AppendableOutputStream (spf4j 8.5.26-SNAPSHOT API)

java.lang.Object
- java.io.OutputStream
- - org.spf4j.io.AppendableOutputStream

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

Direct Known Subclasses:

WriterOutputStream
```
@CleanupObligation
public class AppendableOutputStream
extends OutputStream
```
OutputStream implementation that transforms a byte stream to a character stream using a specified character set encoding and writes the resulting stream to a Writer. The stream is transformed using a CharsetDecoder object, guaranteeing that all character set encodings supported by the JRE are handled correctly.
The output of the CharsetDecoder is buffered using a fixed size buffer. This implies that the data is written to the underlying Writer in chunks that are no larger than the size of this buffer. By default, the buffer is flushed only when it overflows or when flush() or close() is called. In general there is therefore no need to wrap the underlying Writer in a BufferedWriter. WriterOutputStream can also be instructed to flush the buffer after each write operation. In this case, all available data is written immediately to the underlying Writer, implying that the current position of the Writer is correlated to the current position of the AppendableOutputStream.
AppendableOutputStream implements the inverse transformation of OutputStreamWriter; in the following example, writing to out2 would have the same result as writing to out directly (provided that the byte sequence is legal with respect to the character set encoding):
```
 OutputStream out = ...
 Charset cs = ...
 OutputStreamWriter writer = new OutputStreamWriter(out, cs);
 AppendableOutputStream out2 = new AppendableOutputStream(writer, cs);
```
WriterOutputStream implements the same transformation as InputStreamReader, except that the control flow is reversed: both classes transform a byte stream into a character stream, but InputStreamReader pulls data from the underlying stream, while AppendableOutputStream pushes it to the underlying stream.
Note that while there are use cases where there is no alternative to using this class, very often the need to use this class is an indication of a flaw in the design of the code. This class is typically used in situations where an existing API only accepts an OutputStream object, but where the stream is known to represent character data that must be decoded for further use.
Instances of AppendableOutputStream are not thread safe.
Since:

7.2.25

See Also:

ReaderInputStream

Field Summary

Fields
Modifier and Type Field and Description

protected CharBuffer decoderOut
CharBuffer used as output for the decoder.

Fields
Modifier and Type	Field and Description
`protected CharBuffer`	`decoderOut` CharBuffer used as output for the decoder.

Constructor Summary

Constructors
Constructor and Description
`AppendableOutputStream(Appendable writer, Charset charset)` Constructs a new `WriterOutputStream` with a default output buffer size of 1024 characters.
`AppendableOutputStream(Appendable writer, CharsetDecoder decoder)` Constructs a new `WriterOutputStream` with a default output buffer size of 1024 characters.
`AppendableOutputStream(Appendable writer, CharsetDecoder decoder, int bufferSize)` Constructs a new `WriterOutputStream`.
`AppendableOutputStream(Appendable writer, Charset charset, int bufferSize)` Constructs a new `WriterOutputStream`.
`AppendableOutputStream(Appendable writer, String charsetName)` Constructs a new `WriterOutputStream` with a default output buffer size of 1024 characters.
`AppendableOutputStream(Appendable writer, String charsetName, int bufferSize)` Constructs a new `WriterOutputStream`.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`close()` Close the stream.
`void`	`flush()` Flush the stream.
`protected void`	`flushOutput()` Flush the output.
`protected void`	`processInput(boolean endOfInput)` Decode the contents of the input ByteBuffer into a CharBuffer.
`String`	`toString()`
`void`	`write(byte[] b)` Write bytes from the specified byte array to the stream.
`void`	`write(byte[] b, int poff, int plen)` Write bytes from the specified byte array to the stream.
`void`	`write(int b)` Write a single byte to the stream.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - decoderOut
```
protected CharBuffer decoderOut
```
    CharBuffer used as output for the decoder. It should be somewhat larger as we write from this buffer to the underlying Writer.
- Constructor Detail
  - AppendableOutputStream
```
public AppendableOutputStream(Appendable writer,
                              CharsetDecoder decoder)
```
    Constructs a new WriterOutputStream with a default output buffer size of 1024 characters. The output buffer will only be flushed when it overflows or when flush() or close() is called.
    
    Parameters:
    
    writer - the target Writer
    
    decoder - the charset decoder
    
    Since:
    
    2.1
  - AppendableOutputStream
