Package com.yahoo.vespa.objects

Class Identifiable

  • All Implemented Interfaces:
    java.lang.Cloneable
    public class Identifiable
extends Selectable
implements java.lang.Cloneable
    This is 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 Detail

      • classId

        public static int classId

    • Constructor Detail

      • Identifiable

        public Identifiable()

    • Method Detail

      • 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:
        java.lang.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 java.lang.Object
        Returns:
        A cloned instance of this.
        Throws:
        java.lang.AssertionError - Thrown if a subclass does not implement clone().

      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class java.lang.Object

      • equals

        public boolean equals​(java.lang.Object obj)
        Overrides:
        equals in class java.lang.Object

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • registerClass

        protected static int registerClass​(int id,
                                   java.lang.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:
        java.lang.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.

      • equals

        protected static boolean equals​(java.lang.Object lhs,
                                java.lang.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.

      • getUtf8

        protected java.lang.String getUtf8​(Deserializer buf)

      • putUtf8

        protected void putUtf8​(Serializer buf,
                       java.lang.String val)