Package org.apache.juneau.marshall.msgpack

Class MsgPackTokenReader

java.lang.Object

org.apache.juneau.marshall.msgpack.MsgPackTokenReader

All Implemented Interfaces:

Closeable, AutoCloseable, RecordReader, TokenReader

public class MsgPackTokenReader
extends Object
implements TokenReader

Reference implementation of the public TokenReader surface for the MessagePack format.

Backed by the existing internal MsgPackInputStream plumbing. MessagePack containers are length-prefixed; this cursor tracks the remaining-element-count per level on a stack and emits END_* when the count is exhausted.

Notes:

• This class is not thread safe.
• The cursor is a true O(1)-memory streaming cursor (isStreaming() == true).

Field Summary

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

MSG_READ_NON_VALUE_STATE

Constructor Summary

Constructors

Constructor	Description
MsgPackTokenReader(ParserPipe pipe)	Constructor with default settings.
MsgPackTokenReader(ParserPipe pipe, MsgPackParserSession session)	Constructor used by MsgPackParserSession.readTokens(Object) to plumb the calling session through.

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.
MsgPackTokenReader	setMaxLength(int value)	Sets the maximum allowed wire-declared length (in bytes) for binary/string payloads read by this cursor.
MsgPackTokenReader	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

MsgPackTokenReader

public MsgPackTokenReader(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.

MsgPackTokenReader

public MsgPackTokenReader(ParserPipe pipe,
 MsgPackParserSession session)
                   throws IOException

Constructor used by MsgPackParserSession.readTokens(Object) to plumb the calling session through.

Parameters:

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

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

Throws:

IOException - If a problem occurred opening the underlying stream.

Method Details

setNativeMode

public MsgPackTokenReader setNativeMode(boolean value)

Enables or disables binary-native opt-in mode.

When enabled, MsgPack ext tokens carry the signed type byte via getExtType(). When disabled (default), the payload still surfaces as TokenType.VALUE_BINARY but the type byte is dropped — identical to the pre-native-mode behavior.

Parameters:

value - true to enable native mode.

Returns:

This object.

setMaxLength

public MsgPackTokenReader setMaxLength(int value)

Sets the maximum allowed wire-declared length (in bytes) for binary/string payloads read by this cursor.

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 length-prefixed 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.