Package com.yahoo.vespa.objects
Class Identifiable
java.lang.Object
com.yahoo.vespa.objects.Selectable
com.yahoo.vespa.objects.Identifiable
- All Implemented Interfaces:
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 Summary
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionclone()
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.final Deserializer
deserialize
(Deserializer buf) Deserializes the content (excluding the identifier) of this class from the given byte buffer.protected static Identifiable
This is a convenience method to allow deserialization of an optional field.final Deserializer
Deserializes the content of this class from the given byte buffer.boolean
protected static boolean
Returns whether or not two objects are equal, taking into account that either can be null.final int
Returns the class identifier of this class.protected static byte[]
protected String
getUtf8
(Deserializer buf) int
hashCode()
protected void
Deserializes the content of this class from the given byte buffer.protected int
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.protected static int
registerClass
(int id, Class<? extends Identifiable> spec, Supplier<? extends Identifiable> creator) final 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.final Serializer
Serializes the content of this class into the given byte buffer.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
-
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 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
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
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
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
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
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
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
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().
-
hashCode
public int hashCode() -
equals
-
toString
-
registerClass
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
-
registerClass
protected static int registerClass(int id, Class<? extends Identifiable> spec, Supplier<? extends Identifiable> creator) -
create
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
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
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
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
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
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
-
getUtf8
-
putUtf8
-