Module io.jstach.jstachio

Package io.jstach.jstachio.output

@NonNullByDefault package io.jstach.jstachio.output

Output utility classes particularly for leveraging pre-encoding efficiently and shared integration logic for plugging into web application frameworks.

Blocking frameworks

LimitEncodedOutput

For blocking frameworks LimitEncodedOutput provides a good solution over just writing to directly to the body OutputStream if the length of output is needed apriori while avoiding running out of memory for rare large outputs (in those cases the length will not be determined before writing to the stream).

Non-blocking frameworks

BufferedEncodedOutput

Because JStachio does not have a reactive model the only reliable solution is to completely buffer the output. As long as template output is not that large this is generally not much of a problem as memory is often cheap and GC pretty fast these days. For this model BufferedEncodedOutput can allow the complete output to be read either as a ByteBuffer or a channel.

By type

In some cases frameworks only allow returning output by a certain type. Below is rough guide based on type.

Output choice by type

Type	Strategy
ByteBuffer or byte[]	Use ByteBufferEncodedOutput.
OutputStream	If size must ALWAYS be known before writing use ChunkEncodedOutput. If size must be known for MOST outputs use LimitEncodedOutput. If size is not needed use Output.EncodedOutput.of(java.io.OutputStream, java.nio.charset.Charset).
Writer	Use Renderer.execute(Object, Appendable) (pre-encoding will not be used).
ReadableByteChannel or Iterable<byte[]>	Use ChunkEncodedOutput. The iterable of byte[] can also be converted to a reactive data type.

See Also:

• BufferedEncodedOutput
• ThresholdEncodedOutput

API Note

As with most IO the classes in this package are not thread safe unless noted.

Related Packages

Package	Description
io.jstach.jstachio	JStachio Core Runtime API.
io.jstach.jstachio.context	JStachio extended Mustache context support for context stack as well as Map and JSON tree like models.
io.jstach.jstachio.escapers	Builtin Escapers.
io.jstach.jstachio.formatters	Builtin Formatters.
io.jstach.jstachio.spi	JStachio Service Provider extension points API.

Class	Description
BufferedEncodedOutput	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.
ByteBufferedOutputStream	A custom OutputStream that is designed for generating bytes from pre-encoded output as well as reused carefully either by threadlocals or some other pooling mechanism.
ByteBufferEncodedOutput	An encoded output optimized for producing a single ByteBuffer.
ChunkEncodedOutput<T>	Maintains the encoded output in an iterable of chunks of type T that is optimized for BufferedEncodedOutput.asReadableByteChannel().
ForwardingEncodedOutput<E extends Exception>	An encoded output that forwards all calls to a delegate.
ForwardingOutput<E extends Exception>	An encoded output that forwards all calls to a delegate.
LimitEncodedOutput<T,E extends Exception>	This output will limit buffering by byte count and then fallback to pushing to the downstream output type of T once limit is exceeded.
OutputConsumer<E extends Exception>	An OutputStream like callback.
OutputFactory<T,E extends Exception>	Creates output like objects with a buffer size.
ThresholdEncodedOutput<T,E extends Exception>	This abstract output will limit buffering by byte count and then fallback to pushing to the downstream output type of T once limit is exceeded.
ThresholdEncodedOutput.OutputStreamThresholdEncodedOutput	An OutputStream backed buffer limited encoded output.