com.caucho.vfs
Class WriteStream

java.lang.Object
  extended by java.io.OutputStream
      extended by com.caucho.vfs.OutputStreamWithBuffer
          extended by com.caucho.vfs.WriteStream
All Implemented Interfaces:
ByteAppendable, LockableStream, java.io.Closeable, java.io.Flushable
Direct Known Subclasses:
NullWriteStream

public class WriteStream
extends OutputStreamWithBuffer
implements LockableStream

A fast bufferered output 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.

OutputStream and Writers are combined. The write routines write bytes and the print routines write characters.

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


Constructor Summary
WriteStream()
          Creates an uninitialized stream.
WriteStream(StreamImpl source)
          Creates a stream and initializes with a specified source.
 
Method Summary
 boolean canWrite()
          Returns true if the buffer allows writes.
 void clearPosition()
          Clears the position for statistics cases like a socket stream.
 void clearWrite()
          Clears the write buffer
 void close()
          Close the stream, first flushing the write buffer.
 void flush()
          Flushes the buffer to the source.
 void flushBuffer()
          Flushes the buffer to the source.
 void flushToDisk()
          Flushes the buffer to the disk
 void free()
          Frees the buffer
 java.lang.Object getAttribute(java.lang.String name)
          Returns a named attribute.
 java.util.Iterator<java.lang.String> getAttributeNames()
          Lists all named attributes.
 byte[] getBuffer()
          Returns the write buffer.
 int getBufferOffset()
          Returns the write offset.
 int getBufferSize()
          Returns the write size.
 boolean getDisableClose()
           
 java.lang.String getEncoding()
          Returns the mime-encoding used for writing.
 java.lang.String getJavaEncoding()
           
 java.lang.String getNewlineString()
          Returns the current string used for println newlines
 Path getPath()
          Returns the Path which opened this stream.
 long getPosition()
          Returns the write position.
 java.io.PrintWriter getPrintWriter()
          Returns a printWriter writing to this stream.
 int getRemaining()
          Returns the bytes remaining in the buffer.
 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)
          Initializes the stream with a given source.
 boolean isClosed()
          Returns true if the stream is closed.
 boolean lock(boolean shared, boolean block)
          Lock the shared advisory lock.
 void log(java.lang.String string)
          Logs a line to the stream.
 void log(java.lang.Throwable exn)
           
 byte[] nextBuffer(int offset)
          Flushes and writes the buffer
 void print(boolean b)
          Prints a boolean.
 void print(char ch)
          Prints the character buffer to the stream.
 void print(char[] buffer)
          Prints the character buffer to the stream.
 void print(char[] buffer, int offset, int length)
          Prints the character buffer to the stream.
 void print(CharSegment segment)
          Prints the character buffer to the stream.
 void print(double d)
          Prints an double
 void print(float f)
          Prints a float.
 void print(int i)
          Prints an integer.
 void print(long i)
          Prints a long.
 void print(java.lang.Object o)
          Prints a double, converted by String.valueOf()
 void print(java.lang.String string)
          Prints a string.
 void print(java.lang.String string, int offset, int length)
          Prints a substring.
 void printLatin1(char[] buffer, int offset, int length)
          Prints the character buffer to the stream encoded as latin1.
 void printLatin1(java.lang.String string)
          Prints a string.
 void printLatin1NoLf(java.lang.String string)
          Prints a string.
 void println()
          Prints a newline
 void println(boolean b)
          Prints a boolean followed by a newline.
 void println(char ch)
          Prints a char followed by a newline.
 void println(char[] buf, int offset, int length)
          Prints a character buffer followed by a newline.
 void println(double d)
          Prints a double followed by a newline.
 void println(float f)
          Prints a float followed by a newline.
 void println(int i)
          Prints an integer followed by a newline.
 void println(long l)
          Prints a long followed by a newline.
 void println(java.lang.Object o)
          Prints an object, converted to a string, followed by a newline.
 void println(java.lang.String string)
          Prints a string buffer followed by a newline.
 void pushFilter(StreamFilter filter)
          Pushes a filter on the top of the stream stack.
 void removeAttribute(java.lang.String name)
          Removes a named attribute.
 void seekEnd(long offset)
          Seeks based on the end
 void seekStart(long pos)
          Seeks based on the start
 void setAttribute(java.lang.String name, java.lang.Object value)
          Sets a named attribute.
 void setBufferOffset(int offset)
          Sets the write offset.
 void setDisableClose(boolean disableClose)
          Disables close.
 void setDisableCloseSource(boolean disableClose)
          Disables close of the underlying source.
 void setEncoding(java.lang.String encoding)
          Sets the character encoding for writing to this stream.
 void setFlushOnNewline(boolean flushOnNewline)
          Some streams, like log streams, should be flushed on every println call.
 void setImplicitFlush(boolean implicitFlush)
           
 void setLocale(java.util.Locale locale)
           
 void setNewlineString(java.lang.String newline)
          Sets the string to use for println newlines
 void setPath(Path path)
          Sets a path name associated with the stream.
 boolean setPosition(long pos)
          Sets the current write position.
 void setReuseBuffer(boolean reuse)
           
 void setSysNewline()
           
