1 /*------------------------------------------------------------------------------
2 Name: PublishQos.java
3 Project: xmlBlaster.org
4 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
5 ------------------------------------------------------------------------------*/
6 package org.xmlBlaster.client.qos;
7
8 import org.xmlBlaster.util.Global;
9 import org.xmlBlaster.util.XmlBlasterException;
10 import org.xmlBlaster.util.SessionName;
11 import org.xmlBlaster.util.def.PriorityEnum;
12 import org.xmlBlaster.util.qos.MsgQosData;
13 import org.xmlBlaster.util.qos.ClientProperty;
14 import org.xmlBlaster.util.qos.address.Destination;
15 import org.xmlBlaster.util.qos.TopicProperty;
16 import org.xmlBlaster.util.def.MethodName;
17
18
19 /**
20 * This class encapsulates the qos of a publish() message.
21 * <p />
22 * So you don't need to type the 'ugly' XML ASCII string by yourself.
23 * After construction access the ASCII-XML string with the toXml() method.
24 * <br />
25 * A typical <b>publish</b> qos in Publish/Subcribe mode could look like this:<br />
26 * <pre>
27 * <qos>
28 * <priority>5</priority>
29 * <expiration lifeTime='60000' forceDestroy='false'/>
30 * <persistent /> <!-- The message shall be recoverable if xmlBlaster crashes -->
31 * <forceUpdate>true</forceUpdate>
32 * <readonly />
33 * </qos>
34 * </pre>
35 * A typical <b>publish</b> qos in PtP mode could look like this:<br />
36 * <pre>
37 * <qos>
38 * <destination queryType='EXACT' forceQueuing='true'>
39 * joe
40 * </destination>
41 * <destination>
42 * /node/heron/client/Tim/-2
43 * </destination>
44 * </qos>
45 * </pre>
46 * <p />
47 * see xmlBlaster/src/dtd/XmlQoS.xml
48 * @see org.xmlBlaster.util.qos.MsgQosSaxFactory
49 * @see <a href="http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.publish.html">publish interface</a>
50 */
51 public final class PublishQos
52 {
53 private final Global glob;
54 private final MsgQosData msgQosData;
55
56 public PublishQos(Global glob, String serialData) {
57 this.glob = (glob==null) ? Global.instance() : glob;
58 this.msgQosData = new MsgQosData(this.glob, this.glob.getMsgQosFactory(), serialData, MethodName.PUBLISH);
59 this.msgQosData.setMethod(MethodName.PUBLISH);
60 }
61
62 /**
63 * Default constructor for transient messages.
64 */
65 public PublishQos(Global glob) {
66 this.glob = (glob==null) ? Global.instance() : glob;
67 this.msgQosData = new MsgQosData(this.glob, this.glob.getMsgQosFactory(), MethodName.PUBLISH);
68 this.msgQosData.setMethod(MethodName.PUBLISH);
69 /*
70 // deprecated:
71 long lt = this.glob.getProperty().get("message.lifeTime", -1L);
72 if (lt != -1L) {
73 this.msgQosData.getLifeTimeProp().setValue(lt, PropEntry.CREATED_BY_PROPFILE);
74 }
75 */
76 }
77
78 /**
79 * Default constructor for transient PtP messages.
80 * <p />
81 * To make the message persistent, use the setPersistent() method
82 * @param destination The object containing the destination address.<br />
83 * To add more destinations, us the addDestination() method.
84 */
85 public PublishQos(Global glob, Destination destination) {
86 this(glob);
87 addDestination(destination);
88 }
89
90 /**
91 * @param persistent true = store the message persistently
92 */
93 public PublishQos(Global glob, boolean persistent) {
94 this(glob);
95 setPersistent(persistent);
96 }
97
98 public MsgQosData getData() {
99 return this.msgQosData;
100 }
101
102 /**
103 * As a default setting you can subscribe on all messages (PtP or PubSub).
104 * @param isSubscribable true if Publish/Subscribe style is used<br />
105 * false Only possible for PtP messages to keep PtP secret (you can't subscribe them)
106 */
107 public void setSubscribable(boolean isSubscribable) {
108 this.msgQosData.setSubscribable(isSubscribable);
109 }
110
111 /**
112 * Message priority.
113 * @return priority 0 (=Lowest) - 9 (=Highest)
114 */
115 public PriorityEnum getPriority() {
116 return this.msgQosData.getPriority();
117 }
118
119 /**
120 * Set message priority value, PriorityEnum.NORM_PRIORITY (5) is default.
121 * PriorityEnum.MIN_PRIORITY (0) is slowest
122 * whereas PriorityEnum.MAX_PRIORITY (9) is highest priority.
123 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/engine.qos.publish.priority.html">The engine.qos.publish.priority requirement</a>
124 */
125 public void setPriority(PriorityEnum priority) {
126 this.msgQosData.setPriority(priority);
127 }
128
129 /**
130 * Send message to subscriber even if the content is the same as the previous?
131 * <br />
132 * Default is that xmlBlaster does send messages to subscribed clients, even the content didn't change.
133 */
134 public void setForceUpdate(boolean force) {
135 this.msgQosData.setForceUpdate(force);
136 }
137
138 /**
139 * Mark a message to be readonly.
140 * <br />
141 * Only the first publish() will be accepted, followers are denied.
142 */
143 public void setReadonly(boolean readonly) {
144 this.msgQosData.setReadonly(readonly);
145 }
146
147 /**
148 * Mark a message to be volatile or not.
149 * <br />
150 * A non-volatile messages stays in memory as long as the server runs or the message expires.<br />
151 * A volatile messages exists only during publish and processing it (doing the updates).<br />
152 * Defaults to false.
153 * <br />
154 * NOTE: This is a convenience method for setLifeTime(0L) and setForceDestroy(false).
155 */
156 public void setVolatile(boolean volatileFlag) {
157 this.msgQosData.setVolatile(volatileFlag);
158 }
159
160 /**
161 * @see #isVolatile()
162 */
163 public boolean isVolatile() {
164 return this.msgQosData.isVolatile();
165 }
166
167 /**
168 * Mark a message to be persistent.
169 */
170 public void setPersistent(boolean persistent) {
171 this.msgQosData.setPersistent(persistent);
172 }
173
174 /**
175 * The message expires after given milliseconds.
176 * @param lifeTime in milliseconds
177 * @see MsgQosData#setLifeTime(long)
178 */
179 public void setLifeTime(long lifeTime) {
180 this.msgQosData.setLifeTime(lifeTime);
181 }
182
183 /**
184 * Control message life cycle on message expiry, defaults to false.
185 * @param forceDestroy true Force message destroy on message expire<br />
186 * false On message expiry messages which are already in callback queues are delivered.
187 */
188 public void setForceDestroy(boolean forceDestroy) {
189 this.msgQosData.setForceDestroy(forceDestroy);
190 }
191
192 /**
193 * Add a destination where to send the message.
194 * <p />
195 * Note you can invoke this multiple times to send to multiple destinations.
196 * <p />
197 * Note that the default lifeTime is set to 0 (PtP are volatile messages as default)
198 * @param destination The loginName of a receiver or some destination XPath query
199 */
200 public void addDestination(Destination destination) {
201 this.msgQosData.addDestination(destination);
202 }
203
204 /**
205 * Access sender name.
206 * @return loginName of sender or null if not known
207 */
208 public SessionName getSender() {
209 return this.msgQosData.getSender();
210 }
211
212 /**
213 * Access sender name.
214 * @param loginName of sender
215 */
216 public void setSender(SessionName sender) {
217 this.msgQosData.setSender(sender);
218 }
219
220 public void setAdministrative(boolean administrative) {
221 this.msgQosData.setAdministrative(administrative);
222 }
223
224 /**
225 * @param state The state to return to the server.
226 * e.g. Contants.STATE_OK, see Constants.java
227 */
228 public void setState(String state) {
229 this.msgQosData.setState(state);
230 }
231
232 public String getState() {
233 return this.msgQosData.getState();
234 }
235
236 /**
237 * @param stateInfo The state info attribute to return to the server.
238 */
239 public void setStateInfo(String stateInfo) {
240 this.msgQosData.setStateInfo(stateInfo);
241 }
242
243 public String getStateInfo() {
244 return this.msgQosData.getStateInfo();
245 }
246
247 /**
248 * Administer/configure the message topic.
249 */
250 public void setTopicProperty(TopicProperty topicProperty) {
251 this.msgQosData.setTopicProperty(topicProperty);
252 }
253
254 /**
255 * Sets a client property (an application specific property) to the
256 * given value
257 * @param key
258 * @param value
259 */
260 public void addClientProperty(String key, Object value) {
261 this.msgQosData.addClientProperty(key, value);
262 }
263
264 public void addClientProperty(String key, boolean value) {
265 this.msgQosData.addClientProperty(key, value);
266 }
267
268 public void addClientProperty(String key, int value) {
269 this.msgQosData.addClientProperty(key, value);
270 }
271
272 public void addClientProperty(String key, byte value) {
273 this.msgQosData.addClientProperty(key, value);
274 }
275
276 public void addClientProperty(String key, long value) {
277 this.msgQosData.addClientProperty(key, value);
278 }
279
280 public void addClientProperty(String key, short value) {
281 this.msgQosData.addClientProperty(key, value);
282 }
283
284 public void addClientProperty(String key, double value) {
285 this.msgQosData.addClientProperty(key, value);
286 }
287
288 public void addClientProperty(String key, float value) {
289 this.msgQosData.addClientProperty(key, value);
290 }
291
292 /**
293 * Read back a property.
294 * @return The client property or null if not found
295 */
296 public ClientProperty getClientProperty(String key) {
297 return this.msgQosData.getClientProperty(key);
298 }
299
300 /**
301 * Converts the data into a valid XML ASCII string.
302 * @return An XML ASCII string
303 */
304 public String toString() {
305 return toXml();
306 }
307
308 /**
309 * Converts the data into a valid XML ASCII string.
310 * @return An XML ASCII string
311 */
312 public String toXml() {
313 return this.msgQosData.toXml();
314 }
315
316 /**
317 * For testing invoke: java org.xmlBlaster.client.PublishQos
318 */
319 public static void main( String[] args ) throws XmlBlasterException
320 {
321 Global glob = new Global(args);
322 {
323 PublishQos qos =new PublishQos(new Global(args), new Destination(new SessionName(glob, "joe")));
324 qos.addDestination(new Destination(new SessionName(glob, "Tim")));
325 qos.setPriority(PriorityEnum.HIGH_PRIORITY);
326 qos.setPersistent(true);
327 qos.setForceUpdate(true);
328 qos.setReadonly(true);
329 qos.setLifeTime(60000);
330 System.out.println(qos.toXml());
331 }
332 {
333 PublishQos qos =new PublishQos(null);
334 System.out.println("Minimal '" + qos.toXml() + "'");
335 }
336 }
337 }
syntax highlighted by Code2HTML, v. 0.9.1