Package org.apache.juneau.marshall.cbor

Class CborTokenReader

java.lang.Object

org.apache.juneau.marshall.cbor.CborTokenReader

All Implemented Interfaces:

Closeable, AutoCloseable, RecordReader, TokenReader

public class CborTokenReader
extends Object
implements TokenReader

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

Backed by the existing internal CborInputStream plumbing. CBOR's wire format is already token-shaped (major-type encoded data items), so this cursor maps almost directly onto CborInputStream.readDataType().

Notes:

• This class is not thread safe.
• The cursor is a true O(1)-memory streaming cursor (isStreaming() == true).
• The cursor is purely structural; object swaps and @Schema annotations have no effect. Use the POJO databind path on CborParser for those.

Field Summary

Fields inherited from interface org.apache.juneau.marshall.stream.TokenReader

MSG_READ_NON_VALUE_STATE

Constructor Summary

Constructors

Constructor	Description
CborTokenReader(ParserPipe pipe)	Constructor with default settings.
CborTokenReader(ParserPipe pipe, CborParserSession session)	Constructor used by CborParserSession.readTokens(Object) to plumb the calling session through so that read(Class) can delegate to the CBOR databind path.

Method Summary

Modifier and Type	Method	Description
boolean	canRead()	Returns true if TokenReader.read(Class) is currently callable on this cursor — i.e. the cursor is positioned at a value boundary.
void	close()	Closes the underlying stream.
byte[]	getBinary()	Returns the current binary value.
boolean	getBool()	Returns the current boolean value.
TokenType	getCurrentToken()	Returns the current token type without advancing.
int	getDepth()	Returns the current depth of the cursor.
int	getExtType()	Returns the typed-binary type byte for the current token.
String	getFieldName()	Returns the field name when the current token is TokenType.FIELD_NAME.
BinaryNativeKind	getNativeKind()	Returns the binary-native classification of the current token.
Number	getNumber()	Returns the current numeric value as a parsed Number.
String	getNumberLexeme()	Returns the original numeric lexeme for the current numeric token.
int	getSimpleValue()	Returns the opaque simple value for the current token.
String	getString()	Returns the current scalar value as a string.
long	getTag(int index)	Returns the semantic tag at the specified position in the tag stack.
int	getTagCount()	Returns the number of semantic tags wrapping the current token.
boolean	isStreaming()	Structural token cursors are always O(1)-memory streamers.
TokenType	next()	Advances the cursor to the next token.
<T> T	read(Class<T> type)	Consumes the upcoming value (object, array, or scalar) and binds it to a POJO via the format's existing parser.
<T> T	read(Type type, Type... args)	Same as TokenReader.read(Class) but accepts a parameterized Type and optional type arguments (the same shape as Parser.read(Object, Type, Type...)).
<T> T	read(ClassMeta<T> type)	Same as TokenReader.read(Class) but accepts a pre-resolved ClassMeta.
CborTokenReader	setMaxLength(int value)	Sets the maximum allowed wire-declared length (in bytes) for byte/text strings read by this cursor.
CborTokenReader	setMaxTagNestingDepth(int value)	Sets the maximum number of nested CBOR semantic tags this cursor will unwrap before throwing a ParseException.
CborTokenReader	setNativeMode(boolean value)	Enables or disables binary-native opt-in mode.
void	skipChildren()	Skips over the children of the current structural token.

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.RecordReader

iterator, stream

Constructor Details

CborTokenReader

public CborTokenReader(ParserPipe pipe)
                throws IOException

Constructor with default settings.

Parameters:

pipe - The parser input pipe. Must not be null.

Throws:

IOException - If a problem occurred opening the underlying stream.

CborTokenReader

public CborTokenReader(ParserPipe pipe,
 CborParserSession session)
                throws IOException

Constructor used by CborParserSession.readTokens(Object) to plumb the calling session through so that read(Class) can delegate to the CBOR databind path.

Parameters:

pipe - The parser input pipe. Must not be null.

session - The CborParserSession for read(Class) delegation, or null to disable read.

Throws:

IOException - If a problem occurred opening the underlying stream.

Method Details

setMaxTagNestingDepth

public CborTokenReader setMaxTagNestingDepth(int value)

Sets the maximum number of nested CBOR semantic tags this cursor will unwrap before throwing a ParseException.

Defaults to DEFAULT_MAX_TAG_NESTING_DEPTH (64). A chain of more than this many tags wrapping a single value causes next() to throw rather than risk a StackOverflowError.

Parameters:

value - The new maximum nesting depth. Must be >= 0.

Returns:

This object.

setNativeMode

public CborTokenReader setNativeMode(boolean value)

Enables or disables binary-native opt-in mode.

