1 /*------------------------------------------------------------------------------
  2 Name:      KeyData.h
  3 Project:   xmlBlaster.org
  4 Copyright: xmlBlaster.org, see xmlBlaster-LICENSE file
  5 ------------------------------------------------------------------------------*/
  6 #ifndef _UTIL_KEY_KEYDATA_H
  7 #define _UTIL_KEY_KEYDATA_H
  8 
  9 #include <util/xmlBlasterDef.h>
 10 #include <util/I_Log.h>
 11 #include <util/ReferenceCounterBase.h>
 12 #include <util/ReferenceHolder.h>
 13 
 14 namespace org { namespace xmlBlaster { namespace util { namespace key {
 15 
 16 /** The default content MIME type is null */
 17 extern Dll_Export const char* CONTENTMIME_DEFAULT;
 18 
 19 /** is "" */
 20 extern Dll_Export const char* DEFAULT_DOMAIN;
 21 
 22 /** The default queryType is "EXACT" */
 23 extern Dll_Export const char* QUERYTYPE_DEFAULT;
 24 
 25 /**
 26  * This class encapsulates the Message meta data and unique identifier (key)
 27  * of a publish()/update() or get()-return message.
 28  * <p />
 29  * A typical key could look like this:<br />
 30  * <pre>
 31  *     &lt;key oid='4711' contentMime='text/xml'>
 32  *        &lt;AGENT id='192.168.124.20' subId='1' type='generic'>
 33  *           &lt;DRIVER id='FileProof' pollingFreq='10'>
 34  *           &lt;/DRIVER>
 35  *        &lt;/AGENT>
 36  *     &lt;/key>
 37  * </pre>
 38  * <br />
 39  * Note that the AGENT and DRIVER tags are application know how, which you have
 40  * to supply to the setClientTags() method.<br />
 41  * A well designed xml hierarchy of your problem domain is essential for a proper working xmlBlaster
 42  * <p />
 43  * <p>
 44  * NOTE: Message oid starting with "__" is reserved for internal usage.
 45  * </p>
 46  * <p>
 47  * NOTE: Message oid starting with "_" is reserved for xmlBlaster plugins.
 48  * </p>
 49  */
 50 class Dll_Export KeyData : public org::xmlBlaster::util::ReferenceCounterBase
 51 {
 52 protected:
 53    std::string ME;
 54    org::xmlBlaster::util::Global& global_;
 55    org::xmlBlaster::util::I_Log&    log_;
 56 
 57    /** value from attribute <key oid="..."> */
 58    mutable std::string oid_;
 59 
 60    /** value from attribute <key oid="" contentMime="..."> */
 61    std::string contentMime_;
 62    
 63    /** value from attribute <key oid="" contentMimeExtended="..."> */
 64    std::string contentMimeExtended_;
 65 
 66    /** value from attribute <key oid="" domain="..."> */
 67    std::string domain_;
 68    
 69    /** Is the key oid generated? */
 70    mutable bool isGeneratedOid_;
 71    
 72    /** The query type */
 73    std::string queryType_;
 74    
 75    /** The query std::string */
 76    std::string queryString_;
 77 
 78    void init();
 79 
 80    void copy(const KeyData& key);
 81 
 82 public:
 83    /**
 84     * Minimal constructor.
 85     */
 86    KeyData(org::xmlBlaster::util::Global& global);
 87 
 88    /**
 89     * Copy constructor.
 90     */
 91    KeyData(const KeyData& key);
 92 
 93    /**
 94     * Assignement constructor.
 95     */
 96    KeyData& operator =(const KeyData& key);
 97 
 98    virtual ~KeyData();
 99 
100    void setOid(const std::string& oid);
101 
102    /**
103     *  @return The key oid or null if not set (see org::xmlBlaster::util::key::MsgKeyData.getOid() which generates the oid if it was null).
104     */
105    std::string getOid() const;
106 
107    /**
108     * Test if oid is '__sys__deadMessage'. 
109     * <p />
110     * Dead letters are unrecoverable lost messages, usually an administrator
111     * should subscribe to those messages.
112     * <p>
113     * This is an internal message (isInternal() returns true)
114     * </p>
115     */
116    bool isDeadMessage() const;
117 
118    /**
119     * Messages starting with "_" are reserved for usage in plugins
120     */
121    bool isPluginInternal() const;
122 
123    /**
124     * Messages starting with "__" are reserved for internal usage
125     */
126    bool isInternal() const;
127 
128    /**
129     * Messages starting with "__cmd:" are administrative messages
130     */
131    bool isAdministrative() const;
132 
133    /**
134     * Set mime type (syntax) of the message content. 
135     * @return The MIME type, for example "text/xml" in &lt;key oid='' contentMime='text/xml'><br />
136     *         default is "text/plain" if not set
137     * @see <a href="ftp://ftp.std.com/customers3/src/mail/istd::map-3.3/RFC1521.TXT">RFC1521 - MIME (Multipurpose Internet Mail Extensions)</a>
138     */
139    void setContentMime(const std::string& contentMime);
140 
141    /**
142     * Find out which mime type (syntax) the content of the message has.
143     * @return The MIME type, for example "text/xml" in &lt;key oid='' contentMime='text/xml'><br />
144     *         default is "text/plain" if not set
145     * @see <a href="ftp://ftp.std.com/customers3/src/mail/istd::map-3.3/RFC1521.TXT">RFC1521 - MIME (Multipurpose Internet Mail Extensions)</a>
146     */
147    std::string getContentMime() const;
148 
149    /**
150     * Some further specifying information of the content.
151     * <p />
152     * For example the application version number the document in the content.<br />
153     * You may use this attribute for you own purposes.
154     * @param The MIME-extended info, for example<br />
155     *         "Version 1.1" in &lt;key oid='' contentMime='text/xml' contentMimeExtended='Version 1.1'><br />
156     *         or "" (empty std::string) if not known
157     */
158    void setContentMimeExtended(const std::string& contentMimeExtended);
159 
160    /**
161     * Some further specifying information of the content.
162     * <p />
163     * For example the application version number the document in the content.<br />
164     * You may use this attribute for you own purposes.
165     * @return The MIME-extended info, for example<br />
166     *         "Version 1.1" in &lt;key oid='' contentMime='text/xml' contentMimeExtended='Version 1.1'><br />
167     *         or "" (empty std::string) if not known
168     */
169    std::string getContentMimeExtended() const;
170 
171    /**
172     * Set the domain for this message, can be used for a simple grouping of
173     * messages to their master node with xmlBlaster clusters. 
174     * @param The domain, any chosen std::string in your problem domain, e.g. "RUGBY" or "RADAR_TRACK"
175     *         defaults to "" where the local xmlBlaster instance is the master of the message.
176     * @see <a href="http://www.xmlblaster.org/xmlBlaster/doc/requirements/cluster.html">The cluster requirement</a>
177     */
178    void setDomain(const std::string& domain);
179 
180    /**
181     * Access the domain setting
182     * @return A domain std::string or null
183     */
184    std::string getDomain() const;
185 
186    /**
187     * @return true if no domain is given (null or empty std::string). 
188     */
189    bool isDefaultDomain() const;
190 
191    /**
192     * Access the query type "XPATH" or "EXACT"
193     * @return A queryType std::string or null
194     */
195    std::string getQueryType() const;
196 
197    bool isExact() const;
198 
199    bool isQuery() const;
200 
201    bool isXPath() const;
202 
203    bool isDomain() const;
204 
205    /**
206     * The size in bytes of the data in XML form. 
207     */
208    int size() const;
209 
210    /**
211     * Dump state of this object into a XML ASCII std::string. 
212     * <br>
213     * Needs to be implemented by derived classes.
214     * @param extraOffset indenting of tags for nice output
215     * @return internal state of the query as a XML ASCII std::string
216     */
217    virtual std::string toXml(const std::string& extraOffset) const;
218    virtual std::string toXml() const;
219 
220    /**
221     * Allocate a clone, the derived classes need to implement this method. 
222     * @return The caller needs to free it with 'delete'.
223     */
224    virtual KeyData* getClone() const;
225 
226    /**
227     * Generates a unique key oid in scope of a cluster node (on server or on client side).
228     * @param glob.getStrippedId() on server side
229     */
230    std::string generateOid(const std::string& uniquePrefix) const;
231    
232    /**
233     * @return true if the key oid is generated by xmlBlaster
234     */
235    bool isGeneratedOid() const;
236 };
237 
238 typedef org::xmlBlaster::util::ReferenceHolder<org::xmlBlaster::util::key::KeyData> KeyDataRef;
239 
240 }}}} // namespaces
241 
242 #endif


syntax highlighted by Code2HTML, v. 0.9.1