Package org.opendaylight.controller.cluster.access.concepts

Class Message<T extends WritableIdentifier,C extends Message<T,C>>

java.lang.Object
org.opendaylight.controller.cluster.access.concepts.Message<T,C>
Type Parameters:
T - Target identifier type
C - Message type
All Implemented Interfaces:
Serializable, Immutable
Direct Known Subclasses:
Request, Response
public abstract class Message<T extends WritableIdentifier,C extends Message<T,C>> extends Object implements Immutable, Serializable
An abstract concept of a Message. This class cannot be instantiated directly, use its specializations Request and Response.

Messages have a target and a sequence number. Sequence numbers are expected to be assigned monotonically on a per-target basis, hence two targets can observe the same sequence number.

This class includes explicit versioning for forward- and backward- compatibility of serialization format. This is achieved by using the serialization proxy pattern. Subclasses are in complete control of what proxy is used to serialize a particular object on the wire. This class can serve as an explicit version marker, hence no further action is necessary in the deserialization path.

For the serialization path an explicit call from the user is required to select the appropriate serialization version. This is done via toVersion(ABIVersion) method, which should return a copy of this object with the requested ABI version recorded and should return the appropriate serialization proxy.

This workflow allows least disturbance across ABI versions, as all messages not affected by a ABI version bump will remain working with the same serialization format for the new ABI version.

Note that this class specifies the Immutable contract, which means that all subclasses must follow this API contract.

See Also:

  • Method Details

    • getTarget

      public final @NonNull T getTarget()
      Get the target identifier for this message.
      Returns:
      Target identifier

    • getSequence

      public final long getSequence()
      Get the logical sequence number.
      Returns:
      logical sequence number

    • getVersion

      public final @NonNull ABIVersion getVersion()

    • toVersion

      public final @NonNull C toVersion(@NonNull ABIVersion toVersion)
      Return a message which will end up being serialized in the specified ABIVersion.
      Parameters:
      toVersion - Request ABIVersion
      Returns:
      A new message which will use ABIVersion as its serialization.

    • cloneAsVersion

      protected abstract @NonNull C cloneAsVersion(@NonNull ABIVersion targetVersion)
      Create a copy of this message which will serialize to a stream corresponding to the specified method. This method should be implemented by the concrete final message class and should invoke the equivalent of Message(Message, ABIVersion).
      Parameters:
      targetVersion - target ABI version
      Returns:
      A message with the specified serialization stream
      Throws:
      IllegalArgumentException - if this message does not support the target ABI

    • toString

      public final String toString()
      Overrides:
      toString in class Object

    • addToStringAttributes

      protected @NonNull MoreObjects.ToStringHelper addToStringAttributes(@NonNull MoreObjects.ToStringHelper toStringHelper)
      Add attributes to the output of toString(). Subclasses wanting to contribute additional information should override this method. Any null attributes will be omitted from the output.
      Parameters:
      toStringHelper - a MoreObjects.ToStringHelper instance
      Returns:
      The MoreObjects.ToStringHelper passed in as argument
      Throws:
      NullPointerException - if toStringHelper is null

    • externalizableProxy

      protected abstract @NonNull Message.SerialForm<T,C> externalizableProxy(@NonNull ABIVersion reqVersion)
      Instantiate a serialization proxy for this object for the target ABI version. Implementations should return different objects for incompatible ABIVersions. This method should never fail, as any compatibility checks should have been done by cloneAsVersion(ABIVersion).
      Parameters:
      reqVersion - Requested ABI version
      Returns:
      Proxy for this object

    • writeReplace

      protected final Object writeReplace()