XmlBlaster Logo

REQUIREMENT

interface.publish

XmlBlaster Logo


Type NEW
Priority HIGH
Status CLOSED
Topic All messages sent to xmlBlaster use the publish method
Des
cription

The publish() method allows to send messages to xmlBlaster or in point to point (PtP) mode route messages to other clients.

Method detail (CORBA IDL notation): 

   string publish(in MessageUnit msgUnit) raises(XmlBlasterException);
ParameterTypeDescription
msgMessageUnitA structure containing an XML key, an XML QoS and the binary message content (see MsgUnit link below)
returnstringAn XML based return string containing status and other informations (see PublishReturnQos link below)
XmlBlasterExceptionexceptionThrown on error

Method variants:

  • publishArr() Publishes many messages in a bulk
  • publishOneway() Publishes many messages in a bulk without a return value (without synchronous ACK)

PublishKey example (publish/subscribe mode)

<key oid='4711' contentMime='text/xml' contentMimeExtended='-'>
   <AGENT id='192.168.124.20' subId='1' type='generic'>
     <DRIVER id='FileProof' pollingFreq='10'>
     </DRIVER>
   </AGENT>
</key>

PublishQos example (publish/subscribe mode)

<qos>
   <!-- 5 is NORM priority, 0 is slowest, 9 is highest -->
   <priority>5</priority>

   <!-- The message is automatically destroyed after 60000 milliseconds -->
   <expiration lifeTime='60000' forceDestroy='false'/>

   <!-- The message is saved to harddisk to be recoverable after a crash -->
   <persistent/>

   <!-- Don't update messages with identical content as the predecessor -->
   <forceUpdate>false</forceUpdate>

   <clientProperty name='transactionId'>0x23345</clientProperty>
   <clientProperty name='myName'>jack</clientProperty>
   <clientProperty name='myAge' type='int'>12</clientProperty>

   <!-- Administration: configure the topic on first publish (optional) -->
   <topic readonly='false' destroyDelay='30000' createDomEntry='true'>
      <persistence relating='msgUnitStore' maxEntries='1000' maxBytes='4000'/>
      <queue relating='history' type='CACHE' version='1.0'
                maxEntries='1000' maxBytes='4000'/>
   </topic>
</qos>

<priority>5</priority>

The message priority can be chosen between 0 and 9 whereas 5 is the default, see requirement engine.qos.publish.priority.

<expiration lifeTime='60000'/> or <expiration lifeTime='60000' forceDestroy='true'/>

Control the life time of a message, given in milli seconds.

This value is calculated relative to the rcvTimestamp in the xmlBlaster server.

Passing -1 milliseconds asks the server for unlimited lifespan, which the server may or may not grant (but currently does grant with the default configuration). This is the default setting.

Setting to 0 will behave as a volatile message (see setVolatile()) and the message will be invisible directly after being pushed into the subscribers callback queues, in the callback queues it will stay until retrieved by the subscriber.

Setting it to a value > 0 will expire the message after the given milliseconds.
With forceDestroy=false, which is the default setting, messages which are already put to clients callback queue will be delivered even after they are expired. But they are not anymore visible to clients subscribing after expiration.
Setting forceDestroy=true forces all messages to be discarded on expiry, including those already served to callback queues.

See requirement engine.qos.publish.isVolatile.

<persistent/>

Messages are sent transient as default. Here we have chosen that the message survives a server crash or shutdown as it is marked to be persistent, see requirement engine.qos.publish.persistent.

<forceUpdate>false</forceUpdate>

This flag allows to set the behavior for follow up messages with the same content, see requirement engine.qos.publish.forceUpdate.

<clientProperty>

You can choose to send any number of problem domain specific client properties which each message. The receiver can access those in the UpdateQos, see requirement engine.qos.clientProperty.

<topic ...>

Here we send the configuration for the topic. This is only evaluated if the topic didn't exist yet and needs to be created automatically when this publish arrives. We can omit these topic settings as there are chosen useful default values in this case.
See requirement engine.message.lifecycle.

PublishQos PtP example (point to point mode)