When enabled, CBOR semantic tags are captured on the tag stack rather than discarded (surface them via getTagCount() / getTag(int)), and CBOR simple values surface their int via getSimpleValue(). When disabled (default), tags are silently unwrapped and simple values collapse to TokenType.VALUE_NULL with no metadata — identical to the pre-native-mode behavior.

Parameters:

value - true to enable native mode.

Returns:

This object.

setMaxLength

public CborTokenReader setMaxLength(int value)

Sets the maximum allowed wire-declared length (in bytes) for byte/text strings read by this cursor.

Applies to the length caps enforced while decoding definite- and indefinite-length strings. The cursor is intentionally NOT bounded by an element-count cap for arrays/maps — it is an O(1)-memory streaming cursor and never materializes containers, so it accepts large definite-length containers. Values <= 0 disable the maximum-length cap (the negative-length check still applies).

Parameters:

value - The maximum length in bytes.

Returns:

This object.

next

public TokenType next()
               throws IOException,
ParseException

Description copied from interface: TokenReader

Advances the cursor to the next token.

Specified by:

next in interface TokenReader

Returns:

The token type of the new current token, or TokenType.END_OF_STREAM when the underlying input is exhausted. Never returns TokenType.NOT_AVAILABLE — that value is reserved for the initial pre-next() state.

Throws:

IOException - If a problem occurred reading from the underlying stream.

ParseException - If the input is malformed for the format.

getCurrentToken

public TokenType getCurrentToken()

Description copied from interface: TokenReader

Returns the current token type without advancing.

Specified by:

getCurrentToken in interface TokenReader

Returns:

The current token type. Returns TokenType.NOT_AVAILABLE before the first call to TokenReader.next(), and TokenType.END_OF_STREAM once the stream is exhausted.

getDepth

public int getDepth()

Description copied from interface: TokenReader

Returns the current depth of the cursor.

Depth starts at 0 at the document root and increases by 1 for each TokenType.START_OBJECT / TokenType.START_ARRAY encountered (and decreases on the matching end tokens).

Specified by:

getDepth in interface TokenReader

Returns:

The current depth.

getFieldName

public String getFieldName()

Description copied from interface: TokenReader

Returns the field name when the current token is TokenType.FIELD_NAME.

Specified by:

getFieldName in interface TokenReader

Returns:

The field name.

getString

public String getString()

Description copied from interface: TokenReader

Returns the current scalar value as a string.

Defined for TokenType.VALUE_STRING (the natural value), TokenType.FIELD_NAME (returns the field name), TokenType.VALUE_NUMBER (returns the lexeme), and TokenType.VALUE_BOOLEAN (returns "true"/"false"). For TokenType.VALUE_NULL returns null.

Specified by:

getString in interface TokenReader

Returns:

The string view of the current value.

getNumber

public Number getNumber()
                 throws ParseException

Description copied from interface: TokenReader

Returns the current numeric value as a parsed Number.

Implementations may parse lazily; the returned Number subtype is implementation- and format-defined (e.g. Long / Double / BigDecimal). Use TokenReader.getNumberLexeme() to recover the original textual form.

Specified by:

getNumber in interface TokenReader

Returns:

The parsed numeric value.

Throws:

ParseException - If the lexeme cannot be parsed.

getNumberLexeme

public String getNumberLexeme()

Description copied from interface: TokenReader

Returns the original numeric lexeme for the current numeric token.

For text formats this is the exact substring that produced the number. For binary formats the implementation returns a canonical text rendering of the native numeric token.

Specified by:

getNumberLexeme in interface TokenReader

Returns:

The numeric lexeme.

getBool

public boolean getBool()

Description copied from interface: TokenReader

Returns the current boolean value.

Specified by:

getBool in interface TokenReader

Returns:

The boolean value.

getBinary

public byte[] getBinary()

Description copied from interface: TokenReader

Returns the current binary value.

Binary scalars come from binary formats only (cbor, msgpack, bson, ...). Text formats deliver embedded binary content as base64-encoded TokenType.VALUE_STRING.

Specified by:

getBinary in interface TokenReader

Returns:

The binary value.

canRead

public boolean canRead()
                throws IOException,
ParseException

Description copied from interface: TokenReader

Returns true if TokenReader.read(Class) is currently callable on this cursor — i.e. the cursor is positioned at a value boundary.

This is the natural loop predicate when streaming records:

