Package score

Interface ObjectWriter

  • All Known Subinterfaces:
    ByteArrayObjectWriter
    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

      All Methods Instance Methods Abstract Methods 
      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