Module io.jstach.jstachio

Package io.jstach.jstachio.output

Interface BufferedEncodedOutput

All Superinterfaces:

AutoCloseable, Output<RuntimeException>, Output.CloseableEncodedOutput<RuntimeException>, Output.EncodedOutput<RuntimeException>

All Known Subinterfaces:

ByteBufferEncodedOutput, ChunkEncodedOutput<T>

All Known Implementing Classes:

ByteBufferedOutputStream

public sealed interface BufferedEncodedOutput
extends Output.CloseableEncodedOutput<RuntimeException>
permits ChunkEncodedOutput<T>, ByteBufferEncodedOutput

An encoded output that will store the output in its preferred memory structure and can then be copied to an OutputStream or read from a ReadableByteChannel. The total size() of the output can also be retrieved before being copied which is useful for setting "Content-Length" HTTP header or for allocating buffers.

The major impetus for this interface is needing the length of the output prior to outputing. If the length is not needed before writing then better performance and memory savings can probably be had by just using Output.EncodedOutput.of(OutputStream, Charset).

In general instances will be empty and not have correct results till Template.EncodedTemplate.write(Object, EncodedOutput) is called.

Currently there are two approaches to buffered output:

• ByteBufferEncodedOutput: according to benchmarks on most platforms other than Windows it is more CPU friendly but less memory friendly. It is ideal for platforms where you can return ByteBuffer directly or need to return a byte[]. The default implementation uses a growing array and can be created with ByteBufferEncodedOutput.ofByteArray(Charset, int) and can be reused provided close() is called. Reuse can be useful if using ThreadLocals or some other pooling mechanism.
• ChunkEncodedOutput: according to benchmarks is more optimized for memory savings as well as possible reduction of copying. This approach originated from Rocker's purported "near zero copy".

Regardless one should benchmark each approach to determine which one best fits for their platform. In many cases a custom Output.EncodedOutput that uses the platform's underlying buffer pool will probably yield the best results.

Author:

agentgt

See Also:

• ByteBufferEncodedOutput
• ChunkEncodedOutput

API Note

Methods starting with "as" are a view where as methods starting with "to" (or ending in "To" for the case of transferTo) are a copy. If the output is to be reused "as" methods should be copied or fully used before the output is reused.

Nested Class Summary

Nested classes/interfaces inherited from interface io.jstach.jstachio.Output

Output.CloseableEncodedOutput<E extends Exception>, Output.EncodedOutput<E extends Exception>, Output.StringOutput

Method Summary

Modifier and Type	Method	Description
<E extends Exception> void	accept(OutputConsumer<E> consumer)	Transfers the entire buffered output to a consumer
default void	append(CharSequence s)	Analogous to Appendable.append(CharSequence).
default void	append(String s)	Analogous to Appendable.append(CharSequence) which by default treats the String as a CharSequence.
ReadableByteChannel	asReadableByteChannel()	Represents the encoded output as readable channel.
default int	bufferSizeHint()	The recommend buffer size to use for extracting with asReadableByteChannel() or transferTo(OutputStream).
void	close()	Signals that the buffer should be reset for reuse or destroyed.
default boolean	isReusable()	If this instance can be reused after close() is called.
default LimitEncodedOutput<OutputStream,IOException>	limit(int limit, OutputFactory<OutputStream,IOException> factory)	Decorates this buffer so that buffering is limited to certain amount and will eventually send all output to the OutputStream created by the factory.
static BufferedEncodedOutput	ofChunked(Charset charset)	Create a buffered encoded output backed by a sequence of chunks.
int	size()	Total size in number of bytes of the output.
default byte[]	toByteArray()	Copies the output to a byte array.
default void	transferTo(OutputStream stream)	Transfers the entire buffered output by writing to an OutputStream.

Methods inherited from interface io.jstach.jstachio.Output

append, append, append, append, append, toAppendable

Methods inherited from interface io.jstach.jstachio.Output.EncodedOutput

append, append, charset, write, write

Method Details

size

int size()

Total size in number of bytes of the output.

Returns:

size

See Also:

• bufferSizeHint()

transferTo

default void transferTo(OutputStream stream)
                 throws IOException

Transfers the entire buffered output by writing to an OutputStream.

Parameters:

stream - not null and will not be closed or flushed.

Throws:

IOException - if the stream throws an IOException.

See Also:

• asReadableByteChannel()

API Note

For nonblocking asReadableByteChannel() is generally accepted as the better aproach as it is a pull model.

limit

default LimitEncodedOutput<OutputStream,IOException> limit(int limit,
 OutputFactory<OutputStream,IOException> factory)

Decorates this buffer so that buffering is limited to certain amount and will eventually send all output to the OutputStream created by the factory. The factory will be passed -1 if the limit is exceeded and create will only be called once and only once provided that the returned object is closed.

This method should be called before passed to JStachio and the result is the output that should be passed.

Parameters:

limit - the maximum amount of bytes to buffer.

factory - create the output stream on demand and will always be used before close is called.

Returns:

output that will need to be closed eventually.

See Also:

• LimitEncodedOutput

accept

<E extends Exception> void accept(OutputConsumer<E> consumer)
                           throws E

Transfers the entire buffered output to a consumer

Type Parameters:

E - the exception type

Parameters:

consumer - not null.

Throws:

E - if the consumer throws an exception

See Also:

• asReadableByteChannel()

API Note

For nonblocking asReadableByteChannel() is generally accepted as the better aproach as it is a pull model.

bufferSizeHint

default int bufferSizeHint()

The recommend buffer size to use for extracting with asReadableByteChannel() or transferTo(OutputStream).

Returns:

buffer size to use which by default is size().

asReadableByteChannel

ReadableByteChannel asReadableByteChannel()

Represents the encoded output as readable channel. The channel should be closed when finished to signal reuse or destruction of the buffered output!. To possibly help determine the buffer to use for ReadableByteChannel.read(java.nio.ByteBuffer) one can use bufferSizeHint() or size().

Returns:

channel open and ready to read from at the start of the output.

See Also:

• bufferSizeHint()

toByteArray

default byte[] toByteArray()

Copies the output to a byte array.

Returns:

a copied byte array of the output

append

default void append(String s)

Description copied from interface: Output

Analogous to Appendable.append(CharSequence) which by default treats the String as a CharSequence.

Specified by:

append in interface Output<RuntimeException>

Specified by:

append in interface Output.EncodedOutput<RuntimeException>

Parameters:

s - unlike appendable always non null.

append

default void append(CharSequence s)

Description copied from interface: Output

Analogous to Appendable.append(CharSequence).

Specified by:

append in interface Output<RuntimeException>

Parameters:

s - unlike appendable always non null.

close

void close()

Signals that the buffer should be reset for reuse or destroyed.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Output.CloseableEncodedOutput<RuntimeException>

API Note

This does not throw an IOException on purpose since everything is in memory.

isReusable

default boolean isReusable()

If this instance can be reused after close() is called.

Returns:

true if reuse is allowed by default false is returned.

ofChunked

static BufferedEncodedOutput ofChunked(Charset charset)

Create a buffered encoded output backed by a sequence of chunks.

Parameters:

charset - the expected encoding

Returns:

buffered output