1 /*------------------------------------------------------------------------------
  2 Name:      SubscribeReturnQos.h
  3 Project:   xmlBlaster.org
  4 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
  5 ------------------------------------------------------------------------------*/
  6 
  7 /**
  8  * Handling the returned QoS (quality of service) of a subscribe() call.
  9  * <p />
 10  * If you are a Java client and use the XmlBlasterConnection helper class
 11  * you get this object as the subscribe() return value.
 12  * <p />
 13  * Example:
 14  * <pre>
 15  *   &lt;qos>
 16  *     &lt;state id='OK' info='QUEUED[bilbo]'/>
 17  *     &lt;subscribe id='_subId:1/>
 18  *  &lt;/qos>
 19  * </pre>
 20  * @see org.xmlBlaster.test.classtest.qos.StatusQosFactoryTest
 21  * @see <a href="http://www.xmlBlaster.org/xmlBlaster/doc/requirements/interface.subscribe.html" target="others">the interface.subscribe requirement</a>
 22  */
 23 
 24 #ifndef _CLIENT_QOS_SUBSCRIBERETURNQOS_H
 25 #define _CLIENT_QOS_SUBSCRIBERETURNQOS_H
 26 
 27 #include <util/qos/StatusQosData.h>
 28 
 29 namespace org { namespace xmlBlaster { namespace client { namespace qos {
 30 
 31 class Dll_Export SubscribeReturnQos
 32 {
 33 private:
 34    std::string ME;
 35    org::xmlBlaster::util::Global& global_;
 36    org::xmlBlaster::util::qos::StatusQosData data_;
 37 
 38 public:
 39 
 40    /**
 41     * Constructs the specialized quality of service object for status informations,
 42     * e.g. for a return of a subscribe() call
 43     * <p>
 44     * The state defaults to Constants::STATE_OK
 45     * </p>
 46     * @param global The stack
 47     * @param data The data object
 48     */
 49    SubscribeReturnQos(org::xmlBlaster::util::Global& global,
 50                       const org::xmlBlaster::util::qos::StatusQosData& data);
 51 
 52    SubscribeReturnQos(org::xmlBlaster::util::Global& global);
 53 
 54    SubscribeReturnQos(const SubscribeReturnQos& data);
 55 
 56    SubscribeReturnQos operator =(const SubscribeReturnQos& data);
 57 
 58    /**
 59     * Access state of message on update().
 60     * @return "OK", "ERROR" etc. See Constants::java
 61     */
 62    std::string getState() const;
 63 
 64    /**
 65     * Access state of message on update().
 66     * @return The human readable info text
 67     */
 68    std::string getStateInfo() const;
 69 
 70    /**
 71     * Access key oid. 
 72     * @return The unique identifier of a message
 73     */
 74    std::string getSubscriptionId() const;
 75 
 76    /**
 77     * gets the subscription status: persistent (true) or not persistent 
 78     * (false). If it is true it means that the subscription has implicitly
 79     * made the associated session persistent and both are surviving a
 80     * server crash. 
 81     */
 82    bool isPersistent() const;
 83 
 84    /**
 85     * Allows to check if the subscription request was queued on client side. 
 86     * <p>
 87     * If a subscribe is queued the return subscriptionId is generated on client side
 88     * and may on later connect not force to be the same on server side.
 89     * TODO: Enforce identical client + server side generation:
 90     * 1. If pubSessionId>0: <sessionName>-[EXACT:|XPATH:|DOMAIN:][topicOid|queryString]
 91     * 2. For none fail save clients any unique Id will do
 92     * </p>
 93     * @return true if subscribe is queued
 94     */
 95    bool isFakedReturn() const;
 96 
 97    /**
 98     * Dump state of this object into a XML ASCII std::string.
 99     * <br>
100     * @param extraOffset indenting of tags for nice output
101     * @return internal state of the status as a XML ASCII std::string
102     */
103    std::string toXml(const std::string& extraOffset="") const;
104 
105    org::xmlBlaster::util::qos::StatusQosData& getData();
106 
107 };
108 
109 }}}} // namespace
110 
111 #endif
syntax highlighted by Code2HTML, v. 0.9.1