com.caucho.vfs
Class ReadStream

java.lang.Object
  extended by java.io.InputStream
      extended by com.caucho.vfs.ReadStream
All Implemented Interfaces:
LockableStream, java.io.Closeable

public final class ReadStream
extends java.io.InputStream
implements LockableStream

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.


Nested Class Summary
 class ReadStream.StreamReader
           
 
Field Summary
static int READ_TIMEOUT
           
static int ZERO_COPY_SIZE
           
 
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 clearPosition()
          Clears the position for statistics cases like a socket stream.
 void clearRead()
          Clears the read buffer.
 void clearReadTime()
          Returns the last read-time.
 void close()
          Close the stream.
 int fillBuffer()
          Fills the buffer from the underlying stream.
 boolean fillIfLive(long timeout)
          Fills the buffer with a timed read, testing for the end of file.
 int fillWithTimeout(long timeout)
          Fills the buffer with a non-blocking read.
 java.lang.Object getAttribute(java.lang.String name)
          Returns a named attribute.
 java.util.Iterator<java.lang.String> getAttributeNames()
          Lists all named attributes.
 int getAvailable()
          Returns an estimate of the available bytes.
 byte[] getBuffer()
           
 int getBufferAvailable()
          Returns true if data in the buffer is available.
 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 read position.
 java.io.Reader getReader()
          Returns a Reader reading to this stream.
 long getReadTime()
          Returns the last read-time.
 WriteStream getSibling()
           
 StreamImpl getSource()
          Returns the underlying source for the stream.
 java.lang.String getURL()
          Returns the user path which opened this 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.
 boolean lock(boolean shared, boolean block)
          Lock the shared advisory lock.
 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.
 int readInt()
          Reads a 4-byte network encoded integer
 java.lang.String readLine()
          Reads a line, returning a string.
 int readLine(char[] buf, int length)
          Reads a line into the character buffer.
 int readLine(char[] buf, int length, boolean isChop)
          Reads a line into the character buffer.
 boolean readLine(CharBuffer cb)
          Reads a line into the character buffer.
 boolean readLine(CharBuffer cb, boolean isChop)
          Reads a line into the character buffer.
 java.lang.String readLineNoChop()
          Reads a line, returning a string.
 java.lang.String readln()
          Reads a line from the stream, returning a string.
 boolean readln(CharBuffer cb)
          Fills the buffer with the next line from the input stream.
 long readLong()
          Reads an 8-byte network encoded long
 boolean readNonBlock()
          Fills the buffer with a non-blocking read.
 int readUTF8ByByteLength(char[] buffer, int offset, int byteLength)
          Reads a utf-8 string
 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 setDisableCloseSource(boolean disableClose)
          Disables closing of the underlying source.
 void setEnableReadTime(boolean isEnable)
          Enables setting the read time on every reads.
 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.
 boolean setPosition(long pos)
          Sets the current read position.
 void setReuseBuffer(boolean reuse)
           
 void setSibling(WriteStream sibling)
           
 void setSource(StreamImpl source)
           
 long skip(long n)
          Skips the next n bytes.
 java.lang.String toString()
          Returns a printable representation of the read stream.
 boolean unlock()
          Unlock the advisory lock.
 void unread()
          Unreads the last byte.
 boolean waitForRead()
          Waits for data to be available.
 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
 

Field Detail

ZERO_COPY_SIZE

public static int ZERO_COPY_SIZE

READ_TIMEOUT

public static final int READ_TIMEOUT
See Also:
Constant Field Values
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

setSource

public void setSource(StreamImpl 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)

getPosition

public long getPosition()
Returns the read position.


getReadTime

public long getReadTime()
Returns the last read-time.


clearReadTime

public void clearReadTime()
Returns the last read-time.


setEnableReadTime

public void setEnableReadTime(boolean isEnable)
Enables setting the read time on every reads.


setPosition

public boolean setPosition(long pos)
                    throws java.io.IOException
Sets the current read position.

Throws:
java.io.IOException

clearPosition

public void clearPosition()
Clears the position for statistics cases like a socket stream.


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.

Throws:
java.io.IOException

getBufferAvailable

public int getBufferAvailable()
                       throws java.io.IOException
Returns true if data in the buffer is available.

Throws:
java.io.IOException

available

public int available()
              throws java.io.IOException
Compatibility with InputStream.

Overrides:
available in class java.io.InputStream
Throws:
java.io.IOException

read

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

