< prev index next >
src/java.base/share/classes/java/io/PushbackInputStream.java
Print this page
*** 24,34 ****
*/
package java.io;
/**
! * A <code>PushbackInputStream</code> adds
* functionality to another input stream, namely
* the ability to "push back" or "unread" bytes,
* by storing pushed-back bytes in an internal buffer.
* This is useful in situations where
* it is convenient for a fragment of code
--- 24,34 ----
*/
package java.io;
/**
! * A {@code PushbackInputStream} adds
* functionality to another input stream, namely
* the ability to "push back" or "unread" bytes,
* by storing pushed-back bytes in an internal buffer.
* This is useful in situations where
* it is convenient for a fragment of code
*** 57,68 ****
*/
protected byte[] buf;
/**
* The position within the pushback buffer from which the next byte will
! * be read. When the buffer is empty, <code>pos</code> is equal to
! * <code>buf.length</code>; when the buffer is full, <code>pos</code> is
* equal to zero.
*
* @since 1.1
*/
protected int pos;
--- 57,68 ----
*/
protected byte[] buf;
/**
* The position within the pushback buffer from which the next byte will
! * be read. When the buffer is empty, {@code pos} is equal to
! * {@code buf.length}; when the buffer is full, {@code pos} is
* equal to zero.
*
* @since 1.1
*/
protected int pos;
*** 74,92 ****
if (in == null)
throw new IOException("Stream closed");
}
/**
! * Creates a <code>PushbackInputStream</code>
! * with a pushback buffer of the specified <code>size</code>,
* and saves its argument, the input stream
! * <code>in</code>, for later use. Initially,
* the pushback buffer is empty.
*
* @param in the input stream from which bytes will be read.
* @param size the size of the pushback buffer.
! * @exception IllegalArgumentException if {@code size <= 0}
* @since 1.1
*/
public PushbackInputStream(InputStream in, int size) {
super(in);
if (size <= 0) {
--- 74,92 ----
if (in == null)
throw new IOException("Stream closed");
}
/**
! * Creates a {@code PushbackInputStream}
! * with a pushback buffer of the specified {@code size},
* and saves its argument, the input stream
! * {@code in}, for later use. Initially,
* the pushback buffer is empty.
*
* @param in the input stream from which bytes will be read.
* @param size the size of the pushback buffer.
! * @throws IllegalArgumentException if {@code size <= 0}
* @since 1.1
*/
public PushbackInputStream(InputStream in, int size) {
super(in);
if (size <= 0) {
*** 95,131 ****
this.buf = new byte[size];
this.pos = size;
}
/**
! * Creates a <code>PushbackInputStream</code>
* with a 1-byte pushback buffer, and saves its argument, the input stream
! * <code>in</code>, for later use. Initially,
* the pushback buffer is empty.
*
* @param in the input stream from which bytes will be read.
*/
public PushbackInputStream(InputStream in) {
this(in, 1);
}
/**
* Reads the next byte of data from this input stream. The value
! * byte is returned as an <code>int</code> in the range
! * <code>0</code> to <code>255</code>. If no byte is available
* because the end of the stream has been reached, the value
! * <code>-1</code> is returned. This method blocks until input data
* is available, the end of the stream is detected, or an exception
* is thrown.
*
* <p> This method returns the most recently pushed-back byte, if there is
! * one, and otherwise calls the <code>read</code> method of its underlying
* input stream and returns whatever value that method returns.
*
! * @return the next byte of data, or <code>-1</code> if the end of the
* stream has been reached.
! * @exception IOException if this input stream has been closed by
* invoking its {@link #close()} method,
* or an I/O error occurs.
* @see java.io.InputStream#read()
*/
public int read() throws IOException {
--- 95,131 ----
this.buf = new byte[size];
this.pos = size;
}
/**
! * Creates a {@code PushbackInputStream}
* with a 1-byte pushback buffer, and saves its argument, the input stream
! * {@code in}, for later use. Initially,
* the pushback buffer is empty.
*
* @param in the input stream from which bytes will be read.
*/
public PushbackInputStream(InputStream in) {
this(in, 1);
}
/**
* Reads the next byte of data from this input stream. The value
! * byte is returned as an {@code int} in the range
! * {@code 0} to {@code 255}. If no byte is available
* because the end of the stream has been reached, the value
! * {@code -1} is returned. This method blocks until input data
* is available, the end of the stream is detected, or an exception
* is thrown.
*
* <p> This method returns the most recently pushed-back byte, if there is
! * one, and otherwise calls the {@code read} method of its underlying
* input stream and returns whatever value that method returns.
*
! * @return the next byte of data, or {@code -1} if the end of the
* stream has been reached.
! * @throws IOException if this input stream has been closed by
* invoking its {@link #close()} method,
* or an I/O error occurs.
* @see java.io.InputStream#read()
*/
public int read() throws IOException {
*** 135,162 ****
}
return super.read();
}
/**
! * Reads up to <code>len</code> bytes of data from this input stream into
* an array of bytes. This method first reads any pushed-back bytes; after
! * that, if fewer than <code>len</code> bytes have been read then it
! * reads from the underlying input stream. If <code>len</code> is not zero, the method
* blocks until at least 1 byte of input is available; otherwise, no
! * bytes are read and <code>0</code> is returned.
*
* @param b the buffer into which the data is read.
! * @param off the start offset in the destination array <code>b</code>
* @param len the maximum number of bytes read.
* @return the total number of bytes read into the buffer, or
! * <code>-1</code> if there is no more data because the end of
* the stream has been reached.
! * @exception NullPointerException If <code>b</code> is <code>null</code>.
! * @exception IndexOutOfBoundsException If <code>off</code> is negative,
! * <code>len</code> is negative, or <code>len</code> is greater than
! * <code>b.length - off</code>
! * @exception IOException if this input stream has been closed by
* invoking its {@link #close()} method,
* or an I/O error occurs.
* @see java.io.InputStream#read(byte[], int, int)
*/
public int read(byte[] b, int off, int len) throws IOException {
--- 135,162 ----
}
return super.read();
}
/**
! * Reads up to {@code len} bytes of data from this input stream into
* an array of bytes. This method first reads any pushed-back bytes; after
! * that, if fewer than {@code len} bytes have been read then it
! * reads from the underlying input stream. If {@code len} is not zero, the method
* blocks until at least 1 byte of input is available; otherwise, no
! * bytes are read and {@code 0} is returned.
*
* @param b the buffer into which the data is read.
! * @param off the start offset in the destination array {@code b}
* @param len the maximum number of bytes read.
* @return the total number of bytes read into the buffer, or
! * {@code -1} if there is no more data because the end of
* the stream has been reached.
! * @throws NullPointerException If {@code b} is {@code null}.
! * @throws IndexOutOfBoundsException If {@code off} is negative,
! * {@code len} is negative, or {@code len} is greater than
! * {@code b.length - off}
! * @throws IOException if this input stream has been closed by
* invoking its {@link #close()} method,
* or an I/O error occurs.
* @see java.io.InputStream#read(byte[], int, int)
*/
public int read(byte[] b, int off, int len) throws IOException {
*** 190,204 ****
}
/**
* Pushes back a byte by copying it to the front of the pushback buffer.
* After this method returns, the next byte to be read will have the value
! * <code>(byte)b</code>.
*
! * @param b the <code>int</code> value whose low-order
* byte is to be pushed back.
! * @exception IOException If there is not enough room in the pushback
* buffer for the byte, or this input stream has been closed by
* invoking its {@link #close()} method.
*/
public void unread(int b) throws IOException {
ensureOpen();
--- 190,204 ----
}
/**
* Pushes back a byte by copying it to the front of the pushback buffer.
* After this method returns, the next byte to be read will have the value
! * {@code (byte)b}.
*
! * @param b the {@code int} value whose low-order
* byte is to be pushed back.
! * @throws IOException If there is not enough room in the pushback
* buffer for the byte, or this input stream has been closed by
* invoking its {@link #close()} method.
*/
public void unread(int b) throws IOException {
ensureOpen();
*** 209,226 ****
}
/**
* Pushes back a portion of an array of bytes by copying it to the front
* of the pushback buffer. After this method returns, the next byte to be
! * read will have the value <code>b[off]</code>, the byte after that will
! * have the value <code>b[off+1]</code>, and so forth.
*
* @param b the byte array to push back.
* @param off the start offset of the data.
* @param len the number of bytes to push back.
! * @exception NullPointerException If <code>b</code> is <code>null</code>.
! * @exception IOException If there is not enough room in the pushback
* buffer for the specified number of bytes,
* or this input stream has been closed by
* invoking its {@link #close()} method.
* @since 1.1
*/
--- 209,226 ----
}
/**
* Pushes back a portion of an array of bytes by copying it to the front
* of the pushback buffer. After this method returns, the next byte to be
! * read will have the value {@code b[off]}, the byte after that will
! * have the value {@code b[off+1]}, and so forth.
*
* @param b the byte array to push back.
* @param off the start offset of the data.
* @param len the number of bytes to push back.
! * @throws NullPointerException If {@code b} is {@code null}.
! * @throws IOException If there is not enough room in the pushback
* buffer for the specified number of bytes,
* or this input stream has been closed by
* invoking its {@link #close()} method.
* @since 1.1
*/
*** 234,249 ****
}
/**
* Pushes back an array of bytes by copying it to the front of the
* pushback buffer. After this method returns, the next byte to be read
! * will have the value <code>b[0]</code>, the byte after that will have the
! * value <code>b[1]</code>, and so forth.
*
* @param b the byte array to push back
! * @exception NullPointerException If <code>b</code> is <code>null</code>.
! * @exception IOException If there is not enough room in the pushback
* buffer for the specified number of bytes,
* or this input stream has been closed by
* invoking its {@link #close()} method.
* @since 1.1
*/
--- 234,249 ----
}
/**
* Pushes back an array of bytes by copying it to the front of the
* pushback buffer. After this method returns, the next byte to be read
! * will have the value {@code b[0]}, the byte after that will have the
! * value {@code b[1]}, and so forth.
*
* @param b the byte array to push back
! * @throws NullPointerException If {@code b} is {@code null}.
! * @throws IOException If there is not enough room in the pushback
* buffer for the specified number of bytes,
* or this input stream has been closed by
* invoking its {@link #close()} method.
* @since 1.1
*/
*** 262,272 ****
* pushed back and the value returned by {@link
* java.io.FilterInputStream#available available}.
*
* @return the number of bytes that can be read (or skipped over) from
* the input stream without blocking.
! * @exception IOException if this input stream has been closed by
* invoking its {@link #close()} method,
* or an I/O error occurs.
* @see java.io.FilterInputStream#in
* @see java.io.InputStream#available()
*/
--- 262,272 ----
* pushed back and the value returned by {@link
* java.io.FilterInputStream#available available}.
*
* @return the number of bytes that can be read (or skipped over) from
* the input stream without blocking.
! * @throws IOException if this input stream has been closed by
* invoking its {@link #close()} method,
* or an I/O error occurs.
* @see java.io.FilterInputStream#in
* @see java.io.InputStream#available()
*/
*** 278,295 ****
? Integer.MAX_VALUE
: n + avail;
}
/**
! * Skips over and discards <code>n</code> bytes of data from this
! * input stream. The <code>skip</code> method may, for a variety of
* reasons, end up skipping over some smaller number of bytes,
! * possibly zero. If <code>n</code> is negative, no bytes are skipped.
*
! * <p> The <code>skip</code> method of <code>PushbackInputStream</code>
* first skips over the bytes in the pushback buffer, if any. It then
! * calls the <code>skip</code> method of the underlying input stream if
* more bytes need to be skipped. The actual number of bytes skipped
* is returned.
*
* @param n {@inheritDoc}
* @return {@inheritDoc}
--- 278,295 ----
? Integer.MAX_VALUE
: n + avail;
}
/**
! * Skips over and discards {@code n} bytes of data from this
! * input stream. The {@code skip} method may, for a variety of
* reasons, end up skipping over some smaller number of bytes,
! * possibly zero. If {@code n} is negative, no bytes are skipped.
*
! * <p> The {@code skip} method of {@code PushbackInputStream}
* first skips over the bytes in the pushback buffer, if any. It then
! * calls the {@code skip} method of the underlying input stream if
* more bytes need to be skipped. The actual number of bytes skipped
* is returned.
*
* @param n {@inheritDoc}
* @return {@inheritDoc}
*** 320,345 ****
}
return pskip;
}
/**
! * Tests if this input stream supports the <code>mark</code> and
! * <code>reset</code> methods, which it does not.
*
! * @return <code>false</code>, since this class does not support the
! * <code>mark</code> and <code>reset</code> methods.
* @see java.io.InputStream#mark(int)
* @see java.io.InputStream#reset()
*/
public boolean markSupported() {
return false;
}
/**
* Marks the current position in this input stream.
*
! * <p> The <code>mark</code> method of <code>PushbackInputStream</code>
* does nothing.
*
* @param readlimit the maximum limit of bytes that can be read before
* the mark position becomes invalid.
* @see java.io.InputStream#reset()
--- 320,345 ----
}
return pskip;
}
/**
! * Tests if this input stream supports the {@code mark} and
! * {@code reset} methods, which it does not.
*
! * @return {@code false}, since this class does not support the
! * {@code mark} and {@code reset} methods.
* @see java.io.InputStream#mark(int)
* @see java.io.InputStream#reset()
*/
public boolean markSupported() {
return false;
}
/**
* Marks the current position in this input stream.
*
! * <p> The {@code mark} method of {@code PushbackInputStream}
* does nothing.
*
* @param readlimit the maximum limit of bytes that can be read before
* the mark position becomes invalid.
* @see java.io.InputStream#reset()
*** 347,363 ****
public synchronized void mark(int readlimit) {
}
/**
* Repositions this stream to the position at the time the
! * <code>mark</code> method was last called on this input stream.
*
! * <p> The method <code>reset</code> for class
! * <code>PushbackInputStream</code> does nothing except throw an
! * <code>IOException</code>.
*
! * @exception IOException if this method is invoked.
* @see java.io.InputStream#mark(int)
* @see java.io.IOException
*/
public synchronized void reset() throws IOException {
throw new IOException("mark/reset not supported");
--- 347,363 ----
public synchronized void mark(int readlimit) {
}
/**
* Repositions this stream to the position at the time the
! * {@code mark} method was last called on this input stream.
*
! * <p> The method {@code reset} for class
! * {@code PushbackInputStream} does nothing except throw an
! * {@code IOException}.
*
! * @throws IOException if this method is invoked.
* @see java.io.InputStream#mark(int)
* @see java.io.IOException
*/
public synchronized void reset() throws IOException {
throw new IOException("mark/reset not supported");
*** 368,378 ****
* associated with the stream.
* Once the stream has been closed, further read(), unread(),
* available(), 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 synchronized void close() throws IOException {
if (in == null)
return;
in.close();
--- 368,378 ----
* associated with the stream.
* Once the stream has been closed, further read(), unread(),
* available(), reset(), or skip() invocations will throw an IOException.
* Closing a previously closed stream has no effect.
*
! * @throws IOException if an I/O error occurs.
*/
public synchronized void close() throws IOException {
if (in == null)
return;
in.close();
< prev index next >