try (TokenReader r = Json.DEFAULT.readTokens(input)) { r.next(); // consume the opening [ while (r.canRead()) { Item item = r.read(Item.class); process(item); } r.next(); // consume the closing ] }

Specified by:

canRead in interface RecordReader

Specified by:

canRead in interface TokenReader

Returns:

true if the next operation can be read; false if the cursor is positioned at a structural separator, field name, end-container, or end-of-stream.

Throws:

IOException - If a problem occurred peeking at the underlying stream.

ParseException - If the input is malformed for the format.

read

public <T> T read(Class<T> type)
           throws IOException,
ParseException

Description copied from interface: TokenReader

Consumes the upcoming value (object, array, or scalar) and binds it to a POJO via the format's existing parser.

Cursor positioning: the cursor must be in a state where the next call to TokenReader.next() would emit a value-shaped token (i.e. TokenType.START_OBJECT, TokenType.START_ARRAY, or one of the VALUE_* tokens). Calling read consumes that upcoming value wholesale and advances the cursor's depth back to where it was before the value would have started — structurally equivalent to calling TokenReader.next() on a scalar, or TokenReader.next() + TokenReader.skipChildren() on a container.

Do NOT call TokenReader.next() before read. Once the structural opener (e.g. { or [) has been consumed by TokenReader.next(), the underlying parser cannot re-bind the value. The contract is "instead-of-next, not after-next."

Default behavior: the default implementation throws UnsupportedOperationException. Format-specific token readers override this by delegating to their existing *ParserSession at the cursor's current input position and resyncing the cursor's state machine afterward.

Specified by:

read in interface RecordReader

Specified by:

read in interface TokenReader

Type Parameters:

T - The expected return type.

Parameters:

type - The target Java type.

Returns:

The bound POJO.

Throws:

IOException - If a problem occurred reading from the underlying stream.

ParseException - If the input is malformed for the format or cannot be bound to the type.

read

public <T> T read(ClassMeta<T> type)
           throws IOException,
ParseException

Description copied from interface: TokenReader

Same as TokenReader.read(Class) but accepts a pre-resolved ClassMeta.

Specified by:

read in interface RecordReader

Specified by:

read in interface TokenReader

Type Parameters:

T - The expected return type.

Parameters:

type - The target type.

Returns:

The bound POJO.

Throws:

IOException - If a problem occurred reading from the underlying stream.

ParseException - If the input is malformed or cannot be bound to the type.

read

public <T> T read(Type type,
 Type... args)
           throws IOException,
ParseException

Description copied from interface: TokenReader

Same as TokenReader.read(Class) but accepts a parameterized Type and optional type arguments (the same shape as Parser.read(Object, Type, Type...)).

Specified by:

read in interface RecordReader

Specified by:

read in interface TokenReader

Type Parameters:

T - The expected return type.

Parameters:

type - The target type.

args - Optional type arguments for parameterized types.

Returns:

The bound POJO.

Throws:

IOException - If a problem occurred reading from the underlying stream.

ParseException - If the input is malformed or cannot be bound to the type.

skipChildren

public void skipChildren()
                  throws IOException,
ParseException

Description copied from interface: TokenReader

Skips over the children of the current structural token.

If the current token is TokenType.START_OBJECT or TokenType.START_ARRAY, the cursor is advanced to the matching TokenType.END_OBJECT or TokenType.END_ARRAY (i.e. the entire sub-tree is consumed). For any other token this is a no-op.

Specified by:

skipChildren in interface TokenReader

Throws:

IOException - If a problem occurred reading from the underlying stream.

ParseException - If the input is malformed for the format.

isStreaming

public boolean isStreaming()

Description copied from interface: TokenReader

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

Specified by:

isStreaming in interface RecordReader

Specified by:

isStreaming in interface TokenReader

Returns:

Always true.

close

public void close()
           throws IOException

Description copied from interface: TokenReader

Closes the underlying stream.

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

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Specified by:

close in interface RecordReader

Specified by:

close in interface TokenReader

Throws:

IOException

getNativeKind

public BinaryNativeKind getNativeKind()

Description copied from interface: TokenReader

Returns the binary-native classification of the current token.

Specified by:

getNativeKind in interface TokenReader

Returns:

The native kind, or NONE when the current token carries no binary-native metadata. Never null.

getTagCount

public int getTagCount()

Description copied from interface: TokenReader

Returns the number of semantic tags wrapping the current token.

Specified by:

getTagCount in interface TokenReader

Returns:

The tag count (0 when TokenReader.getNativeKind() is not CBOR_TAG).

getTag

public long getTag(int index)

Description copied from interface: TokenReader

Returns the semantic tag at the specified position in the tag stack.

Specified by:

getTag in interface TokenReader

Parameters:

index - The tag position; outermost tag is 0.

Returns:

The tag number.

getExtType

public int getExtType()

Description copied from interface: TokenReader

Returns the typed-binary type byte for the current token.

Specified by:

getExtType in interface TokenReader

Returns:

The signed type byte (range -128..127).

getSimpleValue

public int getSimpleValue()

Description copied from interface: TokenReader

Returns the opaque simple value for the current token.

Specified by:

getSimpleValue in interface TokenReader

Returns:

The simple int.