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

      • 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

      • 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

      • 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

      • 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

      • 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