```
public AppendableOutputStream(Appendable writer,
                              CharsetDecoder decoder,
                              int bufferSize)
```
    Constructs a new WriterOutputStream.
    
    Parameters:
    
    writer - the target Writer
    
    decoder - the charset decoder
    
    bufferSize - the size of the output buffer in number of characters
    
    Since:
    
    2.1
  - AppendableOutputStream
```
public AppendableOutputStream(Appendable writer,
                              Charset charset,
                              int bufferSize)
```
    Constructs a new WriterOutputStream.
    
    Parameters:
    
    writer - the target Writer
    
    charset - the charset encoding
    
    bufferSize - the size of the output buffer in number of characters
  - AppendableOutputStream
```
public AppendableOutputStream(Appendable writer,
                              Charset charset)
```
    Constructs a new WriterOutputStream with a default output buffer size of 1024 characters. The output buffer will only be flushed when it overflows or when flush() or close() is called.
    
    Parameters:
    
    writer - the target Writer
    
    charset - the charset encoding
  - AppendableOutputStream
```
public AppendableOutputStream(Appendable writer,
                              String charsetName,
                              int bufferSize)
```
    Constructs a new WriterOutputStream.
    
    Parameters:
    
    writer - the target Writer
    
    charsetName - the name of the charset encoding
    
    bufferSize - the size of the output buffer in number of characters
  - AppendableOutputStream
```
public AppendableOutputStream(Appendable writer,
                              String charsetName)
```
    Constructs a new WriterOutputStream with a default output buffer size of 1024 characters. The output buffer will only be flushed when it overflows or when flush() or close() is called.
    
    Parameters:
    
    writer - the target Writer
    
    charsetName - the name of the charset encoding
- Method Detail
  - write
```
public void write(byte[] b,
                  int poff,
                  int plen)
           throws IOException
```
    Write bytes from the specified byte array to the stream.
    
    Overrides:
    
    write in class OutputStream
    
    Parameters:
    
    b - the byte array containing the bytes to write
    
    poff - the start offset in the byte array
    
    plen - the number of bytes to write
    
    Throws:
    
    IOException - if an I/O error occurs
  - write
```
public final void write(byte[] b)
                 throws IOException
```
    Write bytes from the specified byte array to the stream.
    
    Overrides:
    
    write in class OutputStream
    
    Parameters:
    
    b - the byte array containing the bytes to write
    
    Throws:
    
    IOException - if an I/O error occurs
  - write
```
public final void write(int b)
                 throws IOException
```
    Write a single byte to the stream.
    
    Specified by:
    
    write in class OutputStream
    
    Parameters:
    
    b - the byte to write
    
    Throws:
    
    IOException - if an I/O error occurs
  - flush
```
public void flush()
           throws IOException
```
    Flush the stream. Any remaining content accumulated in the output buffer will be written to the underlying Writer. After that Writer.flush() will be called.
    
    Specified by:
    
    flush in interface Flushable
    
    Overrides:
    
    flush in class OutputStream
    
    Throws:
    
    IOException - if an I/O error occurs
  - close
```
@DischargesObligation
public void close()
                                 throws IOException
```
    Close the stream. Any remaining content accumulated in the output buffer will be written to the underlying Writer. After that Writer.close() will be called.
    
    Specified by:
    
    close in interface Closeable
    
    Specified by:
    
    close in interface AutoCloseable
    
    Overrides:
    
    close in class OutputStream
    
    Throws:
    
    IOException - if an I/O error occurs
  - processInput
```
protected void processInput(boolean endOfInput)
                     throws IOException
```
    Decode the contents of the input ByteBuffer into a CharBuffer.
    
    Parameters:
    
    endOfInput - indicates end of input
    
    Throws:
    
    IOException - if an I/O error occurs
  - flushOutput
```
protected void flushOutput()
                    throws IOException
```
    Flush the output.
    
    Throws:
    
    IOException - if an I/O error occurs
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object

Class AppendableOutputStream

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

decoderOut

Constructor Detail

AppendableOutputStream

AppendableOutputStream

AppendableOutputStream

AppendableOutputStream

AppendableOutputStream

AppendableOutputStream

Method Detail

write

write

write

flush

close

processInput

flushOutput

toString