Package score

Interface ObjectWriter

public interface ObjectWriter

Interface for object write.

An object is writable if the object is a builtin object or its class has the following method.

  public static void writeObject(ObjectWriter w, UserClass obj)
 

A builtin object is a simple object or a container object. A simple object is a Boolean, a Byte, a Short, a Character, a Integer, a Float, a Long, a Double, a BigInteger, a String, byte array or an Address. They are written by corresponding write methods. The following is an example of writing simple objects.

      objectWriter.writeString("a string");
      objectWriter.writeInt(0);
 

A container object is a list or a map. A container may have another container as its element.

A list has zero or more builtin objects as its elements. A list is written by a beginList(int) call followed by calls for writings of zero or more its elements followed by a end() call. For example, the following method writes a list of two elements.

      objectWriter.beginList(2);
          objectWriter.writeInt(0);
          objectWriter.beginList(0);
          objectWriter.end();
      objectWriter.end();
 

A map has zero or more pairs of objects as its elements. A map is written by a beginMap(int) call followed by calls for writings of zero or more its elements followed by a end() call. For example, the following method writes a map of one element.

      objectWriter.beginMap(1);
          objectWriter.writeString("key");
          objectWriter.writeString("value");
      objectWriter.end();
 

You can write a custom object indirectly if its class has the following method.

  public static void writeObject(ObjectWriter w, UserClass obj)
 

When you write a custom object, the writeObject method is called. In the method, you must write one equivalent builtin object. It is error to write no object or two or more objects. The method may write one list with multiple elements. For example, the following is error.

  public static void writeObject(ObjectWriter w, UserClass obj) {
      w.writeString(obj.name);
      w.writeString(obj.description);
  }
 

Instead, write a list with multiple elements if you want to write multiple objects.

  public static void writeObject(ObjectWriter w, UserClass obj) {
      w.beginList(2);
          w.writeString(obj.name);
          w.writeString(obj.description);
      w.end();
  }
 

You can write an object as a non-nullable type object or nullable type object. A non-nullable type object is always not null. A nullable object may be null or non-null. A write method writes an object as non-nullable type unless the document specifies the method writes a nullable type object. For example, write(String) writes non-nullable type object. writeNullable(Object) and writeNull() methods write a nullable type object. beginNullableList(int) begins a nullable list.

Nullable-ness shall be preserved during write and read. If a non-nullable object is written, the object shall be read as a non-nullable object and shall not be read as a nullable object later. If a nullable object is written, the object shall be read as a nullable object and shall not be read a non-nullable object later. For example, if an object is written as the following:

     Integer i = getInteger();
     objectWriter.writeNullable(i);
 

It is error to read the object as the following:

     int i = objectReader.readInt();
 

Instead, the object shall be read as the following:

     Integer i = objectReader.readNullable(Integer.class);
 

If an exception is thrown during any write call, the writer becomes invalidated. An invalidated writer fails any method.

See Also:

ObjectReader

Method Summary

Modifier and Type	Method	Description
void	beginList(int l)	Writes a list header and begins a list.
void	beginMap(int l)	Writes a map header and begins a map.
void	beginNullableList(int l)	Writes a nullable list header and begins a list.
void	beginNullableMap(int l)	Writes a nullable map header and begins a map.
void	end()	Ends the current container.
void	write(boolean v)	Writes a boolean.
void	write(byte v)	Writes a byte.
void	write(byte[] v)	Writes a byte array.
void	write(char v)	Writes a character.
void	write(double v)	Writes a double.
void	write(float v)	Writes a float.
void	write(int v)	Writes a integer.
void	write(long v)	Writes a long.
void	write(short v)	Writes a short.
void	write(java.lang.Object v)	Writes an object.
void	write(java.lang.Object... v)	Writes objects.
void	write(java.lang.String v)	Writes a string.
void	write(java.math.BigInteger v)	Writes a big integer.
void	write(Address v)	Writes an address.
void	writeListOf(java.lang.Object... v)	Writes a list.
void	writeListOfNullable(java.lang.Object... v)	Writes a list of nullable.
void	writeNull()	Writes a null.
void	writeNullable(java.lang.Object v)	Writes a nullable object.
void	writeNullable(java.lang.Object... v)	Writes nullable objects.

Method Detail

write

void write(boolean v)

Writes a boolean.

Parameters:

