com.owlike.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

See Also:

JsonWriter, ObjectReader, JsonReader

Method Summary

Modifier and Type	Method and Description
ObjectWriter	beginArray() Starts to write an array (use it also for collections).
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.
ObjectWriter	beginObject() Starts a object, objects are a suite of name/value pairs, values may be literals, arrays or objects.
void	close()
JsonType	enclosingType()
ObjectWriter	endArray() Ends the array, if beginArray was not called, implementations should throw an exception.
ObjectWriter	endObject() Ends the object being written, if beginObject was not called an exception will be throwed.
void	flush()
ObjectWriter	writeBoolean(Boolean value)
ObjectWriter	writeBoolean(String name, Boolean value)
ObjectWriter	writeBytes(byte[] value)
ObjectWriter	writeBytes(String name, byte[] value)
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.
ObjectWriter	writeMetadata(String name, String value) Metadata is a suite of name/value pairs, names will be prepended with '@' (handled by the library).
ObjectWriter	writeName(String name) Writes the name of a property.
ObjectWriter	writeNull() Must be called when a null value is encountered.
ObjectWriter	writeNumber(Number value)
ObjectWriter	writeNumber(String name, Number value)
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.
ObjectWriter	writeString(String name, String value) Will write the name and the value, it is just a shortcut for writer.writeName("key").writeString(value).
ObjectWriter	writeUnsafeValue(String value) Writes value as is without any pre-processing, it's faster than writeValue(String) but should be used only if you know that it is safe.
ObjectWriter	writeValue(boolean value) See writeValue(int).
ObjectWriter	writeValue(byte[] value) Writes an array of bytes as a base64 encoded string.
ObjectWriter	writeValue(double value) See writeValue(int).
ObjectWriter	writeValue(float value)
ObjectWriter	writeValue(int value) Writes a value to the stream.
ObjectWriter	writeValue(long value) See writeValue(int).
ObjectWriter	writeValue(Number value) See writeValue(int).
ObjectWriter	writeValue(short value) See writeValue(int).
ObjectWriter	writeValue(String value) See writeValue(int).

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

writeValue

ObjectWriter writeValue(double value)

See writeValue(int).

Throws:

JsonStreamException - if trying to produce invalid json

See Also:

writeValue(int)

writeValue

ObjectWriter writeValue(long value)

See writeValue(int).

Throws:

JsonStreamException - if trying to produce invalid json

See Also:

writeValue(int)

writeValue

ObjectWriter writeValue(short value)

See writeValue(int).

Throws:

JsonStreamException - if trying to produce invalid json

See Also:

writeValue(int)

writeValue

ObjectWriter writeValue(float value)

See Also:

writeValue(int)

writeValue

ObjectWriter writeValue(boolean value)

See writeValue(int).

Throws:

JsonStreamException - if trying to produce invalid json

See Also:

writeValue(int)

writeBoolean

ObjectWriter writeBoolean(Boolean value)

See Also:

writeString(String)

writeValue

ObjectWriter writeValue(Number value)

See writeValue(int).

Throws:

JsonStreamException - if trying to produce invalid json

See Also:

writeValue(int)

writeNumber

ObjectWriter writeNumber(Number value)

See Also:

writeString(String)

writeValue

ObjectWriter writeValue(String value)

See writeValue(int).

Throws:

JsonStreamException - if trying to produce invalid json

See Also:

writeValue(int)

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.

writeValue

ObjectWriter writeValue(byte[] value)

Writes an array of bytes as a base64 encoded string. See writeValue(int).

Throws:

JsonStreamException - if trying to produce invalid json

See Also:

writeValue(int)

writeBytes

ObjectWriter writeBytes(byte[] value)

See Also:

writeString(String)

writeUnsafeValue

ObjectWriter writeUnsafeValue(String value)

Writes value as is without any pre-processing, it's faster than writeValue(String) but should be used only if you know that it is safe.

Throws:

JsonStreamException - if trying to produce invalid json

See Also:

writeValue(int)

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

writeBoolean

ObjectWriter writeBoolean(String name,
                          Boolean value)

See Also:

writeString(String, String)

writeNumber

ObjectWriter writeNumber(String name,
                         Number value)

See Also:

writeString(String, String)

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.

writeBytes

ObjectWriter writeBytes(String name,
                        byte[] value)

See Also:

writeString(String, String)

flush

void flush()

close

void close()

enclosingType

JsonType enclosingType()