Package org.apache.juneau.marshall.cbor

Class CborTokenWriter

java.lang.Object

org.apache.juneau.marshall.cbor.CborTokenWriter

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable, RecordWriter, TokenWriter

public class CborTokenWriter
extends Object
implements TokenWriter

Reference implementation of the public TokenWriter surface for the CBOR format (RFC 8949).

Wraps a CborOutputStream and emits **indefinite-length** containers (0xBF for maps, 0x9F for arrays, terminated by 0xFF BREAK) so that the caller doesn't have to know element counts up front — a natural fit for streaming generation.

Notes:

• This class is not thread safe.
• byte[] values dispatch to native CBOR major-type-2 byte strings via CborOutputStream.appendBinary(byte[]), not to a base64 string fallback.
• The writer is purely structural; object swaps and @Schema annotations are NOT applied at the token layer (see TokenWriter.object(Object) for the bridge that does apply them).

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	CborTokenWriter.Settings	Cursor-level settings honored by CborTokenWriter.

Constructor Summary

Constructors

Constructor	Description
CborTokenWriter(OutputStream out)	Constructor with default settings.
CborTokenWriter(OutputStream out, CborTokenWriter.Settings settings)	Constructor with explicit 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.
boolean	isStreaming()	Structural token cursors are always O(1)-memory streamers.
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.
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.
CborTokenWriter	writeSimple(int value)	Emits an opaque simple value.
CborTokenWriter	writeTag(long tagNumber)	Emits a semantic tag prefixing the next value emit.

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

write, writeExt

Constructor Details

CborTokenWriter

public CborTokenWriter(OutputStream out)

Constructor with default settings.

Parameters:

out - The OutputStream to emit CBOR to. Must not be null.

CborTokenWriter

public CborTokenWriter(OutputStream out,
 CborTokenWriter.Settings settings)

Constructor with explicit settings.

Parameters:

out - The OutputStream to emit CBOR to. Must not be null.

settings - The 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.

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.

writeTag

public CborTokenWriter writeTag(long tagNumber)
                         throws IOException

Description copied from interface: TokenWriter

Emits a semantic tag prefixing the next value emit.

Tags compose: writeTag(1).writeTag(2).number(5) writes tag(1)(tag(2)(5)). The tag header is written immediately and does NOT consume a map-key/value or array-element slot; that bookkeeping belongs to the wrapped value emit that follows.

Specified by:

writeTag in interface TokenWriter

Parameters:

tagNumber - The unsigned tag number (carried as a long for the full unsigned 64-bit range).

Returns:

This object.

Throws:

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

writeSimple

public CborTokenWriter writeSimple(int value)
                            throws IOException

Description copied from interface: TokenWriter

Emits an opaque simple value. The corresponding read-side token is TokenType.VALUE_NULL with TokenReader.getSimpleValue().

Specified by:

writeSimple in interface TokenWriter

Parameters:

value - The simple value. Format-specific reserved encodings (e.g. CBOR major-7 codepoints 20-23, 25-27, 31 collide with bool/null/undefined/float/break) must not be used.

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.

isStreaming

public boolean isStreaming()

Description copied from interface: TokenWriter

Structural token cursors are always O(1)-memory streamers.

Specified by:

isStreaming in interface RecordWriter

Specified by:

isStreaming in interface TokenWriter

Returns:

Always true.

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