OracleJsonFactory (Oracle Database JDBC Java API Reference)

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 and Description

OracleJsonFactory()

Constructors
Constructor and Description
`OracleJsonFactory()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and 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(BigDecimal value)` Creates a new JSON decimal.
`OracleJsonDecimal`	`createDecimal(int value)` Creates a new JSON decimal.
`OracleJsonDecimal`	`createDecimal(long 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(ByteBuffer in)` Creates a binary JSON parser from the given buffer.
`OracleJsonParser`	`createJsonBinaryParser(InputStream in)` Creates a binary JSON parser from the given byte stream.
`OracleJsonValue`	`createJsonBinaryValue(ByteBuffer in)` Creates a `JsonValue` from the given binary JSON buffer.
`OracleJsonValue`	`createJsonBinaryValue(InputStream in)` Creates a `OracleJsonValue` from the given binary JSON stream.
`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

Class OracleJsonFactory

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

OracleJsonFactory

Method Detail

createJsonBinaryParser

createJsonTextParser

createJsonTextParser

createJsonBinaryParser

createJsonBinaryValue

createJsonTextValue

createJsonTextValue

createJsonBinaryValue

createJsonBinaryGenerator

createJsonTextGenerator

createJsonTextGenerator

createObject

createArray

createObject

createArray

createString

createDecimal

createDecimal

createDecimal

createFloat

createDouble

createBinary

createBoolean

createNull

createTimestamp

createDate

createTimestampTZ

createIntervalDS

createIntervalYM

createValue