Package com.yahoo.vespa.objects
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 theregisterClass(int, Class)
method, and overrideonGetClassId()
to return the same classId as the one registered. Creating an instance of an identifiable object is done through thecreate(Deserializer)
orcreateFromId(int)
factory methods.- Author:
- baldersheim, Simon Thoresen Hult
-
-
Field Summary
Fields Modifier and Type Field Description static int
classId
-
Constructor Summary
Constructors Constructor Description Identifiable()
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description Identifiable
clone()
Declares that all subclasses of Identifiable supports clone() by _not_ throwing CloneNotSupported exceptions.static Identifiable
create(Deserializer buf)
Deserializes a singleIdentifiable
object from the given byte buffer.static Identifiable
createFromId(int id)
Creates an instance of the class registered with the given identifier.Deserializer
deserialize(Deserializer buf)
Deserializes the content (excluding the identifier) of this class from the given byte buffer.protected static Identifiable
deserializeOptional(Deserializer buf)
This is a convenience method to allow deserialization of an optional field.Deserializer
deserializeWithId(Deserializer buf)
Deserializes the content of this class from the given byte buffer.boolean
equals(Object obj)
protected static boolean
equals(Object lhs, Object rhs)
Returns whether or not two objects are equal, taking into account that either can be null.int
getClassId()
Returns the class identifier of this class.protected static byte[]
getRawUtf8Bytes(Deserializer buf)
protected String
getUtf8(Deserializer buf)
int
hashCode()
protected void
onDeserialize(Deserializer buf)
Deserializes the content of this class from the given byte buffer.protected int
onGetClassId()
Returns the class identifier for which this class is registered.protected void
onSerialize(Serializer buf)
Serializes the content of this class into the given buffer.protected void
putUtf8(Serializer buf, String val)
protected static int
registerClass(int id, Class<? extends Identifiable> spec)
Registers the given class specification for the given identifier in the class registry.Serializer
serialize(Serializer buf)
Serializes the content (excluding the identifier) of this class into the given byte buffer.protected static Serializer
serializeOptional(Serializer buf, Identifiable obj)
This is a convenience method to allow serialization of an optional field.Serializer
serializeWithId(Serializer buf)
Serializes the content of this class into the given byte buffer.String
toString()
void
visitMembers(ObjectVisitor visitor)
This function needs to be implemented in such a way that it visits all its members.-
Methods inherited from class com.yahoo.vespa.objects.Selectable
select, select, selectMembers
-
-
-
-
Method Detail
-
getClassId
public final int getClassId()
Returns the class identifier of this class. This proxies theonGetClassId()
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 toregisterClass(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 theserialize(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 theserializeWithId(Serializer)
method instead. This method invokes theonSerialize(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 thedeserializeWithId(Deserializer)
method instead. This method invokes theonDeserialize(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 classObject
- Returns:
- A cloned instance of this.
- Throws:
AssertionError
- Thrown if a subclass does not implement clone().
-
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 withspec
- the class to register- Returns:
- the identifier argument
-
create
public static Identifiable create(Deserializer buf)
Deserializes a singleIdentifiable
object from the given byte buffer. The object itself may perform recursive deserialization ofIdentifiable
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. SeeserializeOptional(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 theObjectVisitor.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)
-
-