Class Identifiable

java.lang.Object
com.yahoo.vespa.objects.Selectable
com.yahoo.vespa.objects.Identifiable
All Implemented Interfaces:
Cloneable

public class Identifiable extends Selectable implements Cloneable
The base class to do cross-language serialization and deserialization of complete object structures without the need for a separate protocol. Each subclass needs to register itself using the registerClass(int, Class) method, and override onGetClassId() to return the same classId as the one registered. Creating an instance of an identifiable object is done through the create(Deserializer) or createFromId(int) factory methods.
Author:
baldersheim, Simon Thoresen Hult
  • Field Details

    • classId

      public static int classId
  • Constructor Details

    • Identifiable

      public Identifiable()
  • Method Details

    • getClassId

      public final int getClassId()
      Returns the class identifier of this class. This proxies the onGetClassId() method that must be implemented by every subclass.
      Returns:
      the class identifier
    • onGetClassId

      protected int onGetClassId()
      Returns the class identifier for which this class is registered. It is important that all subclasses match the return value of this with their call to registerClass(int, Class).
      Returns:
      The class identifier.
    • serializeWithId

      public final Serializer serializeWithId(Serializer buf)
      Serializes the content of this class into the given byte buffer. This method serializes its own identifier into the buffer before invoking the serialize(Serializer) method.
      Parameters:
      buf - The buffer to serialize to.
      Returns:
      The buffer argument, to allow chaining.
    • serialize

      public final Serializer serialize(Serializer buf)
      Serializes the content (excluding the identifier) of this class into the given byte buffer. If you need the identifier serialized, use the serializeWithId(Serializer) method instead. This method invokes the onSerialize(Serializer) method.
      Parameters:
      buf - The buffer to serialize to.
      Returns:
      The buffer argument, to allow chaining.
    • onSerialize

      protected void onSerialize(Serializer buf)
      Serializes the content of this class into the given buffer. This method must be implemented by all subclasses that have content. If the subclass has no other content than the semantics of its class type, this method does not need to be overloaded.
      Parameters:
      buf - The buffer to serialize to.
    • deserializeWithId

      public final Deserializer deserializeWithId(Deserializer buf)
      Deserializes the content of this class from the given byte buffer. This method deserialize a class identifier first, and asserts that this identifier matches the identifier of this class. This is usable if you have an instance of a class whose content you wish to retrieve from a buffer.
      Parameters:
      buf - The buffer to deserialize from.
      Returns:
      The buffer argument, to allow chaining.
      Throws:
      IllegalArgumentException - Thrown if the deserialized class identifier does not match this class.
    • deserialize

      public final Deserializer deserialize(Deserializer buf)
      Deserializes the content (excluding the identifier) of this class from the given byte buffer. If you need the identifier deserialized and verified, use the deserializeWithId(Deserializer) method instead. This method invokes the onDeserialize(Deserializer) method.
      Parameters:
      buf - The buffer to deserialize from.
      Returns:
      The buffer argument, to allow chaining.
    • onDeserialize

      protected void onDeserialize(Deserializer buf)
      Deserializes the content of this class from the given byte buffer. This method must be implemented by all subclasses that have content. If the subclass has no other content than the semantics of its class type, this method does not need to be overloaded.
      Parameters:
      buf - The buffer to deserialize from.
    • clone

      public Identifiable clone()
      Declares that all subclasses of Identifiable supports clone() by _not_ throwing CloneNotSupported exceptions.
      Overrides:
      clone in class Object
      Returns:
      A cloned instance of this.
      Throws:
      AssertionError - Thrown if a subclass does not implement clone().
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object
    • toString

      public String toString()
      Overrides:
      toString in class Object
    • registerClass

      protected static int registerClass(int id, Class<? extends Identifiable> spec)
      Registers the given class specification for the given identifier in the class registry. This method returns the supplied identifier, so that subclasses can declare a static classId member like so: public static int classId = registerClass(<id>, <ClassName>.class);
      Parameters:
      id - the class identifier to register with
      spec - the class to register
      Returns:
      the identifier argument
    • create

      public static Identifiable create(Deserializer buf)
      Deserializes a single Identifiable object from the given byte buffer. The object itself may perform recursive deserialization of Identifiable objects, but there is no requirement that this method consumes the whole content of the buffer.
      Parameters:
      buf - The buffer to deserialize from.
      Returns:
      The instantiated object.
      Throws:
      IllegalArgumentException - Thrown if an unknown class is contained in the buffer.
    • createFromId

      public static Identifiable createFromId(int id)
      Creates an instance of the class registered with the given identifier. If the indentifier is unknown, this method returns null.
      Parameters:
      id - The identifier of the class to instantiate.
      Returns:
      The instantiated object.
    • serializeOptional

      protected static Serializer serializeOptional(Serializer buf, Identifiable obj)
      This is a convenience method to allow serialization of an optional field. A single byte is added to the buffer indicating whether or not an object follows. If the object is not null, it is serialized following this flag.
      Parameters:
      buf - The buffer to serialize to.
      obj - The object to serialize, may be null.
      Returns:
      The buffer, to allow chaining.
    • deserializeOptional

      protected static Identifiable deserializeOptional(Deserializer buf)
      This is a convenience method to allow deserialization of an optional field. See serializeOptional(Serializer, Identifiable) for notes on this.
      Parameters:
      buf - The buffer to deserialize from.
      Returns:
      The instantiated object, or null.
    • equals

      protected static boolean equals(Object lhs, Object rhs)
      Returns whether or not two objects are equal, taking into account that either can be null.
      Parameters:
      lhs - The left hand side of the comparison.
      rhs - The right hand side of the comparison.
      Returns:
      True if both arguments are null or equal.
    • visitMembers

      public void visitMembers(ObjectVisitor visitor)
      This function needs to be implemented in such a way that it visits all its members. This is done by invoking the ObjectVisitor.visit(String, Object) on the visitor argument for all members.
      Parameters:
      visitor - The visitor that is to access the member data.
    • getRawUtf8Bytes

      protected static byte[] getRawUtf8Bytes(Deserializer buf)
    • getUtf8

      protected String getUtf8(Deserializer buf)
    • putUtf8

      protected void putUtf8(Serializer buf, String val)