Specified by:
read in class java.io.InputStream
Throws:
java.io.IOException

unread

public final void unread()
Unreads the last byte.


waitForRead

public final boolean waitForRead()
                          throws java.io.IOException
Waits for data to be available.

Throws:
java.io.IOException

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.
Throws:
java.io.IOException

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.
Throws:
java.io.IOException

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.
Throws:
java.io.IOException

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
Throws:
java.io.UnsupportedEncodingException

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.

Throws:
java.io.IOException

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.
Throws:
java.io.IOException

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.
Throws:
java.io.IOException

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.
Throws:
java.io.IOException

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.
Throws:
java.io.IOException

readln

public final java.lang.String readln()
                              throws java.io.IOException
Reads a line from the stream, returning a string.

Throws:
java.io.IOException

readLine

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

Throws:
java.io.IOException

readLineNoChop

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

Throws:
java.io.IOException

readln

public final boolean readln(CharBuffer cb)
                     throws java.io.IOException
Fills the buffer with the next line from the input stream.

Returns:
true on success, false on end of file.
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
Throws:
java.io.IOException

readLine

public final boolean readLine(CharBuffer cb,
                              boolean isChop)
                       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
Throws:
java.io.IOException

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.
length - number of characters to fill.
Returns:
-1 on end of file or the number of characters read.
Throws:
java.io.IOException

readLine

public final int readLine(char[] buf,
                          int length,
                          boolean isChop)
                   throws java.io.IOException
Reads a line into the character buffer. \r\n is converted to \n.

Parameters:
buf - character buffer to fill.
length - number of characters to fill.
Returns:
-1 on end of file or the number of characters read.
Throws:
java.io.IOException

readInt

public int readInt()
            throws java.io.IOException
Reads a 4-byte network encoded integer

Throws:
java.io.IOException

readLong

public long readLong()
              throws java.io.IOException
Reads an 8-byte network encoded long

Throws:
java.io.IOException

readUTF8ByByteLength

public int readUTF8ByByteLength(char[] buffer,
                                int offset,
                                int byteLength)
                         throws java.io.IOException
Reads a utf-8 string

Throws:
java.io.IOException

writeToStream

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

Parameters:
os - destination stream.
Throws:
java.io.IOException

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.
Throws:
java.io.IOException

writeToWriter

public void writeToWriter(java.io.Writer out)
                   throws java.io.IOException
Copies this stream to the output stream.

Parameters:
out - destination writer
Throws:
java.io.IOException

fillBuffer

public int fillBuffer()
               throws java.io.IOException
Fills the buffer from the underlying stream.

Throws:
java.io.IOException

readNonBlock

public boolean readNonBlock()
                     throws java.io.IOException
Fills the buffer with a non-blocking read.

Throws:
java.io.IOException

fillWithTimeout

public int fillWithTimeout(long timeout)
                    throws java.io.IOException
Fills the buffer with a non-blocking read.

Parameters:
timeout - the timeout in milliseconds for the next data
Returns:
true on data or end of file, false on timeout
Throws:
java.io.IOException

fillIfLive

public boolean fillIfLive(long timeout)
                   throws java.io.IOException
Fills the buffer with a timed read, testing for the end of file. Used for cases like comet to test if the read stream has closed.

Parameters:
timeout - the timeout in milliseconds for the next data
Returns:
true on data or timeout, false on end of file
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.


setDisableCloseSource

public void setDisableCloseSource(boolean disableClose)
Disables closing of the underlying source.


close

public final void close()
Close the stream.

Specified by:
close in interface java.io.Closeable
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.

Throws:
java.io.IOException

getAttributeNames

public java.util.Iterator<java.lang.String> getAttributeNames()
                                                       throws java.io.IOException
Lists all named attributes.

Throws:
java.io.IOException

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.

Throws:
java.io.IOException

removeAttribute

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

Throws:
java.io.IOException

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.


getURL

public java.lang.String getURL()
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

lock

public boolean lock(boolean shared,
                    boolean block)
Description copied from interface: LockableStream
Lock the shared advisory lock. This method will create a shared "read" lock when the shared argument is true and an exclusive "write" lock when the shared argument is false. If the block argument is false then this call will not block if the lock can't be obtained.

Specified by:
lock in interface LockableStream

unlock

public boolean unlock()
Description copied from interface: LockableStream
Unlock the advisory lock. Return true if a lock was held, false otherwise.

Specified by:
unlock in interface LockableStream