Type	NEW
Priority	LOW
Status	CLOSED

Topic	XmlBlaster has a plugin interface which allows to control the distribution of published messages to subscribers
Des cription	It is possible to let a plugin handle the distribution of published messages. The normal behavior is that all client-sessions subscribing to a certain topic are getting all updates of that topic. This covers a wide range of use cases but sometimes it is just too limiting. Suppose you want to guarantee that a published message is consumed once and only once. That could be acheeved by sending a PtP message to a client (by specifying his session to avoid double dispatching) and setting the message as volatile. This is great but it implies that the publisher knows the address of the client. What shall we do if the destination has to be anonymous, i.e. if everybody is allowed to consume that message without the producer knowing about it, as it is for example the case of queues in JMS ? Suppose a load balancer is required where messages of the same topic have to be distributed intelligently among clients (for example by giving the current message to the client currently having the lowest cpu consumption) The mentioned cases are just a few of a whole spectra of potential -an many times specific- wishes users can have. A good approach to this problem is to avoid to hard-code such specific cases and provide a plugin instead. The plugin controls the distribution of a published message to the subscribing clients, in other words it contains the logics which decide who/how a certain subscriber is getting a certain message or message update. There is a maximum of one plugin instance per TopicHandler instance. The Topic is the owner of the plugin. This implies that you define distribution control on a pro-topic base. Practically this is defined in the PublishQos. How to write my own plugin As a plugin coder, you have to implement two interfaces I_Plugin: Which allows xmlBlaster to load the plugin I_MsgDistributor: Which forces you to implement some methods allowing you to control the message flow, i.e. which addresses have to get the message and if/when/how the message should be removed from the history queue. This is simple and straightforward (see requirement msgDistributor.plugin.ConsumableQueuePlugin). Note that this is only an example of what you can do. The status message and priority configuration of the above example is specific for exactly this plugin. If you implement your own plugin, you can do whatever you like. For the mentioned example of only once delivery an implementation exists which you can use/change and modify according to your needs. It is the ConsumableQueuePlugin (see link below).
Configure	The first step to do when configuring this plugin is to register it by assigning a name to it. This is normally put into the xmlBlaster.properties file which is read by the server. The name has the structure PluginType[instanceName][instanceVersion] as stated in the first row in the table below. Besides the class name of the implementation to use you could also pass properties which are specific to the given implementation. The second step is to define a default plugin to be used when the client does not specify anything explicitly. This is done as in the third row of the table below. Property Default / Example Description Implemented MsgDistributorPlugin[MyPlugin][1] com.xy.MyPlugin Register your plugin MsgDistributorPlugin[Another][1.0] com.xy.MySpecial Register your plugin MsgDistributorPlugin/defaultPlugin "MyPlugin,1" or "Another,1.0" or "undef" Specifiy the plugin to use as a default. Default is undef that is no default plugin is loaded which is usually the correct setting: The client normally chooses on publish its desired plugin by specifying it in the topic section of the publish QoS When publishing a topic for the first time (or when doing an administrative publish), you can specify which plugin to use for the distribution of the message. In java you would do it like this: ... PublishQos pubQos = new PublishQos(global); TopicProperty topicProp = new TopicProperty(global); topicProp.setMsgDistributor("ConsumableQueue,1.0"); pubQos.setTopicProperty(topicProp); MsgUnit msgUnit = new MsgUnit(new PublishKey(global, someOid), someContent, pubQos); global.getXmlBlasterAccess().publish(msgUnit); ... 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.engine.distributor.I_MsgDistributor
See API	org.xmlBlaster.engine.distributor.plugins.ConsumableQueuePlugin
See API	org.xmlBlaster.util.plugin.I_Plugin
See REQ	msgDistributor.plugin.ConsumableQueue
See REQ	util.property.env
See TEST	org.xmlBlaster.test.distributor.TestConsumableQueue

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

Back to overview