v - a boolean value.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

write

void write(byte v)

Writes a byte.

Parameters:

v - a byte value.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

write

void write(short v)

Writes a short.

Parameters:

v - a short value.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

write

void write(char v)

Writes a character.

Parameters:

v - a character value.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

write

void write(int v)

Writes a integer.

Parameters:

v - an integer value.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

write

void write(float v)

Writes a float.

Parameters:

v - a float value.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

write

void write(long v)

Writes a long.

Parameters:

v - a long value.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

write

void write(double v)

Writes a double.

Parameters:

v - a double value.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

write

void write(java.math.BigInteger v)

Writes a big integer.

Parameters:

v - a big integer.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

java.lang.NullPointerException - If v is null.

write

void write(java.lang.String v)

Writes a string.

Parameters:

v - a string.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

java.lang.NullPointerException - If v is null.

write

void write(byte[] v)

Writes a byte array.

Parameters:

v - a byte array.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

java.lang.NullPointerException - If v is null.

write

void write(Address v)

Writes an address.

Parameters:

v - an address.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

java.lang.NullPointerException - If v is null.

write

void write(java.lang.Object v)

Writes an object. The class of the object shall be Boolean, Byte, Short, Character, Integer, Float, Long, Double, BigInteger, String, byte array, Address, or a custom class with the following method.

 public static void writeObject(ObjectWriter w, UserClass obj)
 

Parameters:

v - object to be written.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

java.lang.IllegalArgumentException - If the object is not a simple object and correct writeObject method is not available or the method threw Throwable which is not an RuntimeException.

java.lang.NullPointerException - If v is null.

writeNullable

void writeNullable(java.lang.Object v)

Writes a nullable object.

Parameters:

v - object to be written.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

java.lang.IllegalArgumentException - If the object is not a simple object and correct writeObject method is not available or the method threw Throwable which is not an RuntimeException.

See Also:

write(Object)

write

void write(java.lang.Object... v)

Writes objects.

Parameters:

v - objects to be written.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

java.lang.IllegalArgumentException - If the object is not a simple object and correct writeObject method is not available or the method threw Throwable which is not an RuntimeException.

java.lang.NullPointerException - If v is null.

See Also:

write(Object)

writeNullable

void writeNullable(java.lang.Object... v)

Writes nullable objects.

Parameters:

v - objects to be written.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

java.lang.IllegalArgumentException - If the object is not a simple object and correct writeObject method is not available or the method threw Throwable which is not an RuntimeException.

See Also:

write(Object)

writeNull

void writeNull()

Writes a null.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

beginList

void beginList(int l)

Writes a list header and begins a list.

A following write operation writes an element of list. When all elements are written you must call end() to end the current list.

Parameters:

l - number of elements.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

See Also:

ObjectWriter

beginNullableList

void beginNullableList(int l)

Writes a nullable list header and begins a list.

A following write operation writes an element of list. When all elements are written you must call end() to end the current list.

Parameters:

l - number of elements.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

See Also:

ObjectWriter

writeListOf

void writeListOf(java.lang.Object... v)

Writes a list. The operation writes a list header and writes elements and ends the list.

Parameters:

v - list elements

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

java.lang.IllegalArgumentException - If the object is not a simple object and correct writeObject method is not available or the method threw Throwable which is not an RuntimeException.

See Also:

ObjectWriter

writeListOfNullable

void writeListOfNullable(java.lang.Object... v)

Writes a list of nullable. The operation writes a list header and writes elements and ends the list.

Parameters:

v - list elements

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

java.lang.IllegalArgumentException - If the object is not a simple object and correct writeObject method is not available or the method threw Throwable which is not an RuntimeException.

See Also:

ObjectWriter

beginMap

void beginMap(int l)

Writes a map header and begins a map.

A following write operation writes an element of map. When all elements are written you must call end() to end the current map.

Parameters:

l - number of elements.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

See Also:

ObjectWriter

beginNullableMap

void beginNullableMap(int l)

Writes a nullable map header and begins a map.

A following write operation writes an element of map. When all elements are written you must call end() to end the current map.

Parameters:

l - number of elements.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one.

See Also:

ObjectWriter

end

void end()

Ends the current container.

Throws:

java.lang.IllegalStateException - if this writer is invalidated one or if this end is imbalanced.

See Also:

ObjectWriter