Class OracleOsonDecoder

java.lang.Object

io.micronaut.serde.LimitingStream

io.micronaut.serde.support.AbstractStreamDecoder

io.micronaut.serde.oracle.jdbc.json.OracleOsonDecoder

All Implemented Interfaces:

Decoder, AutoCloseable

@Internal
public final class OracleOsonDecoder
extends AbstractStreamDecoder

A serde stream decoder that reads Oracle's binary JSON (OSON) in place from a byte array: no DOM, no event objects, no copy of the document. It is the fast path for Oracle JSON columns, where the driver already holds the encoded document (OracleJsonDatum.shareBytes()).

The layout is a header with flags, a field name dictionary, and a tree segment of nodes whose containers hold child field ids and offsets. Knowledge of that layout comes from the published open source python-oracledb driver (Apache / UPL licensed, impl/base/oson.pyx), not from the Oracle JDBC driver, whose license forbids decompilation. Field names are interned through an OracleOsonFieldNameCache so a stream of documents with the same shape allocates no name strings after the first. Requires the AL32UTF8 database character set, which is what Oracle 23ai and later use for JSON.

Dates, timestamps, intervals, binary values and ids are reported as AbstractStreamDecoder.TokenType.OTHER, as the OracleJdbcJsonParserDecoder reports them, so they are never read as numbers. Read as strings they use the formats of the parser path: ISO-8601 dates and timestamps that always carry seconds, durations with a days part, upper case hexadecimal for binary values and lower case for ids. VECTOR values are not supported and fail when read.

Since:

3.3.0

Nested Class Summary

Nested classes/interfaces inherited from class AbstractStreamDecoder

AbstractStreamDecoder.TokenType, AbstractStreamDecoder.ValueDecoder<R>

Nested classes/interfaces inherited from class LimitingStream

LimitingStream.RemainingLimits

Field Summary

Fields inherited from class LimitingStream

DEFAULT_LIMITS, DEFAULT_MAXIMUM_DEPTH

Constructor Summary

Constructors

Constructor	Description
OracleOsonDecoder(byte[] data, int offset, int length, LimitingStream.RemainingLimits remainingLimits, CoercionPolicy coercionPolicy, OracleOsonFieldNameCache fieldNameCache)	Creates a decoder positioned on the first token of a document.

Method Summary

Modifier and Type	Method	Description
protected String	coerceScalarToString(AbstractStreamDecoder.TokenType currentToken)	Decode any non-null scalar value (number, string or boolean) to its string representation.
IOException	createDeserializationException(String message, @Nullable Object invalidValue)	Creates an exception for the given message.
protected @Nullable AbstractStreamDecoder.TokenType	currentToken()
byte[]	decodeBinary()	Decodes an OSON binary value, or a string holding hexadecimal, or an array of bytes, as a byte array.
LocalDateTime	decodeLocalDateTime()	Decodes an OSON date or timestamp, or an ISO-8601 string, as a LocalDateTime.
OffsetDateTime	decodeOffsetDateTime()	Decodes an OSON timestamp with time zone, or an ISO-8601 string, as an OffsetDateTime.
ZonedDateTime	decodeZonedDateTime()	Decodes an OSON timestamp with time zone, or an ISO-8601 string, as a ZonedDateTime.
void	finishStructure(boolean consumeLeftElements)
protected Number	getBestNumber()	Decode the current AbstractStreamDecoder.TokenType.NUMBER value as a Number value.
protected BigDecimal	getBigDecimal()	Decode the current AbstractStreamDecoder.TokenType.NUMBER value as a BigDecimal value.
protected BigInteger	getBigInteger()	Decode the current AbstractStreamDecoder.TokenType.NUMBER value as a BigInteger value.
protected boolean	getBoolean()	Decode the current AbstractStreamDecoder.TokenType.BOOLEAN value.
protected String	getCurrentKey()	Get the current object field name.
protected double	getDouble()	Decode the current AbstractStreamDecoder.TokenType.NUMBER value as a double value.
protected long	getLong()	Decode the current AbstractStreamDecoder.TokenType.NUMBER value as a long value.
protected String	getString()	Decode the current AbstractStreamDecoder.TokenType.STRING value.
protected boolean	isCurrentNumberFloat()	Whether the current AbstractStreamDecoder.TokenType.NUMBER token has a fractional part.
protected void	nextToken()	Move to the next token.
protected void	skipChildren()	If we are at a AbstractStreamDecoder.TokenType.START_OBJECT or AbstractStreamDecoder.TokenType.START_ARRAY, skip to the matching AbstractStreamDecoder.TokenType.END_OBJECT or AbstractStreamDecoder.TokenType.END_ARRAY.

