Package oracle.sql.json

Class OracleJsonFactory

java.lang.Object

oracle.sql.json.OracleJsonFactory

public final class OracleJsonFactory
extends Object

A factory for reading, writing, and creating SQL JSON values. The methods on this factory fall into three categories:

Description	Methods
Methods for reading and writing Oracle binary JSON	createJsonBinaryGenerator(OutputStream) createJsonBinaryValue(ByteBuffer) createJsonBinaryValue(InputStream) createJsonBinaryParser(ByteBuffer) createJsonBinaryParser(InputStream)
Methods for creating new instances of the JSON type object-model	createObject() createObject(OracleJsonObject) createArray() createArray(OracleJsonArray) createString(String) createDecimal(BigDecimal) createDecimal(int) createDecimal(long) createDouble(double) createFloat(float) createTimestamp(LocalDateTime) createTimestampTZ(OffsetDateTime) createDate(LocalDateTime) createBinary(byte[]) createIntervalDS(Duration) createIntervalYM(Period)
Methods for converting values to and from JSON text	createJsonTextGenerator(OutputStream) createJsonTextGenerator(Writer) createJsonTextParser(InputStream) createJsonTextParser(Reader)

The following example generates Oracle binary JSON for the JSON object {"hello":"world"}

  OracleJsonFactory factory = new OracleJsonFactory();
  OracleJsonObject obj = factory.createObject();
  obj.put("hello", "world");
  
  ByteArrayOutputStream out = new ByteArrayOutputStream();
  JsonGenerator binaryGenerator = factory.createJsonBinaryGenerator(out);
  binaryGenerator.write(obj);
  binaryGenerator.close();
  byte[] binaryJson = out.toByteArray();
  

Continuing with this example, the Oracle binary JSON can be read as follows:

  OracleJsonObject bobj = factory.createJsonBinaryValue(ByteBuffer.wrap(binaryJson));
  System.out.println(bobj.getString("hello"));
  

In this example, the returned object (bobj) directly references the underlying Oracle binary JSON (binaryJson). It does not attempt to convert the underlying binary JSON to some other internal data structure. Consequently, the object is immutable and attempts to call mutator methods such as bobj.put(...) will raise an error. To make a modifiable copy of the object, use createObject(OracleJsonObject).

The object can be printed as JSON text using bobj.toString() or by using a JSON text generator:

  OracleJsonGenerator jsonGenerator = factory.createJsonTextGenerator(System.out);
  jsonGenerator.write(bobj);
  jsonGenerator.close();
  

Using a text generator instead of toString() gives more control over how the JSON output is written and reuses memory more efficiently.

This factory does not support parsing JSON text. To parse JSON text use javax.json.Json.createParser() or another third-party JSON parser. The following example shows how to convert JSON text to Oracle binary JSON using a JSON-P parser:

  JsonParser parser = Json.createParser(new StringReader("{\"hello\":\"world\"}"));
  OracleJsonGenerator binaryGenerator = factory.createJsonBinaryGenerator(out);
  binaryGenerator.writeParser(parser);
  binaryGenerator.close();
  parser.close();
  

This factory is thread safe but the objects created from it are not. Temporary memory used by parsers and generators may be pooled and reused by this factory. In general, a single factory may serve an entire application but performance may degrade if many threads access the same factory at once. It may be beneficial, for example, to keep multiple thread-local instances.

Constructor Summary

Constructors

Constructor	Description
OracleJsonFactory()

Method Summary

Modifier and Type	Method	Description
OracleJsonArray	createArray()	Creates a new mutable JSON array.
OracleJsonArray	createArray(OracleJsonArray other)	Creates a mutable copy of a JSON array.
OracleJsonBinary	createBinary(byte[] value)	Creates a new JSON binary value.
OracleJsonValue	createBoolean(boolean value)	Creates a new JSON boolean value.
OracleJsonDate	createDate(java.time.LocalDateTime i)	Creates a new JSON date value.
OracleJsonDecimal	createDecimal(int value)	Creates a new JSON decimal.
OracleJsonDecimal	createDecimal(long value)	Creates a new JSON decimal.
OracleJsonDecimal	createDecimal(BigDecimal value)	Creates a new JSON decimal.
OracleJsonDouble	createDouble(double value)	Creates a new JSON double.
OracleJsonFloat	createFloat(float value)	Creates a new JSON float.
OracleJsonIntervalDS	createIntervalDS(java.time.Duration d)	Creates a new JSON interval value.
OracleJsonIntervalYM	createIntervalYM(java.time.Period p)	Creates a new JSON interval value.
OracleJsonGenerator	createJsonBinaryGenerator(OutputStream out)	Creates a JSON generator to write binary JSON to a byte stream.
OracleJsonParser	createJsonBinaryParser(InputStream in)	Creates a binary JSON parser from the given byte stream.
OracleJsonParser	createJsonBinaryParser(ByteBuffer in)	Creates a binary JSON parser from the given buffer.
OracleJsonValue	createJsonBinaryValue(InputStream in)	Creates a OracleJsonValue from the given binary JSON stream.
OracleJsonValue	createJsonBinaryValue(ByteBuffer in)	Creates a JsonValue from the given binary JSON buffer.
OracleJsonGenerator	createJsonTextGenerator(OutputStream out)	Creates a JSON generator to write JSON text to a byte stream.
OracleJsonGenerator	createJsonTextGenerator(Writer out)	Creates a JSON generator to write JSON to a character stream.
OracleJsonParser	createJsonTextParser(InputStream in)	Creates a JSON text parser from the given byte stream.
OracleJsonParser	createJsonTextParser(Reader in)	Creates a JSON text parser from the given character stream.
OracleJsonValue	createJsonTextValue(InputStream in)	Creates a OracleJsonValue from the given textual JSON stream.
OracleJsonValue	createJsonTextValue(Reader in)	Creates a OracleJsonValue from the given textual JSON stream.
OracleJsonValue	createNull()	Returns OracleJsonValue.NULL.
OracleJsonObject	createObject()	Creates a new mutable JSON object.
OracleJsonObject	createObject(OracleJsonObject other)	Creates a mutable copy of a JSON object.
OracleJsonString	createString(String value)	Creates a new JSON string.
OracleJsonTimestamp	createTimestamp(java.time.LocalDateTime value)	Creates a new JSON timestamp value.
OracleJsonTimestampTZ	createTimestampTZ(java.time.OffsetDateTime i)	Creates a new JSON timestamp value.
OracleJsonValue	createValue(Datum datum)	Creates a new JSON value from a Datum.