static void setSystemNewline(java.lang.String newline)
          For testing, sets the system newlines.
 java.lang.String toString()
           
 boolean unlock()
          Unlock the advisory lock.
 void write(byte[] buf)
          Writes a byte array.
 void write(byte[] buf, int offset, int length)
          Writes a byte array
 void write(int ch)
          Writes a byte.
 void writeFile(Path path)
          Copies a file to the stream.
 long writeStream(java.io.InputStream source)
          Writes the contents of a JDK stream.
 void writeStream(java.io.InputStream source, int totalLength)
          Writes the contents of a JDK stream.
 void writeStream(java.io.Reader reader)
          Writes the contents of a JDK reader.
 void writeStream(StreamImpl source)
          Writes the contents of a JDK stream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

WriteStream

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


WriteStream

public WriteStream(StreamImpl source)
Creates a stream and initializes with a specified source.

Parameters:
source - Underlying source for the stream.
Method Detail

init

public void init(StreamImpl source)
Initializes the stream with a given source.

Parameters:
source - Underlying source for the stream.

setSysNewline

public void setSysNewline()

getSource

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

Returns:
the source

pushFilter

public void pushFilter(StreamFilter filter)
Pushes a filter on the top of the stream stack.

Parameters:
filter - the filter to be added.

canWrite

public boolean canWrite()
Returns true if the buffer allows writes.

LogStreams, used for debugging, use this feature to test if they should write with very little overhead.

 if (dbg.canWrite())
   dbg.log("some debug value " + expensiveDebugCalculation(foo));
 


clearWrite

public void clearWrite()
Clears the write buffer


setReuseBuffer

public void setReuseBuffer(boolean reuse)

getBuffer

public byte[] getBuffer()
Returns the write buffer.

Specified by:
getBuffer in class OutputStreamWithBuffer

getBufferOffset

public int getBufferOffset()
Returns the write offset.

Specified by:
getBufferOffset in class OutputStreamWithBuffer

setBufferOffset

public void setBufferOffset(int offset)
Sets the write offset.

Specified by:
setBufferOffset in class OutputStreamWithBuffer

getBufferSize

public int getBufferSize()
Returns the write size.


getRemaining

public int getRemaining()
Returns the bytes remaining in the buffer.


setImplicitFlush

public void setImplicitFlush(boolean implicitFlush)

write

public void write(int ch)
           throws java.io.IOException
Writes a byte.

Specified by:
write in interface ByteAppendable
Specified by:
write in class java.io.OutputStream
Throws:
java.io.IOException

write

public void write(byte[] buf,
                  int offset,
                  int length)
           throws java.io.IOException
Writes a byte array

Specified by:
write in interface ByteAppendable
Overrides:
write in class java.io.OutputStream
Throws:
java.io.IOException

nextBuffer

public byte[] nextBuffer(int offset)
                  throws java.io.IOException
Flushes and writes the buffer

