* An abstract concept of a Message. This class cannot be instantiated directly, use its specializations {@link Request}
* and {@link Response}.
*
+ * <p>
* 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.
*
+ * <p>
* 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.
*
+ * <p>
* For the serialization path an explicit call from the user is required to select the appropriate serialization
* version. This is done via {@link #toVersion(ABIVersion)} method, which should return a copy of this object with
* the requested ABI version recorded and should return the appropriate serialization proxy.
*
+ * <p>
* 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.
*
+ * <p>
* Note that this class specifies the {@link Immutable} contract, which means that all subclasses must follow this API
* contract.
*
public abstract class Message<T extends WritableIdentifier, C extends Message<T, C>> implements Immutable,
Serializable {
private static final long serialVersionUID = 1L;
- private final T target;
+
private final ABIVersion version;
+ private final long sequence;
+ private final T target;
- private Message(final ABIVersion version, final T target) {
+ private Message(final ABIVersion version, final T target, final long sequence) {
this.target = Preconditions.checkNotNull(target);
this.version = Preconditions.checkNotNull(version);
+ this.sequence = sequence;
}
- Message(final T target) {
- this(ABIVersion.current(), target);
+ Message(final T target, final long sequence) {
+ this(ABIVersion.current(), target, sequence);
}
Message(final C msg, final ABIVersion version) {
- this(version, msg.getTarget());
+ this(version, msg.getTarget(), msg.getSequence());
}
/**
*
* @return Target identifier
*/
- public final @Nonnull T getTarget() {
+ @Nonnull
+ public final T getTarget() {
return target;
}
+ /**
+ * Get the logical sequence number.
+ *
+ * @return logical sequence number
+ */
+ public final long getSequence() {
+ return sequence;
+ }
+
@VisibleForTesting
+ @Nonnull
public final ABIVersion getVersion() {
return version;
}
/**
* Return a message which will end up being serialized in the specified {@link ABIVersion}.
*
- * @param version Request {@link ABIVersion}
+ * @param toVersion Request {@link ABIVersion}
* @return A new message which will use ABIVersion as its serialization.
*/
@SuppressWarnings("unchecked")
- public final @Nonnull C toVersion(final @Nonnull ABIVersion version) {
- if (this.version == version) {
+ @Nonnull
+ public final C toVersion(@Nonnull final ABIVersion toVersion) {
+ if (this.version == toVersion) {
return (C)this;
}
- switch (version) {
+ switch (toVersion) {
case BORON:
- return Verify.verifyNotNull(cloneAsVersion(version));
+ return Verify.verifyNotNull(cloneAsVersion(toVersion));
case TEST_PAST_VERSION:
case TEST_FUTURE_VERSION:
+ default:
// Fall-through to throw
break;
}
- throw new IllegalArgumentException("Unhandled ABI version " + version);
+ throw new IllegalArgumentException("Unhandled ABI version " + toVersion);
}
/**
* method should be implemented by the concrete final message class and should invoke the equivalent of
* {@link #Message(Message, ABIVersion)}.
*
- * @param version target ABI version
+ * @param targetVersion target ABI version
* @return A message with the specified serialization stream
* @throws IllegalArgumentException if this message does not support the target ABI
*/
- protected abstract @Nonnull C cloneAsVersion(@Nonnull ABIVersion version);
+ @Nonnull
+ protected abstract C cloneAsVersion(@Nonnull ABIVersion targetVersion);
@Override
public final String toString() {
* @return The {@link ToStringHelper} passed in as argument
* @throws NullPointerException if toStringHelper is null
*/
- protected @Nonnull ToStringHelper addToStringAttributes(final @Nonnull ToStringHelper toStringHelper) {
- return toStringHelper.add("target", target);
+ @Nonnull
+ protected ToStringHelper addToStringAttributes(@Nonnull final ToStringHelper toStringHelper) {
+ return toStringHelper.add("target", target).add("sequence", Long.toUnsignedString(sequence));
}
/**
* different objects for incompatible {@link ABIVersion}s. This method should never fail, as any compatibility
* checks should have been done by {@link #cloneAsVersion(ABIVersion)}.
*
- * @param version Requested ABI version
+ * @param reqVersion Requested ABI version
* @return Proxy for this object
*/
- abstract @Nonnull AbstractMessageProxy<T, C> externalizableProxy(@Nonnull ABIVersion version);
+ @Nonnull
+ abstract AbstractMessageProxy<T, C> externalizableProxy(@Nonnull ABIVersion reqVersion);
protected final Object writeReplace() {
return externalizableProxy(version);
Code Review / controller.git / blobdiff