<qos>
   <!-- 5 is NORM priority, 0 is slowest, 9 (or MAX) is highest -->
   <priority>MAX</priority>

   <!-- false to make PtP message invisible for subscribes -->
   <subscribable>false</subscribable>

   <expiration lifeTime='129595811'/>

   <persistent/>  <!-- message is recovered on server crash -->

   <forceUpdate>false</forceUpdate>
                 <!-- messages with identical content as the predecessor
                         are not updated -->

   <!-- Send to all login sessions of user 'Tim',
           if Tim is offline queue it -->
   <destination queryType='EXACT' forceQueuing='true'>
      Tim
   </destination>

   <!-- The login session '-2' of 'Ben' logged in
           at cluster node 'heron' -->
   <destination>
      /node/heron/client/Ben/session/-2
   </destination>

   <destination queryType='XPATH'>   <!-- Not supported yet -->
      //[GROUP='Manager']
   </destination>

   <!-- Administration: configure the topic on first publish
          (optional) -->
   <topic readonly='false' destroyDelay='60000' createDomEntry='false'>
      <persistence relating='msgUnitStore' type='CACHE' version='1.0'
                maxEntries='1000' maxBytes='4000' onOverflow='deadMessage'/>
      <queue relating='history' type='CACHE' version='1.0'
                maxEntries='1000' maxBytes='4000' onOverflow='exception'/>
   </topic>
</qos>

<destination forceQueuing='true'>Tim</destination>

If we want to send a message to specific other clients we address the clients by their login names or session names. If a destination contains the session identifier (like 'client/Tim/session/-2') only this specific login session of the client will receive the message. If we don't specify a publicSessionId, all current login sessions of the user will receive the message.

If a destination client is off-line the publisher gets thrown back an exception and the message is not delivered. By adding the tag forceQueuing the message will be queued in xmlBlaster until the destination client logs in and will then be delivered to the destination.

<subscribable>false</subscribable>

If we want to hide the PtP message from other subscribers of this topic we add the subscribable tag and set it to false.

Example
XML

MsgUnit example

FieldExample
Key<key oid='MyMessageOid' contentMime='text/plain'/>
ContentHello world
QoS<qos><priority>5</priority></qos>

The MsgUnit consists of three attributes:

The key is XML markup describing the topic name, here MyMessageOid and other useful meta information about this topic.

The content is binary data which you want to transport with this message.

The QoS is the quality of service it describes in XML markup how the message shall be handled by the xmlBlaster server.

And a return value: 

<qos>
   <state id='OK' info='QUEUED[bilbo]'/>
   <key oid='MyMessageOid'/>
   <rcvTimestamp nanos='1042815836675000001'/>
</qos>

Above you got an acknowledge for your sent message, the state is OK.

The topic name MyMessageOid is returned, this is helpful if you have not set an oid on publish and the oid is generated uniquely by xmlBlaster.

Finally you get the approximate receive timestamp (UTC time), when the message arrived in the xmlBlaster server publish() method.

It is given in nanoseconds elapsed since midnight, January 1, 1970 UTC. Note that the exact time is milliseconds only but an internal counter is added to have nanosecond precision, guaranteeing a unique timestamp for an xmlBlaster cluster node instance.

This rcvTimestamp is unique for a message instance published and may be used to identify this message. For example a publisher and a receiver of a message can identify this message by its topic (key oid) and its receive timestamp. Have a look at requirement interface.update where this timestamp is delivered as well.

To get a human readable view on the timestamp try: 

String time = qos.getRcvTimestamp().toString(); // Java

string time = TimestampFactory::getTimeAsString(Timestamp timestamp); // C++

->    2003-01-17 16:03:56.675000001
Example
XML

Administrative messages

Such a message configures the topic only and does not contain any user content, it is not updated to subscribers and is not put to the history queue.
Usually this is the first published message for a specific key oid (=topic). 

<qos>
   <!-- 9 is highest -->
   <priority>9</priority>

   <!-- Don't do any PtP or Pub/Sub actions, just configure the topic -->
   <administrative/>

   <!-- Configure the topic on first publish -->
   <topic readonly='false' destroyDelay='-1' createDomEntry='true'>
      <persistence relating='msgUnitStore' type='CACHE' version='1.0'
                 maxEntries='1000' maxBytes='4000' onOverflow='deadMessage'/>
      <queue relating='history' type='CACHE' version='1.0'
                 maxEntries='1000' maxBytes='4000' onOverflow='exception'/>
   </topic>
</qos>

<administrative/>

This tags marks the message to be for configuration only.

<topic>...</topic>

The topic settings are described in detail in the requirement engine.message.lifecycle.

<persistence>...</persistence>

These settings configure the message store which contains the real 'meat' of the message (the queue only hold references on this storage), see engine.persistence.

<queue>...</queue>

The supported settings and default values are described in the queue requirements.

Note that we have set the destroyDelay to unlimited (=-1), else the new created topic will die if no activity happens during this time. Such a topic can only be deleted by an explicit call with erase().
Example
XmlRpc

