1 /*------------------------------------------------------------------------------
2 Name: MsgQosData.h
3 Project: xmlBlaster.org
4 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
5 ------------------------------------------------------------------------------*/
6
7 /**
8 * Data container handling of publish() and update() quality of services.
9 * <p />
10 * QoS Informations sent from the client to the server via the publish() method and back via the update() method<br />
11 * They are needed to control xmlBlaster and inform the client.
12 * <p />
13 * <p>
14 * This data holder is accessible through 4 decorators, each of them allowing a specialized view on the data:
15 * </p>
16 * <ul>
17 * <li>PublishQosServer Server side access</i>
18 * <li>PublishQos Client side access</i>
19 * <li>UpdateQosServer Server side access facade</i>
20 * <li>UpdateQos Client side access facade</i>
21 * </ul>
22 * <p>
23 * For the xml representation see MsgQosSaxFactory.
24 * </p>
25 * @see org.xmlBlaster.util.qos.MsgQosSaxFactory
26 * @see org.xmlBlaster.test.classtest.qos.MsgQosFactoryTest
27 * @author xmlBlaster@marcelruff.info
28 * @author laghi@swissinfo.org
29 */
30
31 #ifndef _XMLBLASTER_UTIL_QOS_MSGQOSDATA_H
32 #define _XMLBLASTER_UTIL_QOS_MSGQOSDATA_H
33
34 #include <util/xmlBlasterDef.h>
35 #include <util/qos/QosData.h>
36
37 #include <util/Destination.h>
38 #include <util/qos/TopicProperty.h>
39 #include <util/cluster/RouteInfo.h>
40 #include <util/cluster/NodeId.h>
41 #include <util/Prop.h>
42 #include <vector>
43 #include <string>
44
45 namespace org { namespace xmlBlaster { namespace util { namespace qos {
46
47 class Dll_Export MsgQosData : public QosData
48 {
49 private:
50
51 mutable bool isExpired_; // = false; // cache the expired state for performance reasons
52
53 bool administrative_;
54
55 org::xmlBlaster::util::qos::TopicProperty* topicProperty_;
56
57 /**
58 * A message lease lasts forever if not otherwise specified. <p />
59 * The default message life cycle can be modified in xmlBlaster.properties:<br />
60 * <code>message.lease.maxLifeTime=3600000 # One hour lease</code><br />
61 * Every message can set the lifeTime value between 1 and maxLifeTime,
62 * -1L sets the life cycle on forever.
63 */ // TODO: Change to use glob instead of org::xmlBlaster::util::Global singleton! What about performance? Put variable into org::xmlBlaster::util::Global?
64 long maxLifeTime_;
65
66 /*
67 {
68 return org::xmlBlaster::util::Global.instance().getProperty().get("message.maxLifeTime", -1L);
69 }
70 */
71
72 /** If Pub/Sub style update: contains the subscribe ID which caused this update */
73 std::string subscriptionId_;
74
75 Prop<bool> subscribable_;
76
77 /** the number of resend tries on failure */
78 int redeliver_;
79 long queueIndex_; // = -1L;
80 long queueSize_; // = -1L;
81
82 /**
83 * Send message to subscriber even the content is the same as the previous?
84 * <br />
85 * Default is that xmlBlaster does send messages to subscribed clients, even the content didn't change.
86 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/engine.qos.publish.forceUpdate.html">The engine.qos.publish.forceUpdate requirement</a>
87 */
88 Prop<bool> forceUpdate_; // = DEFAULT_forceUpdate;
89 Prop<bool> forceDestroy_;
90
91 /**
92 * A message expires after some time and will be discarded.
93 * Clients will get a notify about expiration.
94 * This is the configured lifeTime in millis of the message.
95 */
96 long lifeTime_; // = -1;
97
98 long remainingLifeStatic_; // = -1;
99
100 void init();
101
102 protected:
103 /**
104 * ArrayList for loginQoS, holding all destination addresses (Destination objects)
105 */
106 std::vector<Destination> destinationList_;
107
108
109 // TODO: Pass with client QoS!!!
110 bool receiveTimestampHumanReadable_; // = org::xmlBlaster::util::Global.instance().getProperty().get("cb.receiveTimestampHumanReadable", false);
111
112 void copy(const MsgQosData& data);
113
114 public:
115 /**
116 * Constructs the specialized quality of service object for a publish() or update() call.
117 * @param The factory which knows how to serialize and parse me
118 */
119 // long size_;
120
121 MsgQosData(org::xmlBlaster::util::Global& global, const std::string& serialData="");
122
123 MsgQosData(const MsgQosData& data);
124
125 MsgQosData& operator=(const MsgQosData& data);
126
127 virtual ~MsgQosData();
128
129 /**
130 * @param administrative mark a message as administrative to configure the topic
131 */
132 void setAdministrative(bool administrative);
133
134 /**
135 * @return true/false
136 */
137 bool isAdministrative() const;
138
139 /**
140 * As a default setting you can subscribe on all messages (PtP or PubSub).
141 * @param isSubscribable true if Publish/Subscribe style is used<br />
142 * false Only possible for PtP messages to keep PtP secret (you can't subscribe them)
143 */
144 void setSubscribable(const bool isSubcribeable);
145
146 /**
147 * Test if Publish/Subscribe style is used for PtP messages.
148 *
149 * @return false if PtP message is invisible for subscribes
150 */
151 bool isSubscribable() const;
152
153 /**
154 * Test if Point to Point addressing style is used.
155 *
156 * @return true if addressing of the destination is used
157 * false No destinations given
158 */
159 bool isPtp() const;
160
161 /**
162 * @param volatile true/false
163 */
164 void setVolatile(bool volatileFlag);
165
166 /**
167 * @return true/false
168 */
169 bool isVolatile() const;
170
171 /**
172 * @return true If the default is the current setting.
173 */
174 bool isVolatileDefault() const;
175
176 /**
177 * If Pub/Sub style update: contains the subscribe ID which caused this update
178 * @param subscriptionId null if PtP message
179 */
180 void setSubscriptionId(const std::string& subscriptionId);
181
182 /**
183 * If Pub/Sub style update: contains the subscribe ID which caused this update
184 * @return subscribeId or null if PtP message
185 */
186 std::string getSubscriptionId() const;
187
188 /**
189 * Send message to subscriber even if the content is the same as the previous.
190 * @param forceUpdate
191 */
192 void setForceUpdate(bool forceUpdate);
193
194 /**
195 * @return true/false
196 */
197 bool isForceUpdate() const;
198
199 /**
200 * @return readonly Once published the message can't be changed.
201 */
202 void setReadonly(bool readonly);
203
204 /**
205 * @return true/false
206 */
207 bool isReadonly() const;
208
209 /**
210 * Set > 0 if the message probably is redelivered (number of retries).
211 * @param redeliver if == 0 The message is guaranteed to be delivered only once.
212 */
213 void setRedeliver(int redeliver);
214
215 /**
216 * Increment the redeliver counter
217 */
218 void incrRedeliver();
219
220 /**
221 * Returns > 0 if the message probably is redelivered.
222 * @return == 0 The message is guaranteed to be delivered only once.
223 */
224 int getRedeliver() const;
225
226 /**
227 * @param queueSize The number of queued messages
228 */
229 void setQueueSize(long queueSize);
230
231 /**
232 * @return The number of queued messages
233 */
234 long getQueueSize() const;
235
236 /**
237 * @param queueIndex The index of the message in the queue
238 */
239 void setQueueIndex(long queueIndex);
240
241 /**
242 * @return The index of the message in the queue
243 */
244 long getQueueIndex() const;
245
246 /**
247 * The life time of the message or -1L if forever
248 */
249 long getLifeTime()const;
250
251 /**
252 * The life time of the message or -1L if forever
253 */
254 void setLifeTime(long lifeTime);
255
256 /**
257 * @return Milliseconds until message expiration (from now) or -1L if forever
258 * if 0L the message is expired
259 */
260 long getRemainingLife() const;
261
262 /**
263 * This is the value delivered in the QoS (as it was calculated by the server on sending)
264 * and is NOT dynamically recalculated.
265 * So trust this value only if your client clock is out of date (or not trusted) and
266 * if you know the message sending latency is not too big.
267 * @return Milliseconds until message expiration (from now) or -1L if forever
268 * if 0L the message is expired
269 */
270 long getRemainingLifeStatic() const;
271
272 void setRemainingLifeStatic(long remainingLifeStatic);
273
274 /**
275 * Calculates if we are expired
276 */
277 bool isExpired() const;
278
279 /**
280 * The server default for max. span of life,
281 * adjustable with property "message.maxLifeTime"
282 * @return max span of life for a message
283 */
284 long getMaxLifeTime() const;
285
286 /**
287 * Tagged form of message receive, e.g.:<br />
288 * <rcvTimestamp nanos='1007764305862000004'/>
289 *
290 * @see org.xmlBlaster.util.Timestamp
291 */
292 std::string getXmlRcvTimestamp();
293
294 /**
295 * Set timestamp to current time.
296 */
297 void touchRcvTimestamp();
298
299 /**
300 * Get all the destinations of this message.
301 * This should only be used with PTP style messaging<br />
302 * Check <code>if (isPtp()) ...</code> before calling this method
303 *
304 * @return a valid ArrayList containing 0 - n std::strings with destination names (loginName of clients)<br />
305 * null if Publish/Subscribe style is used
306 */
307 std::vector<Destination> getDestinations() const;
308
309 /**
310 * Add a destination.
311 * The destination is copied into a list - your instance can be savly disappear
312 */
313 void addDestination(const Destination& destination);
314
315 /**
316 * Dump state of this object into a XML ASCII std::string.
317 * <br>
318 * @param clearText Dump base64 clientProperties encoded as plain text
319 * @param extraOffset indenting of tags for nice output
320 * @return internal state of the message QoS as a XML ASCII std::string
321 */
322 virtual std::string toXml(bool clearText, const std::string& extraOffset="") const;
323
324 virtual std::string toXml(const std::string& extraOffset="") const;
325
326 /**
327 * Allocate a clone, the derived classes need to implement this method.
328 * @return The caller needs to free it with 'delete'.
329 */
330 virtual MsgQosData* getClone() const;
331
332 void setTopicProperty(const org::xmlBlaster::util::qos::TopicProperty& prop);
333
334 org::xmlBlaster::util::qos::TopicProperty getTopicProperty();
335
336 bool hasTopicProperty() const;
337
338 /**
339 * Control message life cycle on message expiry.
340 * @param forceDestroy true Force message destroy on message expire<br />
341 * false On message expiry messages which are already in callback queues are delivered.
342 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/engine.qos.publish.isVolatile.html">The engine.qos.publish.isVolatile requirement</a>
343 */
344 void setForceDestroy(bool forceDestroy);
345
346 bool isForceDestroy() const;
347
348 };
349
350 }}}}
351
352 #endif
syntax highlighted by Code2HTML, v. 0.9.1