XmlBlaster Logo

REQUIREMENT

interface.subscribe

XmlBlaster Logo


Type NEW
Priority HIGH
Status CLOSED
Topic Messages are asynchronous accessed with the subscribe() method
Des
cription

The subscribe() method allows to subscribe for messages in xmlBlaster. You can subscribe with exactly one message by passing its oid, or by a selection of message by passing a XPATH query.

Subscribed messages are sent to the callback servers update() method. Clients have to establish a callback server instance to allow asynchronous callbacks.

Method detail (CORBA IDL notation): 

   typedef string XmlType;
   typedef sequence<string> StringArr;

   XmlType subscribe(in XmlType xmlKey, in XmlType qos) raises(XmlBlasterException);
ParameterTypeDescription
xmlKeystringThe XML encoded key containing the oid or XPATH query to select messages to subscribe
xmlQosstringThe XML encoded Quality of Service QoS (see SubscribeQos link below)
returnstring An XML encoded string containing status and the unique subscription ID (see SubscribeReturnQos link below). You need to remember the subscriptionId for unsubscribing later.
XmlBlasterExceptionexceptionThrown on error

Here is an overview of all available subscribe QoS: 

<qos>
   <!-- Force a subscription ID from client side -->
   <subscribe id='__subId:client/subscriber/session/1-exact:MyHelloTopic'/>

   <!-- Recoverable subscription after server crash / restart -->
   <persistent/>

   <!-- Don't send me the xmlKey meta data on updates (default: true) -->
   <meta>false</meta>
   
   <!-- Don't send me the content data on updates (notify only) (default: true) -->
   <content>false</content>
   
   <!-- false: Ignore a second subscribe on same oid or XPATH (default: true) -->
   <multiSubscribe>false</multiSubscribe>

   <!-- Inhibit the delivery of messages to myself if i have published it (default: true) -->
   <local>false</local>
   
   <!-- don't send an initial message after subscribe (default: true) -->
   <initialUpdate>false</initialUpdate>
   
   <!-- send callbacks messages for this subscription with the better performing -->
   <!-- updateOneway() instead of the more reliable update() (default: false) -->
   <!-- Note: The SOCKET protocol plugin supports additionally the faster UDP transfer -->
   <updateOneway>true</updateOneway>
   
   <!-- Suppress erase event to subscribers (default: true) -->
   <notify>false</notify>
   
   <!-- Filters messages i have subscribed as implemented in your plugin -->
   <!-- Here we use the RegEx filter and only want content starting with 'H' -->
   <filter type='GnuRegexFilter' version='1.0'>^H.*$</filter>

   <!-- http://www.xmlblaster.org/xmlBlaster/doc/requirements/engine.qos.queryspec.html -->
   <querySpec type='QueueQuery' version='1.0'>
      <![CDATA[maxEntries=3;maxSize=-1;consumable=false;waitingDelay=0]]>
   </querySpec>
                                
   <!-- Default is to deliver the current entry (numEntries='1'), '-1' deliver all (default: 1) -->
   <!-- newestFirst let you change the delivery order, it defaults to true -->
   <!-- The higher priority messages are always delivered first. -->
   <!-- In one priority the newest message is delivered first with 'true', setting 'false' -->
   <!-- reverts the delivery sequence in this priority. -->
   <history numEntries='20' newestFirst='true'/>
</qos>

Detailed description

