Package org.apache.juneau.marshall.json

Class JsonTokenWriter

java.lang.Object

org.apache.juneau.marshall.json.JsonTokenWriter

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable, RecordWriter, TokenWriter

public class JsonTokenWriter
extends Object
implements TokenWriter

Reference implementation of the public TokenWriter surface for the JSON format.

Emits RFC-8259-compliant JSON. Output style is driven by a small JsonTokenWriter.Settings bundle that mirrors the structurally-applicable subset of JsonSerializer.Builder's formatting flags: useWhitespace, maxIndent, quoteChar, escapeSolidus, and trimStrings. When opened via JsonSerializer.writeTokens(Object) the writer inherits the settings from the calling serializer; constructing the writer directly via JsonTokenWriter(Writer) uses JsonTokenWriter.Settings.DEFAULT (compact, double-quoted, RFC-8259 strict).

Notes:

• This class is not thread safe.
• The writer tracks just enough state to insert structural separators (, between array/object members and : between field names and values). It does not validate event ordering — emitting field twice in a row, for instance, throws.
• The writer is purely structural; object swaps and @Schema annotations have no effect. Use the POJO databind path on JsonSerializer for those.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	JsonTokenWriter.Settings	Output-formatting settings honored by JsonTokenWriter.

Constructor Summary

Constructors

Constructor	Description
JsonTokenWriter(Writer out)	Constructor for a Writer target with default JsonTokenWriter.Settings.
JsonTokenWriter(Writer out, JsonTokenWriter.Settings settings)	Constructor for a Writer target with explicit JsonTokenWriter.Settings.

Method Summary

Modifier and Type	Method	Description
TokenWriter	binary(byte[] value)	Emits a TokenType.VALUE_BINARY event.
TokenWriter	bool(boolean value)	Emits a TokenType.VALUE_BOOLEAN event.
void	close()	Closes the writer, flushing any buffered output first.
TokenWriter	endArray()	Emits a TokenType.END_ARRAY event.
TokenWriter	endObject()	Emits a TokenType.END_OBJECT event.
TokenWriter	fieldName(String name)	Emits a TokenType.FIELD_NAME event for the next field of the enclosing object.
void	flush()	Flushes any buffered output to the underlying stream.
static JsonTokenWriter	forOutput(Object output, JsonTokenWriter.Settings settings)	Internal factory used by JsonSerializer.writeTokens(Object).
TokenWriter	nil()	Emits a TokenType.VALUE_NULL event.
TokenWriter	number(double value)	Emits a TokenType.VALUE_NUMBER event for a double.
TokenWriter	number(long value)	Emits a TokenType.VALUE_NUMBER event for a long.
TokenWriter	number(Number value)	Emits a TokenType.VALUE_NUMBER event for an arbitrary Number.
TokenWriter	number(BigDecimal value)	Emits a TokenType.VALUE_NUMBER event for a BigDecimal.
TokenWriter	number(BigInteger value)	Emits a TokenType.VALUE_NUMBER event for a BigInteger.
TokenWriter	object(Object value)	Emits an arbitrary POJO through the format's structural events.
JsonTokenWriter.Settings	settingsAccess()	Returns the JsonTokenWriter.Settings this writer was configured with.
TokenWriter	startArray()	Emits a TokenType.START_ARRAY event.
TokenWriter	startObject()	Emits a TokenType.START_OBJECT event.
TokenWriter	string(String value)	Emits a TokenType.VALUE_STRING event.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.juneau.marshall.stream.TokenWriter

isStreaming, write, writeExt, writeSimple, writeTag

Constructor Details

JsonTokenWriter

public JsonTokenWriter(Writer out)

Constructor for a Writer target with default JsonTokenWriter.Settings.

Parameters:

out - The writer to emit JSON to. Must not be null.

JsonTokenWriter

public JsonTokenWriter(Writer out,
 JsonTokenWriter.Settings settings)

Constructor for a Writer target with explicit JsonTokenWriter.Settings.

Parameters:

out - The writer to emit JSON to. Must not be null.

settings - The output-formatting settings. Must not be null.

Method Details

startObject

public TokenWriter startObject()
                        throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.START_OBJECT event.

Specified by:

startObject in interface TokenWriter

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

endObject

public TokenWriter endObject()
                      throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.END_OBJECT event.

Specified by:

endObject in interface TokenWriter

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

startArray

public TokenWriter startArray()
                       throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.START_ARRAY event.

Specified by:

startArray in interface TokenWriter

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

endArray

public TokenWriter endArray()
                     throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.END_ARRAY event.

Specified by:

endArray in interface TokenWriter

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

fieldName

public TokenWriter fieldName(String name)
                      throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.FIELD_NAME event for the next field of the enclosing object.

Specified by:

fieldName in interface TokenWriter

Parameters:

name - The field name. Must not be null.

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

string

