org.xmlBlaster.util.dispatch.plugins
Interface I_MsgDispatchInterceptor

All Superinterfaces:

I_ConnectionStatusListener

All Known Implementing Classes:

PriorizedDispatchPlugin

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(DispatchManager dispatchManager) This is called once for each dispatch manager using this plugin.
boolean	doActivate(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.ArrayList	handleNextMessages(DispatchManager dispatchManager, java.util.ArrayList 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(DispatchManager dispatchManager, java.lang.Throwable ex) Invoked when the dispatching failed due to an exception.
void	postHandleNextMessages(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(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, toDead, toPolling

Method Detail

initialize

public void initialize(Global glob,
                       java.lang.String typeVersion)
                throws XmlBlasterException

Is called once only after the instance is created.

Throws:

XmlBlasterException

addDispatchManager

public void addDispatchManager(DispatchManager dispatchManager)

This is called once for each dispatch manager using this plugin.

doActivate

public boolean doActivate(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

public java.util.ArrayList handleNextMessages(DispatchManager dispatchManager,
                                              java.util.ArrayList 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

public void postHandleNextMessages(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

public void shutdown(DispatchManager dispatchManager)
              throws XmlBlasterException

Deregister the given dispatchManager

Throws:

XmlBlasterException

shutdown

public void shutdown()
              throws XmlBlasterException

Shutdown the implementation, sync with data store

Throws:

XmlBlasterException

isShutdown

public boolean isShutdown()

Returns:

true if shutdown

usage

public java.lang.String usage()

Returns:

a human readable usage help string

toXml

public java.lang.String toXml(java.lang.String extraOffset)

Parameters:

extraOffset - Indent the dump with given ASCII blanks

Returns:

An xml encoded dump

onDispatchWorkerException

public void onDispatchWorkerException(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 -