Flag Description
persistent You can mark a subscription to be persistent. If the server crashes or is restarted the clients session and this subscription is restored. Please read the engine.persistence.subscription requirements for details.
multiSubscribe If you subscribe with the same client (the same login session) multiple times to the same message you will receive this message multiple times, one update for each subscription. This can be suppressed, for details please read the engine.qos.subscribe.multiSubscribe requirement.
notify If set to true (which is default) an erase notification message is sent to the subscriber when the topic is erased. The state in the message UpdateQoS is set to Constants.STATE_ERASED="ERASED"
Note: For exact subscriptions this subscription gets invalid when the topic is explicitly erased and you need to subscribe again. For XPath subscriptions the subscription remains, if the same topic is created again the Xpath will match and renew the subscription. Here you may choose to set notify to false.
filter To further filter messages with a full text analyze you can add a filter rule. Please read the mime.plugin.accessfilter requirements for details. There are XPath, regular expression and SQL 92 filter plugins available.
__newestOnly You can add a clientProperty __newestOnly=true. In this case xmlBlaster throws away all oder messages of this topic which are in the callback queue of the subscriber and delivers only the most current. This use case is useful for mobile clients being off line for longer periods and the topic delivers complete updates of some information. The client don't wants to receive the outdated older updates.

A special note how to subscribe in cluster environments:

If you subscribe to a cluster slave node, the subscription is only forwarded to a master node if the subscription key matches the configured master selection.

The return string of subscribe()

On successful call the subscribe() method returns detailed informations: The state = "OK" means everything was successful.
A state = "WARNING" is indicating that a multiple subscription was ignored.
A stateInfo = "QUEUED" tells you that the subcription was queued on client side as there is currently no connection to the server (we are polling). Note that the returned subscriptionId is generated on client side and wont match a server side subscriptionId of a previous persistent subscribe.

Note:
If a subscribe is queued on client side the return subscriptionId is generated on client side and may on later connect not force to be the same on server side.
The client side generated is assured to be identical if you use a positive public sessionId and have set multiSubscribe to false (a typical fail safe configured client).
1. If pubSessionId>0: <sessionName>-[EXACT:|XPATH:|DOMAIN:][topicOid|queryString]
Usually you let the identifier be generated by xmlBlaster, it is done automatically for clients with publicSessionId > 0 and multiSubscribe=false. Such ids are also routed properly in cluster environments.

Example of a reproducable subscriptionID in a queued return qos (e.g. after client restart):

<qos>
  <state id='OK' info='QUEUED'/>
  <subscribe id='__subId:client/subscriber/session/1-exact:PublishToSlave.RUGBY_NEWS'/>
</qos>

2. For none fail save clients any unique Id will do

Example of a queued return qos:

<qos>
  <state id='OK' info='QUEUED'/>
  <subscribe id='__subId:client/joe/session/1-1166021247822779000'/>
</qos>
Example
XML

Here is an example of an exact query:

Key<key oid='MyMessage' />
QoS<qos><initialUpdate>false</initialUpdate></qos>

The topic MyMessage is queried and no initial update of existing history messages is delivered.

And a return value: 

<qos>
   <state id='OK'/>
   <subscribe id='__subId:34023'/>
</qos>
Example
XML

Here is an example of an XPATH query:

Key<key oid='' queryType='XPATH'> /xmlBlaster/key[starts-with(@oid,'radar.')] </key>
QoS<qos/>

All topics which oid starts with radar. is queried.

And the returned value: 

<qos>
   <state id='OK'/>
   <subscribe id='__subId:XPATH67'/>
</qos>
Example
XML

A subscription in a cluster environment belonging to domain RUGBY_NEWS

Key<key oid='MyMessage' domain='RUGBY_NEWS' />
QoS<qos/>

And a return value: 

<qos>
   <state id='OK'/>
   <subscribe id='__subId:34023'/>
</qos>
Example
XmlRpc

This is the XmlRpc server interface variant: 

   public String subscribe(String sessionId, String xmlKey_literal, String qos_literal)
                                                         throws XmlBlasterException
Example
Java

A typical Java client code for an EXACT subscription: 

   import org.xmlBlaster.client.key.SubscribeKey;
   import org.xmlBlaster.client.qos.SubscribeQos;
   import org.xmlBlaster.client.qos.SubscribeReturnQos;

   ...

   SubscribeKey sk = new SubscribeKey(glob, "MyOid");

   SubscribeQos sq = new SubscribeQos(glob);

   SubscribeReturnQos sr = con.subscribe(sk.toXml(), sq.toXml());

   System.out.println("Success, subscriptionId=" + sr.getSubscriptionId());

