Package oracle.sql.json

## Class OracleJsonFactory

- java.lang.Object
- - oracle.sql.json.OracleJsonFactory

    public final class OracleJsonFactory
    extends java.lang.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
`OracleJsonFactory()`

### Method Summary

All Methods Instance Methods Concrete Methods
`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​(java.math.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​(java.io.OutputStream out)` Creates a JSON generator to write binary JSON to a byte stream.
`OracleJsonParser` `createJsonBinaryParser​(java.io.InputStream in)` Creates a binary JSON parser from the given byte stream.
`OracleJsonParser` `createJsonBinaryParser​(java.nio.ByteBuffer in)` Creates a binary JSON parser from the given buffer.
`OracleJsonValue` `createJsonBinaryValue​(java.io.InputStream in)` Creates a `OracleJsonValue` from the given binary JSON stream.
`OracleJsonValue` `createJsonBinaryValue​(java.nio.ByteBuffer in)` Creates a `JsonValue` from the given binary JSON buffer.
`OracleJsonGenerator` `createJsonTextGenerator​(java.io.OutputStream out)` Creates a JSON generator to write JSON text to a byte stream.
`OracleJsonGenerator` `createJsonTextGenerator​(java.io.Writer out)` Creates a JSON generator to write JSON to a character stream.
`OracleJsonParser` `createJsonTextParser​(java.io.InputStream in)` Creates a JSON text parser from the given byte stream.
`OracleJsonParser` `createJsonTextParser​(java.io.Reader in)` Creates a JSON text parser from the given character stream.
`OracleJsonValue` `createJsonTextValue​(java.io.InputStream in)` Creates a `OracleJsonValue` from the given textual JSON stream.
`OracleJsonValue` `createJsonTextValue​(java.io.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​(java.lang.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.
`OracleJsonVector` `createVector​(byte[] vector)` Creates a new JSON vector.
`OracleJsonVector` `createVector​(double[] vector)` Creates a new JSON vector.
`OracleJsonVector` `createVector​(float[] vector)` Creates a new JSON vector.

### 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​(java.io.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​(java.io.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​(java.io.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​(java.nio.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​(java.io.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​(java.io.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​(java.io.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​(java.nio.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​(java.io.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​(java.io.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​(java.io.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​(java.lang.String value)

Creates a new JSON string.

Parameters:
  `value` - the string value
Returns:
  a JSON string

#### createDecimal

    public OracleJsonDecimal createDecimal​(java.math.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

#### createVector

    public OracleJsonVector createVector​(float[] vector)

Creates a new JSON vector.

Parameters:
  `value` - the vector as an array of floats
Returns:
  the vector

#### createVector

    public OracleJsonVector createVector​(double[] vector)

Creates a new JSON vector.

Parameters:
  `value` - the vector as an array of doubles
Returns:
  the vector

#### createVector

    public OracleJsonVector createVector​(byte[] vector)

Creates a new JSON vector.

Parameters:
  `value` - the vector as an array of 8-bit integers
Returns:
  the vector

#### createValue

    public OracleJsonValue createValue​(Datum datum)

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

Parameters:
  `datum` - the value to convert
Returns:
  the JSON value
Throws:
  `java.lang.UnsupportedOperationException` - if the specified Datum type is not supported
  `OracleJsonException` - if the specified Datum can not be converted to OracleJsonValue