1 /*------------------------------------------------------------------------------
2 Name: PublishQos.h
3 Project: xmlBlaster.org
4 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
5 ------------------------------------------------------------------------------*/
6
7 /**
8 * This class encapsulates the qos of a publish() message.
9 * <p />
10 * So you don't need to type the 'ugly' XML ASCII std::string by yourself.
11 * After construction access the ASCII-XML std::string with the toXml() method.
12 * <br />
13 * A typical <b>publish</b> qos in Publish/Subcribe mode could look like this:<br />
14 * <pre>
15 * <qos>
16 * <priority>5</priority>
17 * <expiration lifeTime='60000'/>
18 * <persistent /> <!-- The message shall be recoverable if xmlBlaster crashes -->
19 * <forceUpdate>true</forceUpdate>
20 * <readonly />
21 * </qos>
22 * </pre>
23 * A typical <b>publish</b> qos in PtP mode could look like this:<br />
24 * <pre>
25 * <qos>
26 * <destination queryType='EXACT' forceQueuing='true'>
27 * joe
28 * </destination>
29 * <destination>
30 * /node/heron/client/Tim/-2
31 * </destination>
32 * </qos>
33 * </pre>
34 * <p />
35 * see xmlBlaster/src/dtd/XmlQoS.xml
36 * @see org.xmlBlaster.util.qos.MsgQosSaxFactory
37 * @see <a href="http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.publish.html">publish interface</a>
38 */
39
40 #ifndef _CLIENT_QOS_PUBLISHQOS_H
41 #define _CLIENT_QOS_PUBLISHQOS_H
42
43 #include <util/xmlBlasterDef.h>
44 #include <util/qos/storage/QueuePropertyBase.h>
45 #include <util/PriorityEnum.h>
46 #include <util/qos/MsgQosData.h>
47
48
49
50
51 namespace org { namespace xmlBlaster { namespace client { namespace qos {
52
53 class Dll_Export PublishQos
54 {
55 private:
56 std::string ME;
57 org::xmlBlaster::util::Global& global_;
58 org::xmlBlaster::util::qos::MsgQosData msgQosData_;
59
60 public:
61 /**
62 * Default constructor for transient messages.
63 */
64 PublishQos(org::xmlBlaster::util::Global& global);
65
66 /**
67 * Default constructor for transient PtP messages.
68 * <p />
69 * To make the message persistent, use the setPersistent(true) method
70 * @param destination The object containing the destination address.<br />
71 * To add more destinations, us the addDestination() method.
72 */
73 PublishQos(org::xmlBlaster::util::Global& global, const org::xmlBlaster::util::Destination& destination);
74
75 /**
76 * @param persistent true = store the message persistently
77 */
78 PublishQos(org::xmlBlaster::util::Global& global, bool persistent);
79
80 /**
81 * Returns the immutable internal data holder.
82 */
83 const org::xmlBlaster::util::qos::MsgQosData& getData();
84
85 /**
86 * Message priority.
87 * @return priority 0 (=Lowest) - 9 (=Highest)
88 */
89 org::xmlBlaster::util::PriorityEnum getPriority() const;
90
91 /**
92 * Set message priority value, org::xmlBlaster::util::PriorityEnum::NORM_PRIORITY (5) is default.
93 * org::xmlBlaster::util::PriorityEnum::MIN_PRIORITY (0) is slowest
94 * whereas org::xmlBlaster::util::PriorityEnum.MAX_PRIORITY (9) is highest priority.
95 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/engine.qos.publish.priority.html">The engine.qos.publish.priority requirement</a>
96 */
97 void setPriority(org::xmlBlaster::util::PriorityEnum priority);
98
99 /**
100 * Send message to subscriber even if the content is the same as the previous?
101 * <br />
102 * Default is that xmlBlaster does send messages to subscribed clients, even the content didn't change.
103 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/engine.qos.publish.forceUpdate.html">The engine.qos.publish.forceUpdate requirement</a>
104 */
105 void setForceUpdate(bool force);
106
107 /**
108 * Control message life cycle on message expiry.
109 * @param forceDestroy true Force message destroy on message expire<br />
110 * false On message expiry messages which are already in callback queues are delivered.
111 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/engine.qos.publish.isVolatile.html">The engine.qos.publish.isVolatile requirement</a>
112 */
113 void setForceDestroy(bool forceDestroy);
114
115 /**
116 * As a default setting you can subscribe on all messages (PtP or PubSub).
117 * @param isSubscribable true if Publish/Subscribe style is used<br />
118 * false Only possible for PtP messages to keep PtP secret (you can't subscribe them)
119 */
120 void setSubscribable(bool isSubcribeable);
121
122 /**
123 * Mark a message to be readonly.
124 * <br />
125 * Only the first publish() will be accepted, followers are denied.
126 */
127 void setReadonly(bool readonly);
128
129 /**
130 * Mark a message to be volatile or not.
131 * <br />
132 * A non-volatile messages stays in memory as long as the server runs<br />
133 * A volatile messages exists only during publish and processing it (doing the updates).<br />
134 * Defaults to false.
135 */
136 void setVolatile(bool volatileFlag);
137
138 /**
139 * @see #isVolatile()
140 */
141 bool isVolatile();
142
143 /**
144 * Mark a message to be persistent.
145 */
146 void setPersistent(bool persistent);
147
148 /**
149 * Mark a message to be administrative only.
150 * <p />
151 * It configures the topic and no message content is evaluated by server.
152 */
153 void setAdministrative(bool administrative);
154
155 /**
156 * The message expires after given milliseconds (message is erased).<p />
157 * Clients will get a notify about expiration.<br />
158 * This value is calculated relative to the rcvTimestamp in the xmlBlaster server.<br />
159 * Passing -1 milliseconds asks the server for unlimited livespan, which
160 * the server may or may not grant.
161 * @param lifeTime in milliseconds
162 */
163 void setLifeTime(long lifeTime);
164
165 /**
166 * Add a destination where to send the message.
167 * <p />
168 * Note you can invoke this multiple times to send to multiple destinations.
169 * @param destination The loginName of a receiver or some destination XPath query
170 */
171 void addDestination(const org::xmlBlaster::util::Destination& destination);
172
173 /**
174 * Access sender name.
175 * @return loginName of sender or null if not known
176 */
177 org::xmlBlaster::util::SessionNameRef getSender();
178
179 /*
180 * Access sender name.
181 * @param loginName of sender
182 * @deprecated The sender is forced to the correct client name automatically
183 */
184 //void setSender(const org::xmlBlaster::util::SessionName& sender);
185
186 /**
187 * @param state The state to return to the server.
188 * e.g. Contants.STATE_OK, see Constants::java
189 */
190 void setState(const std::string& state);
191
192 std::string getState();
193
194 /**
195 * @param stateInfo The state info attribute to return to the server.
196 */
197 void setStateInfo(const std::string& stateInfo);
198
199 std::string getStateInfo();
200
201 /**
202 * Administer/configure the message topic.
203 */
204 void setTopicProperty(const org::xmlBlaster::util::qos::TopicProperty& topicProperty);
205
206 /**
207 * Add a client property key and value.
208 * A typical example is:
209 * <pre>
210 * publishQos.addClientProperty("myKey", "myValue");
211 * </pre>
212 * If you want to send a string in your own locale character set:
213 * <pre>
214 * publishQos.addClientProperty("myKey", "myValue", Constants::TYPE_STRING, Constants::ENCODING_BASE64, "windows-1252");
215 * </pre>
216 * @param name The unique property key in US-ASCII encoding (7-bit), UTF-8 should work as well
217 * A duplicate key will overwrite the old setting
218 * @param value Your data . The type (like "float") is guessed from T_VALUE
219 * NOTE: "vector<unsigned char>" "unsigned char*" are
220 * treated as BLOBs and will be transferred Base64 encoded.
221 * @param type The data type of the value, optional, e.g. Constants::TYPE_FLOAT ("float")
222 * @param encoding How the data is transferred, org::xmlBlaster::util::Constants::ENCODING_BASE64 or ""
223 * @param charset XmlBlaster expects all XML strings as UTF-8, however you can send your client properties
224 * in any other charset but you must then encode it with ENCODING_BASE64 and pass the charset used, for example "windows-1252".
225 * Please use the official IANA charset names.
226 * @see http://www.iana.org/assignments/charset-reg/
227 * @see ClientProperty::#ClientProperty
228 */
229 template <typename T_VALUE> void addClientProperty(
230 const std::string& name,
231 const T_VALUE& value,
232 const std::string& type="",
233 const std::string& encoding="",
234 const std::string& charset="") {
235 msgQosData_.addClientProperty(name, value, type, encoding, charset);
236 }
237
238 /**
239 * Set all clientProperties at once, overwrites all existing.
240 * @param cm The new properties
241 */
242 void setClientProperties(const org::xmlBlaster::util::qos::QosData::ClientPropertyMap& cm);
243
244 /**
245 * Get a map containing all send client properties
246 */
247 const org::xmlBlaster::util::qos::QosData::ClientPropertyMap& getClientProperties() const;
248
249 /**
250 * Converts the data into a valid XML ASCII std::string.
251 * @return An XML ASCII std::string
252 */
253 std::string toString();
254
255 /**
256 * Converts the data into a valid XML ASCII std::string.
257 * @return An XML ASCII std::string
258 */
259 std::string toXml();
260 };
261
262 }}}}
263
264 #endif
syntax highlighted by Code2HTML, v. 0.9.1