See xmlBlaster/demo/HelloWorld*.java for more examples.

Example
Java

A typical Java client code for an XPATH subscription: 

   import org.xmlBlaster.client.key.SubscribeKey;
   import org.xmlBlaster.client.qos.SubscribeQos;
   import org.xmlBlaster.client.qos.SubscribeReturnQos;
   import org.xmlBlaster.util.def.Constants;

   ...

   SubscribeKey sk = new SubscribeKey(glob, "/xmlBlaster/key[@oid='radar.track']",
                            Constants.XPATH);

   SubscribeQos sq = new SubscribeQos(glob);

   SubscribeReturnQos sr = con.subscribe(sk.toXml(), sq.toXml());

   System.out.println("Success, subscriptionId=" + sr.getSubscriptionId());
Example
Java

A typical Java client code for a subscriptions in a cluster environment which uses selection of master nodes with message domains: 

   import org.xmlBlaster.client.key.SubscribeKey;
   import org.xmlBlaster.client.qos.SubscribeQos;
   import org.xmlBlaster.client.qos.SubscribeReturnQos;

   ...

   SubscribeKey sk = new SubscribeKey(glob, "MyMessageOid");

   sk.setDomain("RUGBY_NEWS"); // Subscription is forwarded from slaves to master
   // without setting the domain the subscribe would just be handled by the slave connected to

   SubscribeReturnQos sr = con.subscribe(sk.toXml(), null);

   System.out.println("Success, subscriptionId=" + sr.getSubscriptionId());
Configure

NOTE: Configuration parameters are specified on command line (-someValue 17) or in the xmlBlaster.properties file (someValue=17). See requirement "util.property" for details.
Columns named Impl tells you if the feature is implemented.
Columns named Hot tells you if the configuration is changeable in hot operation.

See REQ interface
See REQ engine.qos.subscribe.id
See REQ engine.qos.subscribe.duplicate
See REQ engine.qos.subscribe.multiSubscribe
See REQ client.subscribe.dispatch
See REQ mime.plugin.accessfilter
See ../../demo/javaclients/HelloWorldSubscribe.java.html
See API org.xmlBlaster.engine.xml2java.XmlKey
See API org.xmlBlaster.client.qos.SubscribeQos
See API org.xmlBlaster.client.qos.SubscribeReturnQos
See API org.xmlBlaster.client.I_XmlBlasterAccess
See API org.xmlBlaster.protocol.xmlrpc.XmlBlasterImpl
See TEST org.xmlBlaster.test.qos.TestSub
See TEST org.xmlBlaster.test.qos.TestSubExact
See TEST org.xmlBlaster.test.qos.TestSubXPath
See TEST org.xmlBlaster.test.qos.TestSubManyClients
See TEST org.xmlBlaster.test.qos.TestSubNoDup
See TEST org.xmlBlaster.test.qos.TestSubNotify
See TEST org.xmlBlaster.test.qos.TestSubNoLocal
See TEST org.xmlBlaster.test.qos.TestSubXPathMany
See TEST org.xmlBlaster.test.qos.TestSubDispatch
See TEST org.xmlBlaster.test.qos.TestSubLostClient
See TEST org.xmlBlaster.test.qos.TestSubMulti
See TEST org.xmlBlaster.test.qos.TestSubMultiSubscribe
See TEST org.xmlBlaster.test.classtest.qos.StatusQosFactoryTest
See TEST org.xmlBlaster.test.cluster.SubscribeTest
See TEST org.xmlBlaster.test.cluster.SubscribeXPathTest

This page is generated from the requirement XML file xmlBlaster/doc/requirements/interface.subscribe.xml

Back to overview