xmlBlaster 2.1.0 API

org.xmlBlaster.util.dispatch.plugins
Interface I_MsgDispatchInterceptor

All Superinterfaces:
I_ConnectionStatusListener
All Known Implementing Classes:
PriorizedDispatchPlugin, ReplManagerPlugin

public interface I_MsgDispatchInterceptor
extends I_ConnectionStatusListener

The Interface allows to control how messages are sent to the remote side.

Plugins of this interface have only one instance per plugin-typeVersion for each Global scope so you can look at it like a singleton.

Author:
xmlBlaster@marcelruff.info

Method Summary
 void addDispatchManager(I_DispatchManager dispatchManager)
          This is called once for each dispatch manager using this plugin.
 boolean doActivate(I_DispatchManager dispatchManager)
          If there are new messages available in the queue, you get invoked here and are asked if you want to start a worker thread (from the thread pool) to start taking messages from the queue and send them over the remote connection.
 java.util.List<I_Entry> handleNextMessages(I_DispatchManager dispatchManager, java.util.List<I_Entry> pushEntries)
          If you returned true from doActivate() the worker thread will ask us to retrieve the next messages from the queue (dispatchManager.getQueue()).
 void initialize(Global glob, java.lang.String typeVersion)
          Is called once only after the instance is created.
 boolean isShutdown()
           
 void onDispatchWorkerException(I_DispatchManager dispatchManager, java.lang.Throwable ex)
          Invoked when the dispatching failed due to an exception.
 void postHandleNextMessages(I_DispatchManager dispatchManager, MsgUnit[] processedEntries)
          Method invoked after having successfully sent the entries in asynchronous modus.
 void shutdown()
          Shutdown the implementation, sync with data store
 void shutdown(I_DispatchManager dispatchManager)
          Deregister the given dispatchManager
 java.lang.String toXml(java.lang.String extraOffset)
           
 java.lang.String usage()
           
 
Methods inherited from interface org.xmlBlaster.util.dispatch.I_ConnectionStatusListener
toAlive, toAliveSync, toDead, toPolling
 

Method Detail

initialize

void initialize(Global glob,
                java.lang.String typeVersion)
                throws XmlBlasterException
Is called once only after the instance is created.

Parameters:
The - configuration name under which we are loaded e.g. "Priority,1.0"
Throws:
XmlBlasterException

addDispatchManager

void addDispatchManager(I_DispatchManager dispatchManager)
This is called once for each dispatch manager using this plugin.


doActivate

boolean doActivate(I_DispatchManager dispatchManager)
If there are new messages available in the queue, you get invoked here and are asked if you want to start a worker thread (from the thread pool) to start taking messages from the queue and send them over the remote connection.

Note: If the session cb is in polling and the callback queue contains entries and you return true, the dispatchWorker thread will loop! In such a case check with

 if (dispatchManager.getDispatchConnectionsHandler().isPolling()) {
     return false;
  }
 

Returns:
true: create a worker thread to process messages from queue (it will call our getNextMessages() method where we can decide which messages it will process
false: abort, don't start worker thread

handleNextMessages

java.util.List<I_Entry> handleNextMessages(I_DispatchManager dispatchManager,
                                           java.util.List<I_Entry> pushEntries)
                                           throws XmlBlasterException
If you returned true from doActivate() the worker thread will ask us to retrieve the next messages from the queue (dispatchManager.getQueue()).

This is where this plugin comes in action. The plugin may filter the queue entries and for example only return high priority messages

Usually you take the message out of the queue and then invoke prepareMsgsFromQueue() to filter expired messages away and do a shallow copy of the messages to avoid that changes in the messages have impact on the original messages. See the following example:

  // take messages from queue (none blocking)
  // we take all messages with same priority as a bulk ...
  ArrayList entryList = dispatchManager.getQueue().peekSamePriority(-1);

  // filter expired entries etc. ...
  // you should always call this method after taking messages from queue
  entryList = dispatchManager.prepareMsgsFromQueue(entryList);

  // ... do plugin specific work ...

  return entryList;
 

Parameters:
pushEntries - null: Take messages yourself from queue (async mode)
not null: Use messages pushed (sync mode) or messages from ErrorCode.COMMUNICATION*
Returns:
An ArrayList containing the I_QueueEntry to send.
If list.size() == 0 the worker thread stops and does nothing
If list.size() > 0 the given messages are sent. In case of pushEntries>0 and ErrorCode.COMMUNICATION* if you return them they are send to error handler.
Throws:
If - XmlBlasterException is thrown, dispatch of messages is stopped. Other exceptions will lead to giving up sending messages as configured with I_MsgErrorHandler, usually shutdown queue and sending dead messages.
XmlBlasterException

postHandleNextMessages

void postHandleNextMessages(I_DispatchManager dispatchManager,
                            MsgUnit[] processedEntries)
                            throws XmlBlasterException
Method invoked after having successfully sent the entries in asynchronous modus.

Parameters:
dispatchManager - The used dispatch manager.
processedEntries - The entries which have been previously processed.
Throws:
XmlBlasterException

shutdown

void shutdown(I_DispatchManager dispatchManager)
              throws XmlBlasterException
Deregister the given dispatchManager

Throws:
XmlBlasterException

shutdown

void shutdown()
              throws XmlBlasterException
Shutdown the implementation, sync with data store

Parameters:
true: - force shutdown, don't flush everything
Throws:
XmlBlasterException

isShutdown

boolean isShutdown()
Returns:
true if shutdown

usage

java.lang.String usage()
Returns:
a human readable usage help string

toXml

java.lang.String toXml(java.lang.String extraOffset)
Parameters:
extraOffset - Indent the dump with given ASCII blanks
Returns:
An xml encoded dump

onDispatchWorkerException

void onDispatchWorkerException(I_DispatchManager dispatchManager,
                               java.lang.Throwable ex)
Invoked when the dispatching failed due to an exception. This way the implementation of the plugin gets a notification that an exception occurred.

Parameters:
dispatchManager -
ex -

xmlBlaster 2.1.0 API

Copyright © 1999-2011 The xmlBlaster.org contributers.