package org.okip.service.filing.api;

/*
   Copyright (c) 2002 Massachusetts Institute of Technology

   This work, including any software, documents, or other related items
   (the "Work"), is being provided by the copyright holder(s) subject to
   the terms of the MIT OKI(TM) API Definition License. By obtaining,
   using and/or copying this Work, you agree that you have read,
   understand, and will comply with the following terms and conditions of
   the MIT OKI(TM) API Definition License:

   You may use, copy, and distribute unmodified versions of this Work for
   any purpose, without fee or royalty, provided that you include the
   following on ALL copies of the Work that you make or distribute:

    *  The full text of the MIT OKI(TM) API Definition License in a
       location viewable to users of the redistributed Work.

    *  Any pre-existing intellectual property disclaimers, notices, or
       terms and conditions. If none exist, a short notice similar to the
       following should be used within the body of any redistributed
       Work: "Copyright (c) 2002 Massachusetts Institute of Technology. All
       Rights Reserved."

   You may modify or create Derivatives of this Work only for your
   internal purposes. You shall not distribute or transfer any such
   Derivative of this Work to any location or any other third party. For
   purposes of this license, "Derivative" shall mean any derivative of
   the Work as defined in the United States Copyright Act of 1976, such
   as a translation or modification.

   THIS WORK PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
   TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE WORK
   OR THE USE OR OTHER DEALINGS IN THE WORK.

   The name and trademarks of copyright holder(s) and/or MIT may NOT be
   used in advertising or publicity pertaining to the Work without
   specific, written prior permission. Title to copyright in the Work and
   any associated documentation will at all times remain with the
   copyright holders.

*/

/*
 * $Source: /cvs/oki/tech/src/org/okip/service/filing/api/OkiInputStream.java,v $
 */

/**
 * <p>
 * OkiInputStream interface for input stream.
 * </p>
 * <p>
 * Also allows access to native system IO objects, e.g. java's
 * java.io.InputStream.
 * </p>
 * <p>
 * Licensed under the {@link org.okip.service.ApiLicense MIT OKI&#153; API Definition License}.
 *
 * @version $Name:  $ / $Revision: 1.3 $ / $Date: 2002/09/24 23:11:23 $ */
public interface OkiInputStream //extends java.io.Serializable
{

  /**
   * Reads the next byte of data from the IO Object.
   */
  public int read()
  throws FilingException;

  /**
   * Reads up to len bytes of data from the IO Object into an
   * array of bytes.
   */
  public int read(byte[] b, int off, int len)
  throws FilingException;

  /**
   * Reads some number of bytes from the IO Object and stores
   * them into the buffer array b.
   */
  public int read(byte[] b)
  throws FilingException;

  /**
   * Skips over and discards n bytes of data from this IO Object.
   */
  public long skip(long n)
  throws FilingException;

  /**
   * Returns the number of bytes that can be read (or skipped over)
   * from this IO Object without blocking by the next caller of a
   * method for this IO Object.
   */
  public long available()
  throws FilingException;

  /**
   * Closes this IO Object and releases any system resources
   * associated with the IO Object.
   */
  public void close()
  throws FilingException;

  /**
   * Marks the current position in this input stream. A subsequent call to
   * the <code>reset</code> method repositions this stream at the last marked
   * position so that subsequent reads re-read the same bytes.
   *
   * <p> The <code>readlimit</code> arguments tells this input stream to
   * allow that many bytes to be read before the mark position gets
   * invalidated.
   *
   * <p> The general contract of <code>mark</code> is that, if the method
   * <code>markSupported</code> returns <code>true</code>, the stream somehow
   * remembers all the bytes read after the call to <code>mark</code> and
   * stands ready to supply those same bytes again if and whenever the method
   * <code>reset</code> is called.  However, the stream is not required to
   * remember any data at all if more than <code>readlimit</code> bytes are
   * read from the stream before <code>reset</code> is called.
   *
   * @param   readlimit   the maximum limit of bytes that can be read before
   *                      the mark position becomes invalid.
 * @throws FilingIOException - if an IO error occurs setting the mark
 * @throws UnsupportedFilingOperationException - if mark is not supported in this CabinetFactory implementation.
   */
  public void mark(int readlimit)
  throws FilingException;

  /**
   * Repositions this stream to the position at the time the
   * <code>mark</code> method was last called on this input stream.
   *
   * <p> The general contract of <code>reset</code> is:
   *
   * <p><ul>
   *
   * <li> If the method <code>markSupported</code> returns
   * <code>true</code>, then:
   *
   *     <ul><li> If the method <code>mark</code> has not been called since
   *     the stream was created, or the number of bytes read from the stream
   *     since <code>mark</code> was last called is larger than the argument
   *     to <code>mark</code> at that last call, then a
   *     <code>FilingIOException</code> might be thrown.
   *
   *     <li> If such an <code>IOException</code> is not thrown, then the
   *     stream is reset to a state such that all the bytes read since the
   *     most recent call to <code>mark</code> (or since the start of the
   *     file, if <code>mark</code> has not been called) will be resupplied
   *     to subsequent callers of the <code>read</code> method, followed by
   *     any bytes that otherwise would have been the next input data as of
   *     the time of the call to <code>reset</code>. </ul>
   *
   * <li> If the method <code>markSupported</code> returns
   * <code>false</code>, then:
   *
   *     <ul><li> The call to <code>reset</code> may throw an
   *     <code>IOException</code>.
   *
   *     <li> If an <code>FilingIOException</code> is not thrown,
   *     then the stream is reset to a fixed state that depends on
   *     the particular type of the input stream and how it was
   *     created. The bytes that will be supplied to subsequent
   *     callers of the <code>read</code> method depend on the
   *     particular type of the input stream. </ul></ul>
   *
   *
 * @throws FilingIOException - if an IO error occurs gettting the mark
 * @throws UnsupportedFilingOperationException - if mark is not supported in this CabinetFactory implementation.
 */
  public void reset()
  throws FilingException;

  /**
   * Tests if this input stream supports the <code>mark</code> and
   * <code>reset</code> methods. The <code>markSupported</code> method of
   * <code>InputStream</code> returns <code>false</code>.
   *
   * @return  <code>true</code> if this true type supports the mark and reset
   *          method; <code>false</code> otherwise.
   */
  public boolean markSupported();

  /**
   * Return InputStream in native environment which can be used to
   * access this ByteStore.  In Java, this is a java.io.InputStream
   * object.  From this one may obtain a Reader via InputStreamReader.
   *
   * @return A java.io.InputStream object which may be used to access this
   * ByteStore.
   *
   * @throws FilingPermissionDeniedException - if Factory Owner
   * does not have permission to read this ByteStore.
   * @throws FilingIOException - if an IO error occurs.  */
  public java.io.InputStream getNativeInputStream()
  throws FilingException;
}