BUG-5280: introduce Request/Response and related concepts
[controller.git] / opendaylight / md-sal / cds-access-api / src / main / java / org / opendaylight / controller / cluster / access / concepts / Message.java
1 /*
2  * Copyright (c) 2016 Cisco Systems, Inc. and others.  All rights reserved.
3  *
4  * This program and the accompanying materials are made available under the
5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
6  * and is available at http://www.eclipse.org/legal/epl-v10.html
7  */
8 package org.opendaylight.controller.cluster.access.concepts;
9
10 import com.google.common.annotations.Beta;
11 import com.google.common.annotations.VisibleForTesting;
12 import com.google.common.base.MoreObjects;
13 import com.google.common.base.MoreObjects.ToStringHelper;
14 import com.google.common.base.Preconditions;
15 import com.google.common.base.Verify;
16 import java.io.Serializable;
17 import javax.annotation.Nonnull;
18 import org.opendaylight.controller.cluster.access.ABIVersion;
19 import org.opendaylight.yangtools.concepts.Immutable;
20 import org.opendaylight.yangtools.concepts.WritableIdentifier;
21
22 /**
23  * An abstract concept of a Message. This class cannot be instantiated directly, use its specializations {@link Request}
24  * and {@link Response}.
25  *
26  * Messages have a target and a sequence number. Sequence numbers are expected to be assigned monotonically on a
27  * per-target basis, hence two targets can observe the same sequence number.
28  *
29  * This class includes explicit versioning for forward- and backward- compatibility of serialization format. This is
30  * achieved by using the serialization proxy pattern. Subclasses are in complete control of what proxy is used to
31  * serialize a particular object on the wire. This class can serve as an explicit version marker, hence no further
32  * action is necessary in the deserialization path.
33  *
34  * For the serialization path an explicit call from the user is required to select the appropriate serialization
35  * version. This is done via {@link #toVersion(ABIVersion)} method, which should return a copy of this object with
36  * the requested ABI version recorded and should return the appropriate serialization proxy.
37  *
38  * This workflow allows least disturbance across ABI versions, as all messages not affected by a ABI version bump
39  * will remain working with the same serialization format for the new ABI version.
40  *
41  * Note that this class specifies the {@link Immutable} contract, which means that all subclasses must follow this API
42  * contract.
43  *
44  * @author Robert Varga
45  *
46  * @param <T> Target identifier type
47  * @param <C> Message type
48  */
49 @Beta
50 public abstract class Message<T extends WritableIdentifier, C extends Message<T, C>> implements Immutable,
51         Serializable {
52     private static final long serialVersionUID = 1L;
53     private final T target;
54     private final long sequence;
55     private final ABIVersion version;
56     private final long retry;
57
58     private Message(final ABIVersion version, final T target, final long sequence, final long retry) {
59         this.target = Preconditions.checkNotNull(target);
60         this.version = Preconditions.checkNotNull(version);
61         this.sequence = sequence;
62         this.retry = retry;
63     }
64
65     Message(final T target, final long sequence, final long retry) {
66         this(ABIVersion.current(), target, sequence, retry);
67     }
68
69     Message(final C msg, final ABIVersion version) {
70         this(version, msg.getTarget(), msg.getSequence(), msg.getRetry());
71     }
72
73     Message(final C msg, final long retry) {
74         this(msg.getVersion(), msg.getTarget(), msg.getSequence(), retry);
75     }
76
77     /**
78      * Get the target identifier for this message.
79      *
80      * @return Target identifier
81      */
82     public final @Nonnull T getTarget() {
83         return target;
84     }
85
86     /**
87      * Get the message sequence of this message.
88      *
89      * @return Message sequence
90      */
91     public final long getSequence() {
92         return sequence;
93     }
94
95     @VisibleForTesting
96     public final ABIVersion getVersion() {
97         return version;
98     }
99
100     /**
101      * Get the message retry counter.
102      *
103      * @return Retry counter
104      */
105     public final long getRetry() {
106         return retry;
107     }
108
109     /**
110      * Return a message which will end up being serialized in the specified {@link ABIVersion}.
111      *
112      * @param version Request {@link ABIVersion}
113      * @return A new message which will use ABIVersion as its serialization.
114      */
115     @SuppressWarnings("unchecked")
116     public final @Nonnull C toVersion(final @Nonnull ABIVersion version) {
117         if (this.version == version) {
118             return (C)this;
119         }
120
121         switch (version) {
122             case BORON:
123                 return Verify.verifyNotNull(cloneAsVersion(version));
124             case TEST_PAST_VERSION:
125             case TEST_FUTURE_VERSION:
126                 // Fall-through to throw
127                 break;
128         }
129
130         throw new IllegalArgumentException("Unhandled ABI version " + version);
131     }
132
133     /**
134      * Create a copy of this message which will serialize to a stream corresponding to the specified method. This
135      * method should be implemented by the concrete final message class and should invoke the equivalent of
136      * {@link #Message(Message, ABIVersion)}.
137      *
138      * @param version target ABI version
139      * @return A message with the specified serialization stream
140      * @throws IllegalArgumentException if this message does not support the target ABI
141      */
142     protected abstract @Nonnull C cloneAsVersion(@Nonnull ABIVersion version);
143
144     /**
145      * Return a message which will have the retry counter incremented by one.
146      *
147      * @return A message with the specified retry counter
148      */
149     public final @Nonnull C incrementRetry() {
150         return Verify.verifyNotNull(cloneAsRetry(retry +1));
151     }
152
153     /**
154      * Create a copy of this message which will have its retry count bumped. This method should be implemented by
155      * the concrete final message class and should invoked the equivalent of {@link #Message(Message, long)}.
156      *
157      * @param retry new retry count
158      * @return A message with the specified retry counter
159      */
160     protected abstract @Nonnull C cloneAsRetry(long retry);
161
162     @Override
163     public final String toString() {
164         return addToStringAttributes(MoreObjects.toStringHelper(this).omitNullValues()).toString();
165     }
166
167     /**
168      * Add attributes to the output of {@link #toString()}. Subclasses wanting to contribute additional information
169      * should override this method. Any null attributes will be omitted from the output.
170      *
171      * @param toStringHelper a {@link ToStringHelper} instance
172      * @return The {@link ToStringHelper} passed in as argument
173      * @throws NullPointerException if toStringHelper is null
174      */
175     protected @Nonnull ToStringHelper addToStringAttributes(final @Nonnull ToStringHelper toStringHelper) {
176         return toStringHelper.add("target", target).add("sequence", Long.toUnsignedString(sequence, 16));
177     }
178
179     /**
180      * Instantiate a serialization proxy for this object for the target ABI version. Implementations should return
181      * different objects for incompatible {@link ABIVersion}s. This method should never fail, as any compatibility
182      * checks should have been done by {@link #cloneAsVersion(ABIVersion)}.
183      *
184      * @param version Requested ABI version
185      * @return Proxy for this object
186      */
187     abstract @Nonnull AbstractMessageProxy<T, C> externalizableProxy(@Nonnull ABIVersion version);
188
189     protected final Object writeReplace() {
190         return externalizableProxy(version);
191     }
192 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.