Methods inherited from class AbstractStreamDecoder

consumeLeftElements, decodeArbitrary, decodeArray, decodeArray0, decodeBigDecimal, decodeBigInteger, decodeBoolean, decodeBuffer, decodeByte, decodeChar, decodeCustom, decodeCustom, decodeDouble, decodeFloat, decodeInt, decodeKey, decodeLong, decodeNode, decodeNull, decodeNumber, decodeObject, decodeObject0, decodeShort, decodeString, getBestNumberNode, getBigDecimalFromNumber, getCoercionPolicy, getInteger, hasNextArrayValue, preDecodeValue, skipValue, unexpectedToken

Methods inherited from class LimitingStream

childLimits, decreaseDepth, increaseDepth, limitsFromConfiguration, ourLimits

Methods inherited from class Object

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

Methods inherited from interface Decoder

close, decodeArray, decodeBigDecimalNullable, decodeBigIntegerNullable, decodeBinaryNullable, decodeBooleanNullable, decodeByteNullable, decodeCharNullable, decodeDoubleNullable, decodeFloatNullable, decodeIntNullable, decodeLongNullable, decodeNumber, decodeNumberNullable, decodeObject, decodeShortNullable, decodeStringNullable, finishStructure

Constructor Details

OracleOsonDecoder

public OracleOsonDecoder(byte[] data,
 int offset,
 int length,
 LimitingStream.RemainingLimits remainingLimits,
 CoercionPolicy coercionPolicy,
 OracleOsonFieldNameCache fieldNameCache)
                  throws IOException

Creates a decoder positioned on the first token of a document.

Parameters:

data - the OSON document

offset - the offset of the document in data

length - the length of the document

remainingLimits - the nesting limits

coercionPolicy - the coercion policy

fieldNameCache - the field name cache shared between documents

Throws:

IOException - if the bytes are not an OSON document this decoder understands

Method Details

finishStructure

public void finishStructure(boolean consumeLeftElements)
                     throws IOException

Specified by:

finishStructure in interface Decoder

Overrides:

finishStructure in class AbstractStreamDecoder

Parameters:

consumeLeftElements - True to consume left elements

Throws:

IOException - If an unrecoverable error occurs

currentToken

protected @Nullable AbstractStreamDecoder.TokenType currentToken()

Specified by:

currentToken in class AbstractStreamDecoder

Returns:

The current token.

nextToken

protected void nextToken()

Description copied from class: AbstractStreamDecoder

Move to the next token.

Specified by:

nextToken in class AbstractStreamDecoder

getCurrentKey

protected String getCurrentKey()

Description copied from class: AbstractStreamDecoder

Get the current object field name. Only called for AbstractStreamDecoder.TokenType.KEY.

Specified by:

getCurrentKey in class AbstractStreamDecoder

Returns:

The current field key

skipChildren

protected void skipChildren()

Description copied from class: AbstractStreamDecoder

If we are at a AbstractStreamDecoder.TokenType.START_OBJECT or AbstractStreamDecoder.TokenType.START_ARRAY, skip to the matching AbstractStreamDecoder.TokenType.END_OBJECT or AbstractStreamDecoder.TokenType.END_ARRAY. Else, do nothing.

Specified by:

skipChildren in class AbstractStreamDecoder

coerceScalarToString

protected String coerceScalarToString(AbstractStreamDecoder.TokenType currentToken)

Description copied from class: AbstractStreamDecoder