The XmlRpc server interface

   public String publish (String sessionId, Vector msgUnitWrap)
                                             throws XmlBlasterException
Example
Java

A typical Java client code in publish/subscribe mode

   import org.xmlBlaster.client.key.PublishKey;
   import org.xmlBlaster.client.qos.PublishQos;
   import org.xmlBlaster.util.MsgUnit;

   ...

   PublishKey pk = new PublishKey(glob, "HelloWorld4", "text/plain", "1.0");

   PublishQos pq = new PublishQos(glob);

   MsgUnit msgUnit = new MsgUnit(pk, "Hi", pq);

   PublishReturnQos retQos = con.publish(msgUnit);

A typical Java client code in PtP mode: 

   import org.xmlBlaster.client.key.PublishKey;
   import org.xmlBlaster.client.qos.PublishQos;
   import org.xmlBlaster.util.SessionName;
   import org.xmlBlaster.util.qos.address.Destination;

   ...

   PublishKey pk = new PublishKey(glob, "HelloWorld5", "text/plain", "1.0");

   PublishQos pq = new PublishQos(glob);
   pq.addDestination(new Destination(new SessionName(glob, "Tim/-5")));

   MsgUnit msgUnit = new MsgUnit(pk, "Hi".getBytes(), pq);

   PublishReturnQos retQos = con.publish(msgUnit);

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

Example
Perl

A typical Perl client code in publish/subscribe mode: 

use Frontier::Client;

#$server_url = 'http://MyHost:8080/';
$server_url =  @ARGV[0];
print "\nTrying to connect to xmlBlaster server on $server_url ...\n";

# Make an object to represent the XMLRPC server.
$server = Frontier::Client->new(url => $server_url);

$connectQos = "<qos>".
              "  <securityService type='htpasswd' version='1.0'>".
              "    <user>testpubUser</user>".
              "    <passwd>secret</passwd>".
              "  </securityService>".
              "  <ptp>true</ptp>".
              "  <session timeout='86400000' maxSessions='10'/>".
              "</qos>";

# Call the remote server and get our result (we need to port to connect(),
# see XmlBlaster.pm).
$sessionId = $server->call('authenticate.login', "testpubUser",
                           "secret", $connectQos, "");
print "\nLogin success on $server_url, got secret sessionId=$sessionId \n";

# Publish a volatile message
my $publishKey="<key oid='' contentMime='text/xml'>".
               "  <service>post</service>".
               "  <type>request</type>".
               "  <id>123</id>".
               "</key>",
my $cdata="<event>testing</event>";
my $publishQos="<qos>".
               "  <expiration lifeTime='0'/>".
               "  <persistent>false</persistent>".
               "  <topic destroyDelay='0' createDomEntry='true'/>".
               "</qos>";

$message = $server->call('xmlBlaster.publish', $sessionId,
        $publishKey,
        $cdata,
        $publishQos);

print "publish return is : $message\n";

# Logout from xmlBlaster
$server->call('authenticate.disconnect', $sessionId, "<qos/>");
print "\nLogout done, bye.\n";

See xmlBlaster/demo/perl/xmlrpc/*.pl for more examples.

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 ../../demo/javaclients/HelloWorldPublish.java.html
See API org.xmlBlaster.util.def.PriorityEnum
See API org.xmlBlaster.util.MsgUnit
See API org.xmlBlaster.client.qos.PublishQos
See API org.xmlBlaster.client.qos.PublishReturnQos
See API org.xmlBlaster.client.I_XmlBlasterAccess
See API org.xmlBlaster.protocol.xmlrpc.XmlBlasterImpl
See REQ interface
See REQ engine.message.lifecycle
See REQ engine.qos.clientProperty
See REQ engine.qos.publish.PubSub
See REQ engine.qos.publish.persistent
See REQ engine.qos.publish.forceUpdate
See REQ engine.qos.publish.isVolatile
See REQ engine.qos.publish.readonly
See REQ engine.qos.publish.destination.PtP
See REQ engine.qos.publish.destination.ForceQueuing
See REQ engine.qos.publish.destination.PtX
See REQ engine.qos.publish.destination.offline
See REQ cluster.PtP
See TEST org.xmlBlaster.test.qos.TestPub
See TEST org.xmlBlaster.test.qos.TestPtD
See TEST org.xmlBlaster.test.qos.TestPtPSubscribeable
See TEST org.xmlBlaster.test.cluster.PublishTest
See TEST org.xmlBlaster.test.classtest.qos.MsgQosFactoryTest
See TEST org.xmlBlaster.test.classtest.qos.StatusQosFactoryTest

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

Back to overview