Methods inherited from class java.lang.Object

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

Constructor Detail

OracleJsonFactory

public OracleJsonFactory()

Method Detail

createJsonBinaryParser

public OracleJsonParser createJsonBinaryParser(InputStream in)
                                        throws OracleJsonException

Creates a binary JSON parser from the given byte stream. The contents of the byte stream will be fully stored in the heap. JSON values obtained from the parser may directly reference these underlying bytes.

Parameters:

in - stream of binary JSON

Returns:

the created parser

Throws:

OracleJsonException - if an error occurs reading the input

createJsonTextParser

public OracleJsonParser createJsonTextParser(InputStream in)
                                      throws OracleJsonException

Creates a JSON text parser from the given byte stream. The unicode character set of the JSON text will be detected automatically.

Parameters:

in - stream of JSON text

Returns:

the created parser

Throws:

OracleJsonException - if an error occurs reading the input

createJsonTextParser

public OracleJsonParser createJsonTextParser(Reader in)
                                      throws OracleJsonException

Creates a JSON text parser from the given character stream.

Parameters:

in - stream of JSON text

Returns:

the created parser

Throws:

OracleJsonException - if an error occurs reading the input

createJsonBinaryParser

public OracleJsonParser createJsonBinaryParser(ByteBuffer in)
                                        throws OracleJsonException

Creates a binary JSON parser from the given buffer. JSON values returned from the parser may rely on a direct reference to the provided byte buffer. The buffer must not be modified until the parser and any values obtained from it are no longer needed. The parser will not attempt to modify the buffer.

Parameters:

in - the buffer containing binary JSON

Returns:

the created parser

Throws:

OracleJsonException - if an error occurs reading the input

createJsonBinaryValue

public OracleJsonValue createJsonBinaryValue(InputStream in)
                                      throws OracleJsonException

Creates a OracleJsonValue from the given binary JSON stream. This is a convenience method that is semantically equivalent to obtaining a value from a JSON parser as follows:

    try (OracleJsonParser parser = factory.createJsonBinaryParser(in)) {
      parser.next();
      OracleJsonValue value = parser.getValue();
    }
    

This method does close the provided InputStream.

Parameters:

in - stream of binary JSON

Returns:

the JSON value

Throws:

OracleJsonException - if an error occurs reading the input

createJsonTextValue

public OracleJsonValue createJsonTextValue(InputStream in)
                                    throws OracleJsonException

Creates a OracleJsonValue from the given textual JSON stream. This is a convenience method that is semantically equivalent to obtaining a value from a JSON parser as follows:

    try (OracleJsonParser parser = factory.createJsonTextParser(in)) {
      parser.next();
      OracleJsonValue value = parser.getValue();
    }
    

This method does close the provided InputStream.

Parameters:

in - stream of textual JSON

Returns:

the JSON value

Throws:

OracleJsonException - if an error occurs reading the input

createJsonTextValue

public OracleJsonValue createJsonTextValue(Reader in)
                                    throws OracleJsonException

Creates a OracleJsonValue from the given textual JSON stream. This is a convenience method that is semantically equivalent to obtaining a value from a JSON parser as follows:

    try (OracleJsonParser parser = factory.createJsonTextParser(in)) {
      parser.next();
      OracleJsonValue value = parser.getValue();
    }
    

This method does close the provided InputStream.

Parameters:

in - stream of textual JSON

Returns:

the JSON value

Throws:

OracleJsonException - if an error occurs reading the input

createJsonBinaryValue

public OracleJsonValue createJsonBinaryValue(ByteBuffer in)
                                      throws OracleJsonException

