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

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

  • Type Parameters:
    T - Target identifier type
    C - Message type
    All Implemented Interfaces:
    Serializable, Immutable, MutationBehaviour<Immutable>
    Direct Known Subclasses:
    Request, Response
    @Beta
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.

    Author:
    Robert Varga
    See Also:
    Serialized Form

    • Method Detail

      • 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

      • 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()