package java.io;

/**
 * Abstract class for reading character streams. The only methods that a subclass must implement are
 * read(char[], int, int) and close(). Most subclasses, however, will override some of the methods
 * defined here in order to provide higher efficiency, additional functionality, or both.
 *
 * @see InputStreamReader
 * @see Writer
 */
public abstract class Reader implements Readable, Closeable {

    /**
     * Creates a new character-stream reader whose critical sections will synchronize on the reader
     * itself.
     */
    protected Reader() {
        throw new RuntimeException();
    }

    /**
     * Creates a new character-stream reader whose critical sections will synchronize on the given
     * object.
     *
     * @param lock
     *        The Object to synchronize on.
     */
    protected Reader(Object lock) {
        throw new RuntimeException();
    }

    /**
     * Closes the stream and releases any system resources associated with it. Once the stream has been
     * closed, further read(), ready(), mark(), reset(), or skip() invocations will throw an
     * IOException. Closing a previously closed stream has no effect.
     *
     * @exception IOException
     *            If an I/O error occurs
     */
    public abstract void close() throws IOException;

    /**
     * Marks the present position in the stream. Subsequent calls to reset() will attempt to reposition
     * the stream to this point. Not all character-input streams support the mark() operation.
     *
     * @param readAheadLimit
     *        Limit on the number of characters that may be read while still preserving the mark. After
     *        reading this many characters, attempting to reset the stream may fail.
     *
     * @exception IOException
     *            If the stream does not support mark(), or if some other I/O error occurs
     */
    public void mark(int readAheadLimit) throws IOException {
        throw new RuntimeException();
    }

    /**
     * Tells whether this stream supports the mark() operation. The default implementation always
     * returns false. Subclasses should override this method.
     *
     * @return true if and only if this stream supports the mark operation.
     */
    public boolean markSupported() {
        throw new RuntimeException();
    }

    /**
     * Reads a single character. This method will block until a character is available, an I/O error
     * occurs, or the end of the stream is reached.
     *
     * <p>
     * Subclasses that intend to support efficient single-character input should override this method.
     *
     * @return The character read, as an integer in the range 0 to 65535 (<code>0x00-0xffff</code>), or -1
     *         if the end of the stream has been reached
     *
     * @exception IOException
     *            If an I/O error occurs
     */
    public int read() throws IOException {
        throw new RuntimeException();
    }

    /**
     * Reads characters into an array. This method will block until some input is available, an I/O
     * error occurs, or the end of the stream is reached.
     *
     * @param cbuf
     *        Destination buffer
     *
     * @return The number of characters read, or -1 if the end of the stream has been reached
     *
     * @exception IOException
     *            If an I/O error occurs
     */
    public int read(char[] cbuf) throws IOException {
        throw new RuntimeException();
    }

    /**
     * Reads characters into a portion of an array. This method will block until some input is
     * available, an I/O error occurs, or the end of the stream is reached.
     *
     * @param cbuf
     *        Destination buffer
     * @param off
     *        Offset at which to start storing characters
     * @param len
     *        Maximum number of characters to read
     *
     * @return The number of characters read, or -1 if the end of the stream has been reached
     *
     * @exception IOException
     *            If an I/O error occurs
     */
    public abstract int read(char[] cbuf, int off, int len) throws IOException;

    /**
     * Tells whether this stream is ready to be read.
     *
     * @return True if the next read() is guaranteed not to block for input, false otherwise. Note that
     *         returning false does not guarantee that the next read will block.
     *
     * @exception IOException
     *            If an I/O error occurs
     */
    public boolean ready() throws IOException {
        throw new RuntimeException();
    }

    /**
     * Resets the stream. If the stream has been marked, then attempt to reposition it at the mark. If
     * the stream has not been marked, then attempt to reset it in some way appropriate to the
     * particular stream, for example by repositioning it to its starting point. Not all character-input
     * streams support the reset() operation, and some support reset() without supporting mark().
     *
     * @exception IOException
     *            If the stream has not been marked, or if the mark has been invalidated, or if the
     *            stream does not support reset(), or if some other I/O error occurs
     */
    public void reset() throws IOException {
        throw new RuntimeException();
    }

    /**
     * Skips characters. This method will block until some characters are available, an I/O error
     * occurs, or the end of the stream is reached.
     *
     * @param n
     *        The number of characters to skip
     *
     * @return The number of characters actually skipped
     *
     * @exception IllegalArgumentException
     *            If <code>n</code> is negative.
     * @exception IOException
     *            If an I/O error occurs
     */
    public long skip(long n) throws IOException {
        throw new RuntimeException();
    }
}