oracle.sql.json

## Interface OracleJsonGenerator

All Superinterfaces:
  AutoCloseable, Closeable, Flushable

    public interface OracleJsonGenerator
    extends Closeable, Flushable

Writes a JSON type value to an output source. A JSON generator starts out in no context. As methods on the generator are called, the context changes. The current context determines which methods may be called next on the generator, as defined below.

The generator can be used to create a value as either a sequence of events or by writing full JSON values (instances of `OracleJsonValue`). For example, the following code creates an instance of `OracleJsonObject` and then uses `OracleJsonGenerator` to write it as binary JSON.

        OracleJsonFactory factory = new OracleJsonFactory();
        OracleJsonObject obj = factory.createObject();
        obj.put("hello", "world");

        ByteArrayOutputStream out = new ByteArrayOutputStream();
        OracleJsonGenerator generator = factory.createJsonBinaryGenerator(out);
        generator.write(obj);
        generator.close();
        byte[] binaryJson = out.toByteArray();

The next example generates the same binary JSON value from a sequence of events:

        ByteArrayOutputStream out = new ByteArrayOutputStream();
        OracleJsonGenerator generator = factory.createJsonBinaryGenerator(out);
        generator.writeStartObject();
        generator.writeKey("hello");
        generator.write("world");
        generator.writeEnd();
        generator.close();
        byte[] binaryJson = out.toByteArray();

### Method Summary

All Methods Instance Methods Abstract Methods
`void` `close()` Closes this generator and frees any resources associated with it.
`void` `flush()` Flushes the underlying output source.
`<T> T` `wrap(Class<T> wrapper)` Returns a JSON-P (javax.json.stream) wrapper around this value.
`OracleJsonGenerator` `write(BigDecimal value)` Writes the specified value as a JSON number.
`OracleJsonGenerator` `write(BigInteger value)` Writes the specified value as a JSON number.
`OracleJsonGenerator` `write(boolean value)` Writes the specified value as JSON true or false.
`OracleJsonGenerator` `write(byte[] value)` Writes the specified value as a SQL/JSON binary value.
`OracleJsonGenerator` `write(double value)` Writes the specified value as a JSON double.
`OracleJsonGenerator` `write(java.time.Duration value)` Writes the specified value as a SQL/JSON day/second interval.
`OracleJsonGenerator` `write(float value)` Writes the specified value as a JSON float.
`OracleJsonGenerator` `write(int value)` Writes the specified value as a JSON number.
`OracleJsonGenerator` `write(java.time.LocalDateTime value)` Writes the specified value as a SQL/JSON timestamp.
`OracleJsonGenerator` `write(long value)` Writes the specified value as a JSON number.
`OracleJsonGenerator` `write(java.time.OffsetDateTime value)` Writes the specified value as a SQL/JSON timestamp with timezone.
`OracleJsonGenerator` `write(OracleJsonValue value)` Writes the specified value.
`OracleJsonGenerator` `write(java.time.Period value)` Writes the specified value as a SQL/JSON year/month interval.
`OracleJsonGenerator` `write(String value)` Writes the specified string value as a JSON string.
`OracleJsonGenerator` `write(String name, BigDecimal value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, BigInteger value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, boolean value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, byte[] value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, double value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, java.time.Duration value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, float value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, int value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, java.time.LocalDateTime value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, long value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, java.time.OffsetDateTime value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String key, OracleJsonValue value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, java.time.Period value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `write(String name, String value)` A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.
`OracleJsonGenerator` `writeEnd()` Writes the end of the current object or array.
`OracleJsonGenerator` `writeId(byte[] value)` Writes the specified value as a SQL/JSON binary value.
`OracleJsonGenerator` `writeKey(String name)` Writes a JSON name/value pair in the current object context.
`OracleJsonGenerator` `writeNull()` Writes JSON null.
`OracleJsonGenerator` `writeNull(String name)` A convenience method that is equivalent to calling `writeKey(name)` and then `writeNull()`.
`OracleJsonGenerator` `writeParser(Object parser)` Writes the events from the specified parser to this generator.
`OracleJsonGenerator` `writeStartArray()` Begins a new JSON array.
`OracleJsonGenerator` `writeStartArray(String name)` A convenience method that is equivalent to calling `writeKey(name)` and then `writeStartArray()`.
`OracleJsonGenerator` `writeStartObject()` Begins a new JSON object.
`OracleJsonGenerator` `writeStartObject(String name)` A convenience method that is equivalent to calling `writeKey(name)` and then `writeStartObject()`.

### Method Detail

#### writeStartObject

    OracleJsonGenerator writeStartObject()

Begins a new JSON object. It starts a new child object context within which JSON name/value pairs can be written to the object.

Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written

#### writeStartObject

    OracleJsonGenerator writeStartObject(String name)

A convenience method that is equivalent to calling `writeKey(name)` and then `writeStartObject()`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### writeStartArray

    OracleJsonGenerator writeStartArray()

Begins a new JSON array. It starts a new child array context within which JSON values can be written to the array.

Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written

#### writeStartArray

    OracleJsonGenerator writeStartArray(String name)

A convenience method that is equivalent to calling `writeKey(name)` and then `writeStartArray()`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### writeKey

    OracleJsonGenerator writeKey(String name)

Writes a JSON name/value pair in the current object context. It starts a field context in which a value may be written.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(OracleJsonValue value)

Writes the specified value.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an field, array, or no context.

#### write

    OracleJsonGenerator write(String key,
                              OracleJsonValue value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(String value)

Writes the specified string value as a JSON string.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written

#### write

    OracleJsonGenerator write(String name,
                              String value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(BigDecimal value)

Writes the specified value as a JSON number.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonDecimal}`, `OracleJsonParser.Event#VALUE_DECIMAL}`