Decode any non-null scalar value (number, string or boolean) to its string representation.

Specified by:

coerceScalarToString in class AbstractStreamDecoder

Parameters:

currentToken - The current token

Returns:

The current value, coerced to a string

getString

protected String getString()

Description copied from class: AbstractStreamDecoder

Decode the current AbstractStreamDecoder.TokenType.STRING value. Called for no other token type.

Specified by:

getString in class AbstractStreamDecoder

Returns:

The String value

getBoolean

protected boolean getBoolean()

Description copied from class: AbstractStreamDecoder

Decode the current AbstractStreamDecoder.TokenType.BOOLEAN value. Called for no other token type.

Specified by:

getBoolean in class AbstractStreamDecoder

Returns:

The boolean value

getLong

protected long getLong()

Description copied from class: AbstractStreamDecoder

Decode the current AbstractStreamDecoder.TokenType.NUMBER value as a long value. Called for no other token type.

Specified by:

getLong in class AbstractStreamDecoder

Returns:

The number value

getDouble

protected double getDouble()

Description copied from class: AbstractStreamDecoder

Decode the current AbstractStreamDecoder.TokenType.NUMBER value as a double value. Called for no other token type.

Specified by:

getDouble in class AbstractStreamDecoder

Returns:

The number value

getBigInteger

protected BigInteger getBigInteger()

Description copied from class: AbstractStreamDecoder

Decode the current AbstractStreamDecoder.TokenType.NUMBER value as a BigInteger value. Called for no other token type.

Specified by:

getBigInteger in class AbstractStreamDecoder

Returns:

The number value

getBigDecimal

protected BigDecimal getBigDecimal()

Description copied from class: AbstractStreamDecoder

Decode the current AbstractStreamDecoder.TokenType.NUMBER value as a BigDecimal value. Called for no other token type.

Specified by:

getBigDecimal in class AbstractStreamDecoder

Returns:

The number value

getBestNumber

protected Number getBestNumber()

Description copied from class: AbstractStreamDecoder

Decode the current AbstractStreamDecoder.TokenType.NUMBER value as a Number value. Called for no other token type.

Specified by:

getBestNumber in class AbstractStreamDecoder

Returns:

The number value

isCurrentNumberFloat

protected boolean isCurrentNumberFloat()

Description copied from class: AbstractStreamDecoder

Whether the current AbstractStreamDecoder.TokenType.NUMBER token has a fractional part. Only called when the configuration forbids reading a floating point number as an integer, so a decoder that never sees that configuration keeps working without implementing it.

The default implementation materialises the number with AbstractStreamDecoder.getBestNumber(). A decoder whose underlying parser consumes the value when it is read, as a forward only BSON reader does, must override this and answer from the token type instead.

Overrides:

isCurrentNumberFloat in class AbstractStreamDecoder

Returns:

true if the current number is a floating point number

createDeserializationException

public IOException createDeserializationException(String message,
 @Nullable Object invalidValue)

Description copied from interface: Decoder

Creates an exception for the given message.

Parameters:

message - The message, never null

invalidValue - The invalid value. Can be null.

Returns:

The exception, never null

decodeBinary

public byte[] decodeBinary()
                    throws IOException

Decodes an OSON binary value, or a string holding hexadecimal, or an array of bytes, as a byte array.

Specified by:

decodeBinary in interface Decoder

Overrides:

decodeBinary in class AbstractStreamDecoder

Returns:

the bytes

Throws:

IOException

decodeLocalDateTime

public LocalDateTime decodeLocalDateTime()

Decodes an OSON date or timestamp, or an ISO-8601 string, as a LocalDateTime.

Returns:

the value

decodeOffsetDateTime

public OffsetDateTime decodeOffsetDateTime()

Decodes an OSON timestamp with time zone, or an ISO-8601 string, as an OffsetDateTime.

Returns:

the value

decodeZonedDateTime

public ZonedDateTime decodeZonedDateTime()

Decodes an OSON timestamp with time zone, or an ISO-8601 string, as a ZonedDateTime.

Returns:

the value