org.osgl.util

Interface Output

All Superinterfaces:

Appendable, AutoCloseable, Closeable, Flushable

All Known Implementing Classes:

BufferedOutput, OutputStreamOutput, WriterOutput

public interface Output
extends Appendable, Closeable, Flushable

Output is an Appendable with extra methods to append ByteBuffer and byte[].

An Output is a stateful object, it can be opened and closed.

An Output instance can create OutputStream or Writer based on itself.

Note the behavior differences between an Output and an Appendable: when a char sequence is null, nothing will be appended to the Output while a literal null will be appended to the Appendable

Depending on implementation Output might be or not be thread safe.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	Output.Adaptors

Method Summary

Modifier and Type	Method and Description
Output	append(byte b) Appends a byte to this Output.
Output	append(byte[] bytes) Appends a byte array to this Output.
Output	append(byte[] bytes, int start, int end) Appends a subsequence of the specified byte array to this Output.
Output	append(ByteBuffer buffer) Appends the specified buffer into this Appendable.
Output	append(char c) Appends the specified character to this Output.
Output	append(CharSequence csq) Appends the specified character sequence to this Output.
Output	append(CharSequence csq, int start, int end) Appends a subsequence of the specified character sequence to this Output.
OutputStream	asOutputStream() Create an OutputStream based on this Output instance.
Writer	asWriter() Create an Writer based on this Output instance.
void	close() Close this Output instance.
void	flush() Flushes the output.
void	open() Prepare this Output instance for appending.

Method Detail

open

void open()

Prepare this Output instance for appending. If any append method is called before calling open(), then open() will be called implicitly before appending happens.

close

void close()

Close this Output instance. Call to any append method after the Output is closed will result in IllegalStateException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

flush

void flush()

Flushes the output. If the output has saved any characters from the various append() methods in a buffer, write them immediately to their intended destination. Then, if that destination is another character or byte stream, flush it. Thus one flush() invocation will flush all the buffers in a chain of Writers and OutputStreams.

If the intended destination of this output is an abstraction provided by the underlying operating system, for example a file, then flushing the stream guarantees only that bytes previously written to the stream are passed to the operating system for writing; it does not guarantee that they are actually written to a physical device such as a disk drive.

Specified by:

flush in interface Flushable

append

Output append(CharSequence csq)

Appends the specified character sequence to this Output.

Depending on which class implements the character sequence csq, the entire sequence may not be appended. For instance, if csq is a CharBuffer then the subsequence to append is defined by the buffer’s position and limit.

Specified by:

append in interface Appendable

Parameters:

csq - The character sequence to append. If csq is null, then nothing will be appended

Returns:

A reference to this Output

append

Output append(CharSequence csq,
              int start,
              int end)

Appends a subsequence of the specified character sequence to this Output.

An invocation of this method of the form out.append(csq, start, end) when csq is not null, behaves in exactly the same way as the invocation

    out.append(csq.subSequence(start, end)) 

Specified by:

append in interface Appendable

Parameters:

csq - The character sequence from which a subsequence will be appended. If csq is null, then nothing will be appended.

start - The index of the first character in the subsequence

end - The index of the character following the last character in the subsequence

Returns:

A reference to this Output

Throws:

IndexOutOfBoundsException - If start or end are negative, start is greater than end, or end is greater than csq.length()

append

Output append(char c)

Appends the specified character to this Output.

Specified by:

append in interface Appendable

Parameters:

c - The character to append

Returns:

A reference to this Output

append

Output append(byte[] bytes)

Appends a byte array to this Output.

Parameters:

bytes - The byte array will be appended.

Returns:

A reference to this Output

append

Output append(byte[] bytes,
              int start,
              int end)

Appends a subsequence of the specified byte array to this Output.

An invocation of this method of the form out.append(bytes, start, end) when bytes is not null, behaves in exactly the same way as the invocation

    out.append(csq.subSequence(start, end)) 

Parameters:

bytes - The byte array from which a subsequence will be appended. If bytes is null, then nothing will be appended.

start - The index of the first character in the subsequence

end - The index of the character following the last character in the subsequence

Returns:

A reference to this Output

Throws:

IndexOutOfBoundsException - If start or end are negative, start is greater than end, or end is greater than csq.length()

append

Output append(byte b)

Appends a byte to this Output.

Parameters:

b - A byte will be appended.

Returns:

A reference to this Output.

append

Output append(ByteBuffer buffer)

Appends the specified buffer into this Appendable.

Parameters:

buffer - The buffer to append.

Returns:

A reference to this Output

asOutputStream

OutputStream asOutputStream()

Create an OutputStream based on this Output instance.

Calling to this method before calling to any other method including asOutputStream() itself will result in IllegalStateException.

Returns:

an OutputStream reference backed by this Output.

asWriter

Writer asWriter()

Create an Writer based on this Output instance.

Calling to this method before calling to any other method including asOutputStream() itself will result in IllegalStateException.

Returns:

an Writer reference backed by this Output.