1 /*------------------------------------------------------------------------------
2 Name: SubscribeQos.h
3 Project: xmlBlaster.org
4 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
5 ------------------------------------------------------------------------------*/
6
7 #ifndef _CLIENT_QOS_SUBSCRIBEQOS_H
8 #define _CLIENT_QOS_SUBSCRIBEQOS_H
9
10 #include <util/xmlBlasterDef.h>
11 #include <client/qos/GetQos.h>
12 #include <util/SessionName.h>
13 #include <client/key/SubscribeKey.h>
14
15 namespace org { namespace xmlBlaster { namespace client { namespace qos {
16
17 /**
18 * This class encapsulates the QoS (quality of service) of a subscribe() request.
19 * <p />
20 * A full specified <b>subscribe</b> qos could look like this:<br />
21 * <pre>
22 *<qos>
23 * <id>__subId:/node/heron/client/joe/3/34</id> < Force a subscription ID from client side -->
24 * <meta>false</meta> <!-- Don't send me the xmlKey meta data on updates -->
25 * <content>false</content> <!-- Don't send me the content data on updates (notify only) -->
26 * <local>false</local> <!-- Inhibit the delivery of messages to myself if i have published it -->
27 * <initialUpdate>false</initialUpdate>;
28 * <updateOneway>false</updateOneway>;
29 * <filter type='myPlugin' version='1.0'>a!=100</filter>
30 * <!-- Filters messages i have subscribed as implemented in your plugin -->
31 * <history numEntries='20'/> <!-- Default is to deliver the current entry (numEntries='1'), '-1' deliver all -->
32 *</qos>
33 * </pre>
34 * <p />
35 * see xmlBlaster/src/dtd/XmlQoS.xml
36 * @see org.xmlBlaster.util.qos.QueryQosData
37 * @see org.xmlBlaster.util.qos.QueryQosSaxFactory
38 * @see <a href="http://www.xmlblaster.org/xmlBlaster/doc/requirements/interface.subscribe.html">subscribe interface</a>
39 * @see <a href="http://www.xmlblaster.org/xmlBlaster/doc/requirements/mime.plugin.accessfilter.html">MIME access filter requirement</a>
40 */
41 class Dll_Export SubscribeQos : public GetQos
42 {
43 public:
44 SubscribeQos(org::xmlBlaster::util::Global& global);
45
46 SubscribeQos(org::xmlBlaster::util::Global& global, const org::xmlBlaster::util::qos::QueryQosData& data);
47
48 SubscribeQos(const SubscribeQos& qos);
49
50 SubscribeQos& operator =(const SubscribeQos& qos);
51
52 /**
53 * Do we want to have an initial update on subscribe if the message
54 * exists already?
55 *
56 * @return true if initial update wanted
57 * false if only updates on new publishes are sent
58 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/engine.qos.subscribe.initialUpdate.html">The engine.qos.subscribe.initialUpdate requirement</a>
59 */
60 void setWantInitialUpdate(bool initialUpdate);
61
62 /**
63 * Do we want the callback messages of this subscription as oneway with <tt>updateOneway()</tt> or with
64 * the acknowledged <tt>update()</tt>.
65 * @param updateOneway Defaults to false.
66 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.subscribe.html">The interface.subscribe requirement</a>
67 * @see QueryQosData#setWantUpdateOneway(boolean)
68 */
69 void setWantUpdateOneway(bool updateOneway);
70
71 /**
72 * Allow to subscribe multiple times to the same query/oid
73 * @param multiSubscribe defaults to true
74 */
75 void setMultiSubscribe(bool multiSubscribe);
76
77 bool getMultiSubscribe() const;
78
79 /**
80 * false Inhibit the delivery of messages to myself if i have published it.
81 */
82 void setWantLocal(bool local);
83
84 /**
85 * Notify me when the topic is erased on which i have subscribed
86 * @param notifyOnErase defaults to true
87 */
88 void setWantNotify(bool notifyOnErase);
89
90 /**
91 * Force the identifier (unique handle) for this subscription.
92 * Usually you let the identifier be generated by xmlBlaster.
93 * The call is handled as 'logically const'
94 * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/engine.qos.subscribe.id.html">The engine.qos.subscribe.id requirement</a>
95 */
96 void setSubscriptionId(const std::string& subscriptionId) const;
97
98 /**
99 * A client side subscriptionId must start with "__subId:" followed by the relative session name.
100 * <p>This us only useful for positive session Ids in fail save environments: if the
101 * subscription is queued the faked subscriptionId will be used later by the server</p>
102 * @param sessionName
103 * @param subscribeKey
104 * @return e.g. "__subId:client/joe/session/1-XPATH://key" for pubSessionId>0 and multiSubscribe=false
105 * or e.g. "__subId:client/joe-135692304540000" in other cases
106 */
107 std::string generateSubscriptionId(org::xmlBlaster::util::SessionNameRef sessionName, const org::xmlBlaster::client::key::SubscribeKey& subscribeKey);
108
109 bool hasSubscriptionId() const;
110
111 /**
112 * Sets the subscription to persistent (true) or not persistent (false).
113 * Setting this to true means that the subscription will implicitly
114 * make the associated session persistent and both will survive a
115 * server crash.
116 */
117 void setPersistent(bool persistent);
118
119 /**
120 * Add a client property key and value.
121 * @param name The unique key, a duplicate key will overwrite the old setting
122 * @param value "vector<unsigned char>" and "unsigned char *" types are treated as a blob
123 * @see ClientProperty::#ClientProperty
124 */
125 template <typename T_VALUE> void addClientProperty(
126 const std::string& name,
127 const T_VALUE& value,
128 const std::string& type="",
129 const std::string& encoding="") {
130 data_.addClientProperty(name, value, type, encoding);
131 }
132
133 };
134
135 }}}} // namespace
136
137 #endif
syntax highlighted by Code2HTML, v. 0.9.1