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 Details

    • OracleJsonFactory

      public OracleJsonFactory()

  • Method Details

    • 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(LocalDateTime value)
      Creates a new JSON timestamp value.
      Parameters:
      value - the timestamp as a LocalDateTime
      Returns:
      the timestamp value

    • createDate

      public OracleJsonDate createDate(LocalDateTime i)
      Creates a new JSON date value.
      Parameters:
      value - the date as a LocalDateTime
      Returns:
      the date value

    • createTimestampTZ

      public OracleJsonTimestampTZ createTimestampTZ(OffsetDateTime i)
      Creates a new JSON timestamp value.
      Parameters:
      value - the timestamp as a OffsetDateTime
      Returns:
      the timestamp value

    • createIntervalDS

      public OracleJsonIntervalDS createIntervalDS(Duration d)
      Creates a new JSON interval value.
      Parameters:
      value - the interval as a Duration
      Returns:
      the interval value

    • createIntervalYM

      public OracleJsonIntervalYM createIntervalYM(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:
      UnsupportedOperationException - if the specified Datum type is not supported
      OracleJsonException - if the specified Datum can not be converted to OracleJsonValue