Specified by:
nextBuffer in class OutputStreamWithBuffer
Returns:
the next buffer
Throws:
java.io.IOException

write

public void write(byte[] buf)
           throws java.io.IOException
Writes a byte array.

Overrides:
write in class java.io.OutputStream
Throws:
java.io.IOException

flush

public void flush()
           throws java.io.IOException
Flushes the buffer to the source.

Specified by:
flush in interface java.io.Flushable
Overrides:
flush in class java.io.OutputStream
Throws:
java.io.IOException

flushToDisk

public void flushToDisk()
                 throws java.io.IOException
Flushes the buffer to the disk

Throws:
java.io.IOException

flushBuffer

public final void flushBuffer()
                       throws java.io.IOException
Flushes the buffer to the source.

Throws:
java.io.IOException

seekStart

public void seekStart(long pos)
               throws java.io.IOException
Seeks based on the start

Throws:
java.io.IOException

seekEnd

public void seekEnd(long offset)
             throws java.io.IOException
Seeks based on the end

Throws:
java.io.IOException

setEncoding

public void setEncoding(java.lang.String encoding)
                 throws java.io.UnsupportedEncodingException
Sets the character encoding for writing to this stream. Encoding can be a Java encoding or a mime-encoding.

Throws:
java.io.UnsupportedEncodingException

setLocale

public void setLocale(java.util.Locale locale)
               throws java.io.UnsupportedEncodingException
Throws:
java.io.UnsupportedEncodingException

getEncoding

public java.lang.String getEncoding()
Returns the mime-encoding used for writing.


getJavaEncoding

public java.lang.String getJavaEncoding()

setFlushOnNewline

public void setFlushOnNewline(boolean flushOnNewline)
Some streams, like log streams, should be flushed on every println call. Embedded newlines, i.e. '\n' in strings, do not trigger a flush.

Parameters:
flushOnNewline - set to true if println flushes.

getNewlineString

public java.lang.String getNewlineString()
Returns the current string used for println newlines


setNewlineString

public void setNewlineString(java.lang.String newline)
Sets the string to use for println newlines


print

public final void print(char[] buffer,
                        int offset,
                        int length)
                 throws java.io.IOException
Prints the character buffer to the stream.

Parameters:
buffer - character buffer to write
offset - offset into the buffer to start writes
length - number of characters to write
Throws:
java.io.IOException

printLatin1

public final void printLatin1(char[] buffer,
                              int offset,
                              int length)
                       throws java.io.IOException
Prints the character buffer to the stream encoded as latin1.

Parameters:
buffer - character buffer to write
offset - offset into the buffer to start writes
length - number of characters to write
Throws:
java.io.IOException

print

public final void print(char ch)
                 throws java.io.IOException
Prints the character buffer to the stream.

Parameters:
ch - char
Throws:
java.io.IOException

print

public final void print(char[] buffer)
                 throws java.io.IOException
Prints the character buffer to the stream.

Parameters:
buffer - character buffer to write
Throws:
java.io.IOException

print

public final void print(CharSegment segment)
                 throws java.io.IOException
Prints the character buffer to the stream.

Parameters:
segment - character buffer to write
Throws:
java.io.IOException

print

public final void print(java.lang.String string)
                 throws java.io.IOException
Prints a string.

Throws:
java.io.IOException

printLatin1

public final void printLatin1(java.lang.String string)
                       throws java.io.IOException
Prints a string.

Throws:
java.io.IOException

printLatin1NoLf

public final void printLatin1NoLf(java.lang.String string)
                           throws java.io.IOException
Prints a string.

Throws:
java.io.IOException

print

public final void print(java.lang.String string,
                        int offset,
                        int length)
                 throws java.io.IOException
Prints a substring.

Parameters:
string - the string to print
offset - starting offset into the string
length - length of the substring to print.
Throws:
java.io.IOException

print

public final void print(boolean b)
                 throws java.io.IOException
Prints a boolean.

Throws:
java.io.IOException

print

public final void print(int i)
                 throws java.io.IOException
