Package com.oracle.coherence.io.json.genson.stream

Interface ObjectWriter

  • All Known Implementing Classes:
    JsonWriter
    public interface ObjectWriter
    ObjectWriter defines the api allowing to write data to different format and the contract for classes that implement ObjectWriter to provide different formats support. Implementations are extremely efficient as they use low level stream operations and optimizations. If you want optimal performance you can directly use the streaming api (ObjectWriter and ObjectReader ) without the databind support that comes with the converters. This will be very close in terms of performance as writing manually formated data to the stream.

    If you want to write the array new int[1, 2, 3] to the stream with ObjectWriter: 

     writer.beginArray().writeValue(1).writeValue(2).writeValue(3).endArray();

    And to write Person (we simplify, in practice you must handle null values): 

     class Person {
        public static void main(String[] args) {
                // we will write from Person to json string
                Person p = new Person();
                p.name = "eugen";
                p.age = 26;
                p.childrenYearOfBirth = new ArrayList<Integer>();
                StringWriter sw = new StringWriter();
                ObjectWriter writer = new JsonWriter(sw);
                p.write(writer);
                writer.flush();
                writer.close();
                // will write {"name":"eugen","age":26,"childrenYearOfBirth":[]}
                System.out.println(sw.toString());
  }

        String name;
        int age;
        List<Integer> childrenYearOfBirth;

        public void write(ObjectWriter writer) {
                writer.beginObject().writeName("name");
                if (name == null) writer.writeNull();
                else writer.writeValue(name)
                writer.writeName("age").writeAge(age)
                                .writeName("childrenYearOfBirth");
                if (childrenYearOfBirth == null) writer.writeNull();
                else {
                        writer.beginArray();
                        for (Integer year : childrenYearOfBirth)
                                writer.writeValue(year);
                        writer.endArray()
    }
                writer.endObject();
  }
 }

    Be careful if you instantiate ObjectWriter your self you are responsible of flushing and closing the stream.

    Author:
    Eugen Cepoi
    See Also:
    JsonWriter, ObjectReader, JsonReader

    • Method Detail

      • beginArray

        ObjectWriter beginArray()
        Starts to write an array (use it also for collections). An array is a suite of values that may be literals, arrays or objects. When you finished writing the values don't forget to call endArray().
        Returns:
        a reference to this allowing to chain method calls.
        Throws:
        JsonStreamException - if trying to produce invalid json

      • endArray

        ObjectWriter endArray()
        Ends the array, if beginArray was not called, implementations should throw an exception.
        Returns:
        a reference to this allowing to chain method calls.
        Throws:
        JsonStreamException - if trying to produce invalid json

      • beginObject

        ObjectWriter beginObject()
        Starts a object, objects are a suite of name/value pairs, values may be literals, arrays or objects. Don't forget to call endObject.
        Returns:
        a reference to this allowing to chain method calls.
        Throws:
        JsonStreamException - if trying to produce invalid json

      • endObject

        ObjectWriter endObject()
        Ends the object being written, if beginObject was not called an exception will be throwed.
        Returns:
        a reference to this allowing to chain method calls.
        Throws:
        JsonStreamException - if trying to produce invalid json

      • writeName

        ObjectWriter writeName​(String name)
        Writes the name of a property. Names can be written only in objects and must be called before writing the properties value.
        Parameters:
        name - a non null String
        Returns:
        a reference to this, allowing to chain method calls.
        Throws:
        JsonStreamException - if trying to produce invalid json

      • writeEscapedName

        ObjectWriter writeEscapedName​(char[] name)
        Will write the name without escaping special characters, assuming it has been done by the caller or the string doesn't contain any character needing to be escaped.
        Parameters:
        name - a non null escaped String
        Returns:
        a reference to this, allowing to chain method calls.
        Throws:
        JsonStreamException - if trying to produce invalid json

      • writeValue

        ObjectWriter writeValue​(int value)
        Writes a value to the stream. Values can be written in arrays and in objects (after writing the name).
        Parameters:
        value - to write.
        Returns:
        a reference to this, allowing to chain method calls.
        Throws:
        JsonStreamException - if trying to produce invalid json

      • writeString

        ObjectWriter writeString​(String value)
        Similar to writeValue(String) but is null safe, meaning that if the value is null, then the write will call writeNull for you.

      • writeNull

        ObjectWriter writeNull()
        Must be called when a null value is encountered. Implementations will deal with the null representation (just skip it or write null, etc).
        Returns:
        a reference to this allowing to chain method calls.
        Throws:
        JsonStreamException - if trying to produce invalid json
        See Also:
        writeValue(int)

      • beginNextObjectMetadata

        ObjectWriter beginNextObjectMetadata()
        This method is a kind of cheat as it allows us to start writing metadata and then still be able to call beginObject. This is mainly intended to be used in wrapped converters that want to handle a part of the serialization and then let the chain continue. Have a look at ClassMetadataConverter
        Returns:
        a reference to this allowing to chain method calls.
        Throws:
        JsonStreamException
        See Also:
        writeMetadata(String, String)

      • writeMetadata

        ObjectWriter writeMetadata​(String name,
                           String value)
        Metadata is a suite of name/value pairs, names will be prepended with '@' (handled by the library). Metadata feature is experimental for the moment so things may change a bit. The signature will not, but the way it is implemented could... Actually the contract is that metadata must be written first and only in objects. If it does not respect these conditions ObjectReader won't be able to detect it as metadata. Here is an example of two ways to write object metadata. 

         // here it is transparent for the library if you write metadata or something else, you must call
 // beginObject before being able to start writing its metadata.
 writer.beginObject().writeMetadata("doc", "Object documentation bla bla...").writeName("name")
                .writeNull().endObject().flush();

 // previous example works fine, but if you want to write some metadata and still be able to call
 // beginObject (for example in a converter you want to write some metadata and have all the existing
 // continue to work with calling beginObject) you must use beginNextObjectMetadata.

 // written from a first converter
 writer.beginNextObjectMetadata().writeMetadata("dataFromConverter1", "writtenFromConverter1");
 // written from a second converter after first one
 writer.beginNextObjectMetadata().writeMetadata("dataFromConverter2", "writtenFromConverter2");
 // finally concrete properties will be written from a custom converter
 writer.beginObject().writeName("name").writeNull().endObject().flush();
        Parameters:
        name - of the metadata property, should not start with '@', the library will add it.
        value - of the metadata property.
        Returns:
        a reference to this allowing to chain method calls.
        Throws:
        JsonStreamException
        See Also:
        beginNextObjectMetadata()

      • writeString

        ObjectWriter writeString​(String name,
                         String value)
        Will write the name and the value, it is just a shortcut for writer.writeName("key").writeString(value). Note if the value is null, writeNull is used.

      • flush

        void flush()

      • close

        void close()

      • enclosingType

        JsonType enclosingType()