XmlBlaster Logo

REQUIREMENT

interface.get

XmlBlaster Logo


Type NEW
Priority HIGH
Status CLOSED
Topic Synchronous message access with the get() method
Des
cription

The get() method allows to retrieve messages from xmlBlaster. You can access exactly one message by passing its oid, or a selection of messages by passing an XPATH query.

Method detail (CORBA IDL notation): 

   typedef string XmlType;
   typedef sequence<MessageUnit> MessageUnitArr;

   MessageUnitArr get(in XmlType xmlKey, in XmlType xmlQos)
                                          raises(XmlBlasterException);
ParameterTypeDescription
xmlKeystringThe XML encoded key containing the oid or XPATH query to select messages to get
xmlQosstringThe XML encoded Quality of Service QoS (see GetQos link below)
returnMessageUnit[]An array of messages
XmlBlasterExceptionexceptionThrown on error

Here is an overview of all available get QoS: 

<qos>
   <!-- Don't return the content data of the message (notify only) -->
   <content>false</content>

   <!-- Filters messages as implemented in the specified plugin -->
   <!-- Here we use the regex filter and only want contents starting with the letter 'H' -->
   <filter type='GnuRegexFilter' version='1.0'>
      ^H.*$
   </filter>

   <!-- 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'/>

   <!-- optional, see requirement engine.qos.queryspec.QueueQuery -->
   <querySpec type='QueueQuery'><![CDATA[
      maxEntries=3&maxSize=-1&consumable=false&waitingDelay=0]]>
   </querySpec>

</qos>

A special note how to use get() in cluster environments:

If you invoke get() on a cluster slave node, the request is only forwarded to a master node if the key matches the configured master selection.

Example
XML

Here is an example of an exact query:

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

And a return value:

Key<key oid='MyMessage' />
contentHello world
QoS<qos><state id='OK'></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/>
Example
XML

get() in a cluster environment belonging to domain RUGBY_NEWS

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

This is the XmlRpc server interface variant: 

   public Vector get(String sessionId, String xmlKey_literal, String qos_literal)
                     throws XmlBlasterException
Example
RMI

This is the RMI server interface variant: 

   public MsgUnit[] get(String sessionId, String xmlKey_literal, String qos_literal)
                            throws RemoteException, XmlBlasterException
Example
Java

A typical Java client code for an EXACT subscription: 

   import org.xmlBlaster.client.key.GetKey;
   import org.xmlBlaster.client.qos.GetQos;
   import org.xmlBlaster.util.MsgUnit;
   ...

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

   GetQos sq = new GetQos(glob);

   MsgUnit[] msgs = con.get(sk.toXml(), sq.toXml());

   System.out.println("Success, retrieved " + msgs.length + " messages.");

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

Example
Java

A typical Java client code for an XPATH subscription: 

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

   GetQos sq = new GetQos(glob);

   MsgUnit[] msgs = con.get(sk.toXml(), sq.toXml());

The same in raw XML notation: 

   MsgUnit[] msgs = con.get("<key oid=\"/xmlBlaster/key[@oid='radar.track']\" />", "<qos/>");
Example
Java

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

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

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

   MsgUnit[] msgs = con.get(sk.toXml(), null);
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 ../../demo/javaclients/HelloWorldGet.java.html
See API org.xmlBlaster.client.qos.GetQos
See API org.xmlBlaster.client.I_XmlBlasterAccess
See API org.xmlBlaster.util.MsgUnit
See API org.xmlBlaster.protocol.xmlrpc.XmlBlasterImpl
See API org.xmlBlaster.protocol.rmi.XmlBlasterImpl
See REQ Query history/callback/subject queue (sync)

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

Back to overview