Package oracle.sql.json

Class 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(Instant)
    createDate(Instant)
    createBinary(byte[])
    createIntervalDS(Duration)
    createIntervalYM(Period)
    Methods for converting values to JSON text createJsonTextGenerator(OutputStream)
    createJsonTextGenerator(Writer)

    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.

  • <section role="region">

    • Constructor Detail

      • OracleJsonFactory

        public OracleJsonFactory()
    </section> <section role="region">

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

      • createDate

        public OracleJsonDate createDate​(java.time.Instant i)
        Creates a new JSON date value.
        Parameters:
        value - the date as an Instant
        Returns:
        the date 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
    </section>