public TokenWriter string(String value)
                   throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.VALUE_STRING event.

Specified by:

string in interface TokenWriter

Parameters:

value - The value. May be null, in which case a TokenType.VALUE_NULL event is emitted instead.

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

number

public TokenWriter number(Number value)
                   throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.VALUE_NUMBER event for an arbitrary Number.

Specified by:

number in interface TokenWriter

Parameters:

value - The value. May be null, in which case a TokenType.VALUE_NULL event is emitted instead.

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

number

public TokenWriter number(long value)
                   throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.VALUE_NUMBER event for a long.

Specified by:

number in interface TokenWriter

Parameters:

value - The value.

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

number

public TokenWriter number(double value)
                   throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.VALUE_NUMBER event for a double.

Specified by:

number in interface TokenWriter

Parameters:

value - The value.

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

number

public TokenWriter number(BigDecimal value)
                   throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.VALUE_NUMBER event for a BigDecimal.

Specified by:

number in interface TokenWriter

Parameters:

value - The value. May be null, in which case a TokenType.VALUE_NULL event is emitted instead.

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

number

public TokenWriter number(BigInteger value)
                   throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.VALUE_NUMBER event for a BigInteger.

Specified by:

number in interface TokenWriter

Parameters:

value - The value. May be null, in which case a TokenType.VALUE_NULL event is emitted instead.

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

bool

public TokenWriter bool(boolean value)
                 throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.VALUE_BOOLEAN event.

Specified by:

bool in interface TokenWriter

Parameters:

value - The value.

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

nil

public TokenWriter nil()
                throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.VALUE_NULL event.

Specified by:

nil in interface TokenWriter

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

object

public TokenWriter object(Object value)
                   throws IOException

Description copied from interface: TokenWriter

Emits an arbitrary POJO through the format's structural events.

The value is walked via PojoWalker: nulls / scalars / collections / arrays / maps / beans are introspected and re-emitted through this writer's TokenWriter.startObject(), TokenWriter.fieldName(String), TokenWriter.string(String), TokenWriter.number(long), TokenWriter.bool(boolean), TokenWriter.nil(), and TokenWriter.binary(byte[]) methods. Per-format encoding (quoting, indentation, newlines, etc.) is whatever this writer is configured for.

Cursor positioning: the writer must be in a state where a value emit is legal — at root, after a TokenWriter.fieldName(String) call, or inside an array. Calling object(...) from inside an object body without a preceding field name throws IllegalStateException, same as calling TokenWriter.string(String) would.

Default behavior: the default implementation throws UnsupportedOperationException. Format-specific token writers override this by delegating to PojoWalker.walk(TokenWriter, Object).

Swaps and @Schema: this method is purely structural. Object swaps and schema annotations are NOT applied at the token layer — use the POJO databind path on Serializer.write(Object) for those.

Specified by:

object in interface TokenWriter

Parameters:

value - The value to emit. May be null.

Returns:

This object.

Throws:

IOException - If the underlying stream fails.

settingsAccess

public JsonTokenWriter.Settings settingsAccess()

Returns the JsonTokenWriter.Settings this writer was configured with.

Exposed for delegating wrappers (e.g. JsonlTokenWriter) that need to read the underlying writer's walk options when implementing object(Object).

Returns:

The settings. Never null.

binary

public TokenWriter binary(byte[] value)
                   throws IOException

Description copied from interface: TokenWriter

Emits a TokenType.VALUE_BINARY event.

Text formats normally encode the value as base64-encoded TokenType.VALUE_STRING; the exact encoding is format-defined.

Specified by:

binary in interface TokenWriter

Parameters:

value - The value. May be null, in which case a TokenType.VALUE_NULL event is emitted instead.

Returns:

This object.

Throws:

IOException - If a problem occurred writing to the underlying stream.

flush

public void flush()
           throws IOException

Description copied from interface: TokenWriter

Flushes any buffered output to the underlying stream.

Specified by:

flush in interface Flushable

Specified by:

flush in interface RecordWriter

Specified by:

flush in interface TokenWriter

Throws:

IOException - If a problem occurred flushing the underlying stream.

close

public void close()
           throws IOException

Description copied from interface: TokenWriter

Closes the writer, flushing any buffered output first.

Implementations should be idempotent — closing a closed writer is a no-op.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Specified by:

close in interface RecordWriter

Specified by:

close in interface TokenWriter

Throws:

IOException

forOutput

public static JsonTokenWriter forOutput(Object output,
 JsonTokenWriter.Settings settings)
                                 throws IOException

Internal factory used by JsonSerializer.writeTokens(Object). Coerces the supported output types (Writer / OutputStream) into a Writer the JSON encoder can target.

Parameters:

output - The output object.

settings - The output-formatting settings.

Returns:

A new JsonTokenWriter writing to the resolved Writer.

Throws:

IOException - If the output type is not supported or could not be opened.