XmlBlaster Logo

REQUIREMENT

dispatch.plugin.priorizedDispatch

XmlBlaster Logo


Type NEW
Priority MEDIUM
Status CLOSED
Topic XmlBlaster provides a plugin to control message delivery to remote destinations
Des
cription

XmlBlaster has a plugin interface to control the dispatcher framework. This requirement describes one plugin realization which is free configurable to control message delivery to remote destinations.

Probably you should first read the delivery.control.plugin requirement (see link below) to get the big picture and then proceed with the description of this specific plugin implementation.

What can this plugin do for you?

The plugin supports a set of actions. You configure the wanted behaviour and switch the actions by sending specific status messages to the plugin. The supported actions are:

  1. send Messages are send as without a plugin by passing them to the dispatcher framework
  2. queue Messages are retained in a local 'hold back queue'
  3. destroy Messages are destroyed
  4. notifySender The publisher is notified about the current action, this action is only possible in combination with one of the first three actions

Now lets have a look at how the plugin works:


Overview of the priorized dispatch plugin

Messages are coming from the left hand side into the xmlBlaster core. If a client has subscribed to messages they will be forwarded to the callback queue (see green arrows in drawing). Naturally the dispatcher framework would take the messages out of the callback queue and deliver them directly to the client with whichever protocol the client wished (like CORBA or XmlRpc).

As the client has requested to use the plugin in his connectQos, all messages from the callback queue are intercepted by the plugin and inspected. Depending on the configuration of the plugin the messages are handled as requested. The possible actions are send, queue and destroy each of them can have the additional action notifySender.

Messages which are queued are put in a plugin owned hold back queue (see red arrow). If the plugin state later changes to send them they are flushed back to the update queue to be delivered. You may wonder why they are not directly put into the dispatcher - this is because of the dispatcher framework does not know anything about our plugin implementation details, that the plugin has implemented an own queue. The dispatcher only knows how to deal with its update queue.

There are two events which change the plugin state, and further a new plugin configuration command reconfigures the complete plugin on the fly.

  1. Connection state events from the dispatcher
    The dispatcher notifies the plugin about the current state of the connection. This is a normal Java method invocation telling the plugin if the remote connection is ALIVE, POLLING or DEAD. Such events have precedence over the 'status messages' because they reflect the real situation whereas the 'status messages' giving additional hints about the connection.
  2. Status messages from a remote source
    Any normal xmlBlaster client can send status messages describing the current connection which results in the configured actions. The source of such a message could by a manual operation of an administrator or automically generated by a router or a PLC device.
  3. New plugin configuration
    An administrator can send the plugin a new configuration in hot operation. This reconfigures the plugin on the fly. The configuration is sent by a command message setting a system property.

How to configure the plugin?

The priority of each message is the input parameter of the decision. The priority of a message is set by a publisher when sending the message away. Depending on the priority and the current state of the dispatcher connection and of the state messages an action is chosen. The action determines what happens to the message - if it is queued, destroyed or forwarded.

The following drawing shows a typical configuration:


Configuration of the priorized dispatch plugin

How does my status message look like?

In the above configuration you have specified the message oid to _bandwidth.status and the content to e.g. 64k. The plugin parses your above configuration and automatically subscribes to all given message oids.
So you need to send a message with that oid and content to xmlBlaster. The plugin receives the message and switches its state.

If your client is a router, you can for example write a little perl script which queries the router state and publishes this as a status message to xmlBlaster.


How does the notify message look like?

If you have configured an action='...,notifySender', all publishers of message which match this action receive a PtP notification message.

This notification message has the same message oid as the published message but an empty content. You can query the reason for this PtP message in the state of the update() QoS: 

<qos>
   <state id='queue' 
         info='Notification about special message treatment
               in plugin DispatchPlugin[Priority][1],
               dispatcher state=64k'/>
   <sender>_PriorizedDispatchPlugin</sender>
   <priority>6</priority>
</qos>

Can i use many plugins simultanous?

You can load this plugin multiple times in one xmlBlaster server instance, where every instance has another configuration. The clients connecting xmlBlaster can choose which variant they want to use.

Note that one client can not use more than one plugin at the same time.


How does a client choose a plugin for its connection?

A client can use the configuration parameter DispatchPlugin.defaultPlugin on command line or in its xmlBlaster.properties file. Please see configuration section below.

In normal cases, the user will configure the plugin during login with the ConnectQos the connect() QoS XML string (requirement interface.connect): 

   <connect>
     <qos>
       ...
       <queue relating='callback'>
          <callback ... dispatchPlugin='Priority,1.0'>
         ...
         </callback>
       </queue>
     </qos>
  </connect>

or as a Java code fragment: 

  this.connectQos = new ConnectQos(glob, name, passwd);

  CallbackAddress cbAddress = new CallbackAddress(glob);
  cbAddress.setDelay(1000L);      // retry connecting every 4 sec
  cbAddress.setRetries(-1);       // -1 == forever
  cbAddress.setPingInterval(5000L); // ping every 4 seconds
  cbAddress.setDispatchPlugin("Priority,1.0");  // Activate plugin for callback only
  this.connectQos.addCallbackAddress(cbAddress);
Example
Java

For coding examples please look into the testsuite, links are provided below.

Configure

These parameters allow to configure the dispatch plugin.

Property Default Description Implemented
DispatchPlugin[Priority][1] org.xmlBlaster.util.dispatch.\
plugins.prio.PriorizedDispatchPlugin		 Loads the plugin on the server side yes
DispatchPlugin[Priority][2] org.xmlBlaster.util.dispatch.\
plugins.prio.PriorizedDispatchPlugin		 Loads the same plugin on the server side under a different name. You can configure this plugin differently. Do this as often you as like. yes
DispatchPlugin/defaultPlugin Priority,1 Activates the plugin 1 as default for all connections if not the client overwrites this default.
You can do this on client side to configure your client to use a plugin. On the server side loading the plugin as default is usually not wanted.
Setting it to 'undef' deactivates a default plugin for all connections which is the default 		yes
dispatch/callback/DispatchPlugin/defaultPlugin Priority,1 Activates the plugin 1 as default for all callback connections if not the client overwrites this default.
You can do this on client side to configure your xmlBlaster callback connection to be called back using this plugin. On the server side loading the plugin as default is usually not wanted.
Setting it to 'undef' deactivates a default plugin for all callback connections which is the default. 		yes
PriorizedDispatchPlugin/config 
<msgDispatch ...
...
 The XML default configuration string for the plugin yes
PriorizedDispatchPlugin/config[Priority,2] 
<msgDispatch ...
...
 A specific XML configuration string for the plugin 'Priority,2' yes

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 API org.xmlBlaster.util.dispatch.plugins.prio.PriorizedDispatchPlugin
See API org.xmlBlaster.util.dispatch.plugins.prio.ConfigurationParser
See API org.xmlBlaster.util.dispatch.DispatchManager
See API org.xmlBlaster.util.plugin.I_Plugin
See REQ dispatch.control.plugin
See TEST org.xmlBlaster.test.dispatch.ConfigurationParserTest
See TEST org.xmlBlaster.test.dispatch.TestPriorizedDispatchPlugin
See TEST org.xmlBlaster.test.dispatch.TestPriorizedDispatchWithLostCallback

This page is generated from the requirement XML file xmlBlaster/doc/requirements/dispatch.plugin.priorizedDispatch.xml

Back to overview