com.caucho.vfs
Class ReadStream

java.lang.Object
  |
  +--java.io.InputStream
        |
        +--com.caucho.vfs.ReadStream

public final class ReadStream
extends java.io.InputStream

A fast bufferered input stream supporting both character and byte data. The underlying stream sources are provided by StreamImpl classes, so all streams have the same API regardless of the underlying implementation.

Dynamic streams, like tcp and http will properly flush writes before reading input. And random access streams, like RandomAccessFile, can use the same API as normal streams.

Most applications will use the Path routines to create their own streams. Specialized applications, like servers, need the capability of recycling streams.


Constructor Summary
ReadStream()
          Creates an uninitialized stream.
ReadStream(StreamImpl source)
          Creates a stream and initializes with a specified source.
ReadStream(StreamImpl source, WriteStream sibling)
          Creates a stream and initializes with a specified source.
 
Method Summary
 int available()
          Compatibility with InputStream.
 boolean canRead()
          Returns true if the stream allows reading.
 void clearRead()
          Clears the read buffer.
 void close()
          Close the stream.
 int fillBuffer()
           
 java.lang.Object getAttribute(java.lang.String name)
          Returns a named attribute.
 java.util.Iterator getAttributeNames()
          Lists all named attributes.
 int getAvailable()
          Returns an estimate of the available bytes.
 byte[] getBuffer()
           
 java.lang.String getEncoding()
          Returns the mime-encoding currently read.
 int getLength()
           
 int getOffset()
           
 Path getPath()
          Returns the Path which opened this stream.
 long getPosition()
          Returns the current read position.
 java.io.Reader getReader()
          Returns a Reader reading to this stream.
 WriteStream getSibling()
           
 StreamImpl getSource()
          Returns the underlying source for the stream.
 java.lang.String getUserPath()
          Returns the user path which opened this stream.
 void init(StreamImpl source, WriteStream sibling)
          Initializes the stream with a given source.
 void pushFilter(StreamFilter filter)
          Pushes a filter on the top of the stream stack.
 int read()
          Returns the next byte or -1 if at the end of file.
 int read(byte[] buf, int offset, int length)
          Reads into a byte array.
 int read(char[] buf, int offset, int length)
          Reads into a character buffer from the stream.
 int read(CharBuffer buf, int length)
          Reads characters from the stream, appending to the character buffer.
 int readAll(byte[] buf, int offset, int length)
          Reads into a byte array.
 int readAll(char[] buf, int offset, int length)
          Reads into a character buffer from the stream.
 int readAll(CharBuffer buf, int length)
          Reads characters from the stream, appending to the character buffer.
 int readChar()
          Reads a character from the stream, returning -1 on end of file.
 java.lang.String readLine()
          Reads a line, returning a string.
 int readLine(char[] buf, int length)
          Reads a line into the character buffer.
 boolean readLine(CharBuffer cb)
          Reads a line into the character buffer.
 java.lang.String readln()
           
 boolean readln(CharBuffer cb)
           
 void removeAttribute(java.lang.String name)
          Removes a named attribute.
 void setAttribute(java.lang.String name, java.lang.Object value)
          Sets a named attribute.
 void setDisableClose(boolean disableClose)
          Disables close.
 void setEncoding(java.lang.String encoding)
          Sets the current read encoding.
 void setOffset(int offset)
           
 void setPath(Path path)
          Sets a path name associated with the stream.
 void setPosition(int pos)
          Returns the sets current read position.
 void setReuseBuffer(boolean reuse)
           
 void setSibling(WriteStream sibling)
           
 long skip(long n)
          Skips the next n bytes.
 java.lang.String toString()
          Returns a printable representation of the read stream.
 void unread()
          Unreads the last byte.
 void writeToStream(java.io.OutputStream os)
          Copies this stream to the output stream.
 void writeToStream(java.io.OutputStream os, int len)
          Writes len bytes to the output stream from this stream.
 void writeToWriter(java.io.Writer out)
          Copies this stream to the output stream.
 
Methods inherited from class java.io.InputStream
mark, markSupported, read, reset
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ReadStream

public ReadStream()
Creates an uninitialized stream. Use init to initialize.

ReadStream

public ReadStream(StreamImpl source)
Creates a stream and initializes with a specified source.
Parameters:
source - Underlying source for the stream.

ReadStream

public ReadStream(StreamImpl source,
                  WriteStream sibling)
Creates a stream and initializes with a specified source.
Parameters:
source - Underlying source for the stream.
sibling - Sibling write stream.
Method Detail

init

public void init(StreamImpl source,
                 WriteStream sibling)
Initializes the stream with a given source.
Parameters:
source - Underlying source for the stream.
sibling - Sibling write stream

setSibling

public void setSibling(WriteStream sibling)

getSibling

public WriteStream getSibling()

getSource

public StreamImpl getSource()
Returns the underlying source for the stream.
Returns:
the source

setReuseBuffer

public void setReuseBuffer(boolean reuse)

pushFilter

public void pushFilter(StreamFilter filter)
Pushes a filter on the top of the stream stack.
Parameters:
filter - the filter to be added.

getBuffer

public byte[] getBuffer()

getOffset

public int getOffset()

getLength

public int getLength()

setOffset

public void setOffset(int offset)

canRead

public boolean canRead()
Returns true if the stream allows reading.

clearRead

public void clearRead()
Clears the read buffer.

getAvailable

public int getAvailable()
                 throws java.io.IOException
Returns an estimate of the available bytes. If a read would not block, it will always return greater than 0.

available

public int available()
              throws java.io.IOException
Compatibility with InputStream.
Overrides:
available in class java.io.InputStream