Creates a JsonValue from the given binary JSON buffer. This is a convenience method that is semantically equivalent to obtaining a value from a JSON parser as follows:

    try (OracleJsonParser parser = factory.createJsonBinaryParser(in)) {
      parser.next();
      OracleJsonValue value = parser.getValue();
    }
    

The OracleJsonValue returned by this function may directly reference the provide ByteBuffer. The buffer should not be modified until returned OracleJsonValue and all values derived from it are no longer needed.

Parameters:

in - the buffer containing binary JSON

Returns:

the JSON value

Throws:

OracleJsonException - if an error occurs reading the input

createJsonBinaryGenerator

public final OracleJsonGenerator createJsonBinaryGenerator(OutputStream out)

Creates a JSON generator to write binary JSON to a byte stream.

Parameters:

out - i/o stream to which binary JSON is written

Returns:

the created JSON generator

createJsonTextGenerator

public OracleJsonGenerator createJsonTextGenerator(OutputStream out)

Creates a JSON generator to write JSON text to a byte stream. Characters written to the stream are encoded into bytes as UTF8.

Parameters:

out - i/o stream to which UTF8 JSON is written

Returns:

the created JSON generator

createJsonTextGenerator

public OracleJsonGenerator createJsonTextGenerator(Writer out)

Creates a JSON generator to write JSON to a character stream.

Parameters:

out - character stream to which JSON is written

Returns:

the created JSON generator

createObject

public OracleJsonObject createObject()

Creates a new mutable JSON object.

Returns:

the JSON object

createArray

public OracleJsonArray createArray()

Creates a new mutable JSON array.

Returns:

the JSON array

createObject

public OracleJsonObject createObject(OracleJsonObject other)

Creates a mutable copy of a JSON object.

Parameters:

other - the JSON object to copy. May be either mutable or immutable.

Returns:

a mutable JSON object.

createArray

public OracleJsonArray createArray(OracleJsonArray other)

Creates a mutable copy of a JSON array.

Parameters:

other - the JSON array to copy. May be either mutable or immutable.

Returns:

a mutable JSON array.

createString

public OracleJsonString createString(String value)

Creates a new JSON string.

Parameters:

value - the string value

Returns:

a JSON string

createDecimal

public OracleJsonDecimal createDecimal(BigDecimal value)
                                throws OracleJsonException

Creates a new JSON decimal.

Parameters:

value - the decimal value

Returns:

the JSON decimal

Throws:

OracleJsonException - if the specified value can not be converted to a JSON number.

createDecimal

public OracleJsonDecimal createDecimal(int value)

Creates a new JSON decimal.

Parameters:

value - the value as an integer

Returns:

the JSON decimal value

createDecimal

public OracleJsonDecimal createDecimal(long value)

Creates a new JSON decimal.

Parameters:

value - the value as a long

Returns:

the JSON decimal value

createFloat

public OracleJsonFloat createFloat(float value)

Creates a new JSON float.

Parameters:

value - the value as a float

Returns:

the JSON float value

createDouble

public OracleJsonDouble createDouble(double value)

Creates a new JSON double.

Parameters:

value - the value as a double

Returns:

the JSON double value

createBinary

public OracleJsonBinary createBinary(byte[] value)

Creates a new JSON binary value.

Parameters:

value - the value as a byte array

Returns:

the JSON binary value

createBoolean

public OracleJsonValue createBoolean(boolean value)

Creates a new JSON boolean value.

Parameters:

value - the value as a boolean

Returns:

OracleJsonValue.TRUE or OracleJsonValue.FALSE

createNull

public OracleJsonValue createNull()

Returns OracleJsonValue.NULL.

Returns:

the null value

createTimestamp

public OracleJsonTimestamp createTimestamp(java.time.LocalDateTime value)

Creates a new JSON timestamp value.

Parameters:

value - the timestamp as a LocalDateTime

Returns:

the timestamp value

createDate

public OracleJsonDate createDate(java.time.LocalDateTime i)

Creates a new JSON date value.

Parameters:

value - the date as a LocalDateTime

Returns:

the date value

createTimestampTZ

public OracleJsonTimestampTZ createTimestampTZ(java.time.OffsetDateTime i)

Creates a new JSON timestamp value.

Parameters:

value - the timestamp as a OffsetDateTime

Returns:

the timestamp value

createIntervalDS

public OracleJsonIntervalDS createIntervalDS(java.time.Duration d)

Creates a new JSON interval value.

Parameters:

value - the interval as a Duration

Returns:

the interval value

createIntervalYM

public OracleJsonIntervalYM createIntervalYM(java.time.Period p)

Creates a new JSON interval value.

Parameters:

value - the interval as a Period

Returns:

the interval value

createValue

public OracleJsonValue createValue(Datum datum)

Creates a new JSON value from a Datum. Supported Datum types are CHAR, NUMBER, BINARY_DOUBLE, BINARY_FLOAT, RAW, DATE, TIMESTAMP, INTERVALDS, INTERVALYM, and OracleJsonDatum.

Parameters:

datum - the value to convert

Returns:

the JSON value

Throws:

UnsupportedOperationException - if the specified Datum type is not supported

OracleJsonException - if the specified Datum can not be converted to OracleJsonValue