Package 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 Details

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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

    • 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(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

    • write

      OracleJsonGenerator write(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

    • write

      OracleJsonGenerator write(String name, 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, 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(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

    • write

      OracleJsonGenerator write(String name, 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(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

    • write

      OracleJsonGenerator write(String name, 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

    • 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

    • 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

    • 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