Source code: com/aendvari/hermes/broker/Message.java
1 /*
2 * Message.java
3 *
4 * Copyright (c) 2001, 2002 Aendvari, Ltd. All Rights Reserved.
5 *
6 * See the file LICENSE for terms of use.
7 *
8 */
9
10 package com.aendvari.hermes.broker;
11
12 import com.aendvari.common.properties.Properties;
13
14 /**
15 * <p>Represents a single message. Messages are sent to listeners using a publish/subscribe
16 * model. The {@link MessageBroker} class handles the dispatching and listener registration.</p>
17 *
18 * <p>A message may have several properties. The properties are stored in a
19 * ({@link Properties}) object. This allows the properties to be stored in a hierarchy.</p>
20 *
21 * <p>Every message may have an optional "reply to" value set. The value is the
22 * {@link MessageTopic} to send a response message to. Typically, the sender of the original
23 * message has subscribed to this topic. Other listeners may subscribe with the same topic.
24 * The content of the message is expected to be known by all parties.</p>
25 *
26 * <p>While a message is being sent to the listeners, any listener may choose to cancel
27 * the message. When cancelled, the message is not sent to any other listeners. Typically
28 * a listener higher in the topic hierarchy will cancel a message so that listeners lower
29 * do not receive it.</p>
30 *
31 * <p>Messages are independant of the topics they are published to. A listener receiving a
32 * message may send the same message instance to another topic, typically after adding
33 * information.</p>
34 *
35 * <p>Every message may be given a {@link MessageBrokerContext} to provide broker specific
36 * information that a receiver may need.</p>
37 *
38 * @author Trevor Milne
39 *
40 */
41
42 public class Message
43 {
44 /** The {@link MessageBrokerContext} of this message. */
45 protected MessageBrokerContext context;
46
47 /**
48 * The ({@link Properties}) object that properties are stored in.
49 *
50 */
51 protected Properties properties;
52
53 /** The destination topic of the message. */
54 protected MessageTopic destination;
55
56 /** The topic the message is currently being processed by. */
57 protected MessageTopic location;
58
59 /**
60 * The topic that the sender wishes the receiver to send a response message to.
61 *
62 */
63 protected MessageTopic replyToTopic;
64
65 /** An identifier to correlate replies with the requestor. */
66 protected int correlationId;
67
68 /** Specifies whether the message has been cancelled. */
69 protected boolean cancelled;
70
71
72 /* Constructors. */
73
74
75 /**
76 * Constructs a <code>Message</code>.
77 *
78 */
79
80 protected Message()
81 {
82 // no context initially
83 context = null;
84
85 // create properties
86 properties = new Properties();
87
88 // clear the message
89 clear();
90 }
91
92
93 /**
94 * Constructs a <code>Message</code> as a copy of another <code>Message</code>.
95 *
96 */
97
98 protected Message(Message message)
99 {
100 context = message.getContext();
101 properties = new Properties(message.getProperties());
102 destination = message.getDestination();
103 location = message.getLocation();
104 replyToTopic = message.getReplyTo();
105 correlationId = message.getCorrelationId();
106 cancelled = message.isCancelled();
107 }
108
109
110 /* Accessors. */
111
112
113 /**
114 * Returns the {@link MessageBrokerContext} for this message.
115 *
116 * @return The {@link MessageBrokerContext} for this message.
117 *
118 */
119
120 public MessageBrokerContext getContext()
121 {
122 return context;
123 }
124
125 /**
126 * Sets the {@link MessageBrokerContext} for this message.
127 *
128 * @param setContext The {@link MessageBrokerContext} for this message.
129 *
130 */
131
132 public void setContext(MessageBrokerContext setContext)
133 {
134 context = setContext;
135 }
136
137 /**
138 * Returns the {@link Properties} object for the storage and retrieval of message properties.
139 *
140 * @return The {@link Properties} object for this message.
141 *
142 */
143
144 public Properties getProperties()
145 {
146 return properties;
147 }
148
149 /**
150 * Returns the destination {@link MessageTopic} of this message.
151 *
152 * @return The destination {@link MessageTopic}.
153 *
154 */
155
156 public MessageTopic getDestination()
157 {
158 return destination;
159 }
160
161 /**
162 * Sets the destination {@link MessageTopic} of this message.
163 *
164 * @param setDestination The destination {@link MessageTopic}.
165 *
166 */
167
168 protected void setDestination(MessageTopic setDestination)
169 {
170 destination = setDestination;
171 }
172
173 /**
174 * Returns the {@link MessageTopic} that is currently processing this message.
175 *
176 * @return The current {@link MessageTopic}.
177 *
178 */
179
180 public MessageTopic getLocation()
181 {
182 return location;
183 }
184
185 /**
186 * Sets the {@link MessageTopic} currently processing this message.
187 *
188 * @param setLocation The {@link MessageTopic} current processing this message.
189 *
190 */
191
192 protected void setLocation(MessageTopic setLocation)
193 {
194 location = setLocation;
195 }
196
197 /**
198 * Returns the topic that the sender has requested that a reply be sent to.
199 *
200 * @return The {@link MessageTopic} to send a reply to.
201 *
202 */
203
204 public MessageTopic getReplyTo()
205 {
206 return replyToTopic;
207 }
208
209 /**
210 * Sets the topic that the sender wishes a reply to be sent to.
211 *
212 * @param topic The topic to send a reply to.
213 *
214 */
215
216 public void setReplyTo(MessageTopic topic)
217 {
218 replyToTopic = topic;
219 }
220
221 /**
222 * Returns the correlation identifier of this message.
223 *
224 * @return The correlation ID.
225 *
226 */
227
228 public int getCorrelationId()
229 {
230 return correlationId;
231 }
232
233 /**
234 * Sets the correlation identifier of this message.
235 *
236 * @param setCorrelationId The correlation ID.
237 *
238 */
239
240 public void setCorrelationId(int setCorrelationId)
241 {
242 correlationId = setCorrelationId;
243 }
244
245 /**
246 * Returns whether this message has been cancelled.
247 *
248 * @return True if cancelled, false otherwise.
249 *
250 */
251
252 public boolean isCancelled()
253 {
254 return cancelled;
255 }
256
257
258 /* Operations. */
259
260
261 /**
262 * Clears this message. This allows the same instance to be reused.
263 *
264 */
265
266 public void clear()
267 {
268 properties.clearProperties();
269
270 destination = null;
271 location = null;
272
273 replyToTopic = null;
274 correlationId = -1;
275
276 cancelled = false;
277 }
278
279 /**
280 * Cancels this message.
281 *
282 */
283
284 public void cancel()
285 {
286 cancelled = true;
287 }
288 }
289