getPosition

public long getPosition()
Returns the current read position.

setPosition

public void setPosition(int pos)
Returns the sets current read position.

Note: currently unavailable


read

public final int read()
               throws java.io.IOException
Returns the next byte or -1 if at the end of file.
Overrides:
read in class java.io.InputStream

unread

public final void unread()
Unreads the last byte.

skip

public long skip(long n)
          throws java.io.IOException
Skips the next n bytes.
Overrides:
skip in class java.io.InputStream
Parameters:
n - bytes to skip.
Returns:
number of bytes skipped.

read

public final int read(byte[] buf,
                      int offset,
                      int length)
               throws java.io.IOException
Reads into a byte array. read may return less than the maximum bytes even if more bytes are available to read.
Overrides:
read in class java.io.InputStream
Parameters:
buf - byte array
offset - offset into the byte array to start reading
length - maximum byte allowed to read.
Returns:
number of bytes read or -1 on end of file.

readAll

public int readAll(byte[] buf,
                   int offset,
                   int length)
            throws java.io.IOException
Reads into a byte array. readAll will always read length bytes, blocking if necessary, until the end of file is reached.
Parameters:
buf - byte array
offset - offset into the byte array to start reading
length - maximum byte allowed to read.
Returns:
number of bytes read or -1 on end of file.

setEncoding

public void setEncoding(java.lang.String encoding)
                 throws java.io.UnsupportedEncodingException
Sets the current read encoding. The encoding can either be a Java encoding name or a mime encoding.
Parameters:
encoding - name of the read encoding

getEncoding

public java.lang.String getEncoding()
Returns the mime-encoding currently read.

readChar

public final int readChar()
                   throws java.io.IOException
Reads a character from the stream, returning -1 on end of file.

read

public final int read(char[] buf,
                      int offset,
                      int length)
               throws java.io.IOException
Reads into a character buffer from the stream. Like the byte array version, read may return less characters even though more characters are available.
Parameters:
buf - character buffer to fill
offset - starting offset into the character buffer
length - maximum number of characters to read
Returns:
number of characters read or -1 on end of file.

readAll

public int readAll(char[] buf,
                   int offset,
                   int length)
            throws java.io.IOException
Reads into a character buffer from the stream. length characters will always be read until the end of file is reached.
Parameters:
buf - character buffer to fill
offset - starting offset into the character buffer
length - maximum number of characters to read
Returns:
number of characters read or -1 on end of file.

read

public int read(CharBuffer buf,
                int length)
         throws java.io.IOException
Reads characters from the stream, appending to the character buffer.
Parameters:
buf - character buffer to fill
length - maximum number of characters to read
Returns:
number of characters read or -1 on end of file.

readAll

public int readAll(CharBuffer buf,
                   int length)
            throws java.io.IOException
Reads characters from the stream, appending to the character buffer. length characters will always be read until the end of file.
Parameters:
buf - character buffer to fill
length - maximum number of characters to read
Returns:
number of characters read or -1 on end of file.

readln

public final boolean readln(CharBuffer cb)
                     throws java.io.IOException

readLine

public final boolean readLine(CharBuffer cb)
                       throws java.io.IOException
Reads a line into the character buffer. \r\n is converted to \n.
Parameters:
buf - character buffer to fill
Returns:
false on end of file

readLine

public final int readLine(char[] buf,
                          int length)
                   throws java.io.IOException
Reads a line into the character buffer. \r\n is converted to \n.
Parameters:
buf - character buffer to fill
Returns:
-1 or length

readln

public final java.lang.String readln()
                              throws java.io.IOException

readLine

public java.lang.String readLine()
                          throws java.io.IOException
Reads a line, returning a string.

writeToStream

public void writeToStream(java.io.OutputStream os)
                   throws java.io.IOException
Copies this stream to the output stream.
Parameters:
os - destination stream.

writeToStream

public void writeToStream(java.io.OutputStream os,
                          int len)
                   throws java.io.IOException
Writes len bytes to the output stream from this stream.
Parameters:
os - destination stream.
len - bytes to write.

writeToWriter

public void writeToWriter(java.io.Writer out)
                   throws java.io.IOException
Copies this stream to the output stream.
Parameters:
out - destination writer

fillBuffer

public int fillBuffer()
               throws java.io.IOException

setDisableClose

public void setDisableClose(boolean disableClose)
Disables close. Sometimes an application will pass a stream to a client that may close the stream at an inappropriate time. Setting disable close gives the calling routine control over closing the stream.

close

public final void close()
                 throws java.io.IOException
Close the stream.
Overrides:
close in class java.io.InputStream

getAttribute

public java.lang.Object getAttribute(java.lang.String name)
                              throws java.io.IOException
Returns a named attribute. For example, an HTTP stream may use this to return header values.

getAttributeNames

public java.util.Iterator getAttributeNames()
                                     throws java.io.IOException
Lists all named attributes.

setAttribute

public void setAttribute(java.lang.String name,
                         java.lang.Object value)
                  throws java.io.IOException
Sets a named attribute. For example, an HTTP stream may use this to set header values.

removeAttribute

public void removeAttribute(java.lang.String name)
                     throws java.io.IOException
Removes a named attribute.

getPath

public Path getPath()
Returns the Path which opened this stream.

getUserPath

public java.lang.String getUserPath()
Returns the user path which opened this stream.

Parsing routines typically use this for error reporting.


setPath

public void setPath(Path path)
Sets a path name associated with the stream.

getReader

public java.io.Reader getReader()
Returns a Reader reading to this stream.

toString

public java.lang.String toString()
Returns a printable representation of the read stream.
Overrides:
toString in class java.lang.Object