Prints an integer.

Throws:
java.io.IOException

print

public final void print(long i)
                 throws java.io.IOException
Prints a long.

Throws:
java.io.IOException

print

public final void print(float f)
                 throws java.io.IOException
Prints a float.

Throws:
java.io.IOException

print

public final void print(double d)
                 throws java.io.IOException
Prints an double

Throws:
java.io.IOException

print

public final void print(java.lang.Object o)
                 throws java.io.IOException
Prints a double, converted by String.valueOf()

Throws:
java.io.IOException

println

public final void println()
                   throws java.io.IOException
Prints a newline

Throws:
java.io.IOException

println

public final void println(char[] buf,
                          int offset,
                          int length)
                   throws java.io.IOException
Prints a character buffer followed by a newline.

Throws:
java.io.IOException

println

public final void println(java.lang.String string)
                   throws java.io.IOException
Prints a string buffer followed by a newline.

Throws:
java.io.IOException

println

public final void println(boolean b)
                   throws java.io.IOException
Prints a boolean followed by a newline.

Throws:
java.io.IOException

println

public final void println(char ch)
                   throws java.io.IOException
Prints a char followed by a newline.

Throws:
java.io.IOException

println

public final void println(int i)
                   throws java.io.IOException
Prints an integer followed by a newline.

Throws:
java.io.IOException

println

public final void println(long l)
                   throws java.io.IOException
Prints a long followed by a newline.

Throws:
java.io.IOException

println

public final void println(float f)
                   throws java.io.IOException
Prints a float followed by a newline.

Throws:
java.io.IOException

println

public final void println(double d)
                   throws java.io.IOException
Prints a double followed by a newline.

Throws:
java.io.IOException

println

public final void println(java.lang.Object o)
                   throws java.io.IOException
Prints an object, converted to a string, followed by a newline.

Throws:
java.io.IOException

getPrintWriter

public java.io.PrintWriter getPrintWriter()
Returns a printWriter writing to this stream.


log

public final void log(java.lang.String string)
Logs a line to the stream. log is essentially println, but it doesn't throw an exception and it always flushes the output.


log

public final void log(java.lang.Throwable exn)

writeStream

public long writeStream(java.io.InputStream source)
                 throws java.io.IOException
Writes the contents of a JDK stream. Essentially this will copy source to the current stream.

Parameters:
source - InputStream to read.
Throws:
java.io.IOException

writeStream

public void writeStream(java.io.Reader reader)
                 throws java.io.IOException
Writes the contents of a JDK reader. Essentially this will copy source to the current stream.

Parameters:
source - InputStream to read.
Throws:
java.io.IOException

writeStream

public void writeStream(java.io.InputStream source,
                        int totalLength)
                 throws java.io.IOException
Writes the contents of a JDK stream. Essentially this will copy source to the current stream.

Parameters:
source - InputStream to read.
Throws:
java.io.IOException

writeStream

public void writeStream(StreamImpl source)
                 throws java.io.IOException
Writes the contents of a JDK stream. Essentially this will copy source to the current stream.

Parameters:
source - InputStream to read.
Throws:
java.io.IOException

writeFile

public void writeFile(Path path)
               throws java.io.IOException
Copies a file to the stream.

Parameters:
path - Path of the file to copy.
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.


getDisableClose

public boolean getDisableClose()

setDisableCloseSource

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


isClosed

public final boolean isClosed()
Returns true if the stream is closed.

Specified by:
isClosed in class OutputStreamWithBuffer

close

public final void close()
                 throws java.io.IOException
Close the stream, first flushing the write buffer.

Specified by:
close in interface java.io.Closeable
Overrides:
close in class java.io.OutputStream
Throws:
java.io.IOException

free

public final void free()
Frees the buffer


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

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

getAttributeNames

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

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.


setPath

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


setSystemNewline

public static void setSystemNewline(java.lang.String newline)
For testing, sets the system newlines.


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

getPosition

public long getPosition()
Returns the write position.


clearPosition

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


setPosition

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

Throws:
java.io.IOException

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object