#### write

    OracleJsonGenerator write(String name,
                              BigDecimal value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(BigInteger value)

Writes the specified value as a JSON number.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonDecimal}`, `OracleJsonParser.Event#VALUE_DECIMAL}`

#### write

    OracleJsonGenerator write(String name,
                              BigInteger value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(int value)

Writes the specified value as a JSON number.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonDecimal}`, `OracleJsonParser.Event#VALUE_DECIMAL}`

#### write

    OracleJsonGenerator write(String name,
                              int value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(long value)

Writes the specified value as a JSON number.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonDecimal}`, `OracleJsonParser.Event#VALUE_DECIMAL}`

#### write

    OracleJsonGenerator write(String name,
                              long value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(double value)

Writes the specified value as a JSON double.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonDouble}`, `OracleJsonParser.Event#VALUE_DOUBLE}`

#### write

    OracleJsonGenerator write(String name,
                              double value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(float value)

Writes the specified value as a JSON float.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonFloat}`, `OracleJsonParser.Event#VALUE_FLOAT}`

#### write

    OracleJsonGenerator write(String name,
                              float value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(boolean value)

Writes the specified value as JSON true or false.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonValue.OracleJsonType#TRUE}`, `OracleJsonValue.OracleJsonType#FALSE}`, `OracleJsonParser.Event#VALUE_TRUE}`, `OracleJsonParser.Event#VALUE_FALSE}`

#### write

    OracleJsonGenerator write(String name,
                              boolean value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(java.time.LocalDateTime value)

Writes the specified value as a SQL/JSON timestamp. To write the local date time as a date rather than a timestamp, use `OracleJsonFactory.createDate(LocalDateTime)` and `write(OracleJsonValue)`.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonTimestamp}`, `OracleJsonParser.Event#VALUE_TIMESTAMP}`

#### write

    OracleJsonGenerator write(java.time.OffsetDateTime value)

Writes the specified value as a SQL/JSON timestamp with timezone.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonTimestampTZ}`, `OracleJsonParser.Event#VALUE_TIMESTAMPTZ}`

#### write

    OracleJsonGenerator write(String name,
                              java.time.LocalDateTime value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(String name,
                              java.time.OffsetDateTime value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(java.time.Period value)

Writes the specified value as a SQL/JSON year/month interval.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonIntervalYM}`, `OracleJsonParser.Event#VALUE_INTERVALYM}`

#### write

    OracleJsonGenerator write(String name,
                              java.time.Period value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(java.time.Duration value)

Writes the specified value as a SQL/JSON day/second interval.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonIntervalDS}`, `OracleJsonParser.Event#VALUE_INTERVALDS}`

#### write

    OracleJsonGenerator write(String name,
                              java.time.Duration value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### write

    OracleJsonGenerator write(byte[] value)

Writes the specified value as a SQL/JSON binary value.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonBinary}`, `OracleJsonParser.Event#VALUE_BINARY}`

#### writeId

    OracleJsonGenerator writeId(byte[] value)

Writes the specified value as a SQL/JSON binary value. The value will be annotated as an identifier.

Parameters:
  `value` - the value to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonBinary}`, `OracleJsonParser.Event#VALUE_BINARY}`, `OracleJsonBinary#isId()}`

#### write

    OracleJsonGenerator write(String name,
                              byte[] value)

A convenience method that is equivalent to calling `writeKey(name)` and then `write(value)`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### writeNull

    OracleJsonGenerator writeNull()

Writes JSON null.

Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or it is called in no context when a value has already been written
See Also:
  `OracleJsonValue.OracleJsonType#NULL}`, `OracleJsonParser.Event#VALUE_NULL}`

#### writeNull

    OracleJsonGenerator writeNull(String name)

A convenience method that is equivalent to calling `writeKey(name)` and then `writeNull()`.

Parameters:
  `name` - the name of a JSON field
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is not called within an object context

#### writeEnd

    OracleJsonGenerator writeEnd()

Writes the end of the current object or array. The parent context becomes the new current context.

Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this method is called in no context

#### writeParser

    OracleJsonGenerator writeParser(Object parser)

Writes the events from the specified parser to this generator. The parser can be either an instance of `javax.json.JsonParser` or `OracleJsonParser`. The purpose of this method is to allow events from one type of source to be piped into another type of source. For example, this method can be used to convert JSON text to binary JSON by passing in a JSON text parser to a binary generator.

The method writes the full value for the current event of the specified parser. The parser will not be closed by this method

Parameters:
  `parser` - the parser to be written
Returns:
  this generator
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if this is called within an object context or if it no context and a value has already been written

#### close

    void close()

Closes this generator and frees any resources associated with it. The underlying output source is closed.

Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `Closeable`
Throws:
  `OracleJsonException` - - if an i/o error occurs
  `OracleJsonGenerationException` - - if an incomplete JSON value is generated (no events have been written or there is still a context that needs to be closed)

#### flush

    void flush()

Flushes the underlying output source. This method may do nothing for some implementations.

Specified by:
  `flush` in interface `Flushable`
Throws:
  `OracleJsonException` - - if an i/o error occurs

#### wrap

    <T> T wrap(Class<T> wrapper)

Returns a JSON-P (javax.json.stream) wrapper around this value. For example:

          import javax.json.stream.JsonGenerator;
          ...
          OracleJsonGenerator oraGenerator = ...;
          JsonGenerator generator = oraGenerator.wrap(JsonGenerator.class);

The returned object is a logical view of this generator. Any changes to the state of this generator are observed by the returned wrapper object.

Parameters:
  `wrapper` - the interface to view this object as. Must be assignable to `javax.json.stream.JsonGenerator`

Copyright © 2008, 2020, Oracle and/or its affiliates. All rights reserved.