org.xmlBlaster.util.dispatch
Interface I_DispatchManager

All Superinterfaces:

java.util.EventListener, I_QueuePutListener, I_Timeout

All Known Implementing Classes:

ClientDispatchManager, ServerDispatchManager

public interface I_DispatchManager
extends I_Timeout, I_QueuePutListener

Manages the sending of messages and commands and does error recovery further we communicate with the dispatcher plugin if one is configured.

There is one instance of this class per queue and remote connection.

Author:

xmlBlaster@marcelruff.info

Method Summary

boolean	addConnectionStatusListener(I_ConnectionStatusListener connectionStatusListener)
boolean	addConnectionStatusListener(I_ConnectionStatusListener connectionStatusListener, boolean fireInitial)
java.util.ArrayList	filterDistributorEntries(java.util.ArrayList entries, java.lang.Throwable ex)
long	getAliveSinceTime() Get timestamp when we went to ALIVE state.
long	getBurstModeMaxBytes() How many bytes maximum shall the callback thread take in one bulk out of the callback queue and deliver in one bulk.
int	getBurstModeMaxEntries() How many messages maximum shall the callback thread take in one bulk out of the callback queue and deliver in one bulk.
I_ConnectionStatusListener[]	getConnectionStatusListeners()
DispatchConnectionsHandler	getDispatchConnectionsHandler()
DispatchStatistic	getDispatchStatistic()
java.lang.String	getId() For logging
I_MsgDispatchInterceptor	getMsgDispatchInterceptor()
I_MsgErrorHandler	getMsgErrorHandler()
I_MsgSecurityInterceptor	getMsgSecurityInterceptor()
int	getNotifyCounter() Counts how often a new entry was added since the current worker thread was started.
long	getPollingSinceTime() Get timestamp when we went to POLLING state.
I_Queue	getQueue()
SessionName	getSessionName()
java.lang.String	getTypeVersion() The name in the configuration file for the plugin
void	handleSyncWorkerException(java.util.List<I_Entry> entryList, java.lang.Throwable throwable) Called by DispatchWorker if an Exception occured in sync mode Only on client side
void	handleWorkerException(java.util.List<I_Entry> entryList, java.lang.Throwable throwable) Called by DispatchWorker if an Exception occurred in async mode.
void	internalError(java.lang.Throwable throwable) Called locally and from TopicHandler when internal error (Throwable) occurred to avoid infinite looping
boolean	isAlive()
boolean	isDead()
boolean	isDispatcherActive()
boolean	isPolling()
boolean	isShutdown()
boolean	isSyncMode()
void	lostClientConnection() Can be called when client connection is lost (NOT the callback connection).
void	notifyAboutNewEntry() When somebody puts a new entry into the queue, we want to be notified about this after the entry is fed.
boolean	pingCallbackServer(boolean sync, boolean connectionIsDown)
void	postSendNotification(MsgQueueEntry entry)
void	postSendNotification(MsgQueueEntry[] entries)
java.util.ArrayList	prepareMsgsFromQueue(java.util.List<I_Entry> entryList) Here we prepare messages which are coming directly from the queue.
void	putPost(I_QueueEntry queueEntry) Called by I_Queue implementation before leaving put() and somebody has registered for such events.
void	putPost(I_QueueEntry[] queueEntries) Called by I_Queue implementation before leaving put() and somebody has registered for such events.
boolean	putPre(I_QueueEntry queueEntry) Called by I_Queue implementation when a put() is invoked and somebody has registered for such events
boolean	putPre(I_QueueEntry[] queueEntries) Called by I_Queue implementation when a put() is invoked and somebody has registered for such events
void	reachedAliveSync(ConnectionStateEnum oldState, I_XmlBlasterAccess connection)
boolean	removeConnectionStatusListener(I_ConnectionStatusListener connectionStatusListener) Remove the given listener
void	removeFromQueue(MsgQueueEntry[] entries, boolean postSendNotify) Messages are successfully sent, remove them now from queue (sort of a commit()): We remove filtered/destroyed messages as well (which doen't show up in entryListChecked)
boolean	sendingFailedNotification(MsgQueueEntry[] entries, XmlBlasterException ex) Notify I_PostSendListener about problem.
void	setAddresses(AddressBase[] addr) Set new callback addresses, typically after a session login/logout
void	setDispatcherActive(boolean dispatcherActive) Inhibits/activates the delivery of asynchronous dispatches of messages.
void	setDispatchWorkerIsActive(boolean val) The worker notifies us that it is finished, if messages are available it is triggered again.
void	shutdown() Stop all callback drivers of this client.
void	shutdownFomAnyState(ConnectionStateEnum oldState, XmlBlasterException ex) Call by DispatchConnectionsHandler on state transition
void	switchToASyncMode() Switch back to asynchronous mode.
void	switchToSyncMode() We register a QueuePutListener and all put() into the queue are intercepted - our put() is called instead.
void	timeout(java.lang.Object userData) We are notified about the burst mode timeout through this method.
void	toAlive(ConnectionStateEnum oldState) Call by DispatchConnectionsHandler on state transition NOTE: toAlive is called initially when a protocol plugin is successfully loaded but we don't know yet if it ever is able to connect
void	toDead(XmlBlasterException ex)
void	toPolling(ConnectionStateEnum oldState) Call by DispatchConnectionsHandler on state transition
java.lang.String	toXml(java.lang.String extraOffset) Dump state of this object into a XML ASCII string.
void	trySyncMode(boolean trySyncMode) Set behavior of dispatch framework.
void	updateProperty(CallbackAddress[] addressArr) Reconfigure dispatcher with given properties.

Method Detail

getSessionName

SessionName getSessionName()

Returns:

Never null

isSyncMode

boolean isSyncMode()

trySyncMode

void trySyncMode(boolean trySyncMode)

Set behavior of dispatch framework.

Parameters:

trySyncMode - true: client side queue embedding, false: server side callback queue defaults to false

updateProperty

void updateProperty(CallbackAddress[] addressArr)
                    throws XmlBlasterException

Reconfigure dispatcher with given properties. Note that only a limited re-configuration is supported

Parameters:

addressArr - The new configuration

Throws:

XmlBlasterException

getQueue

I_Queue getQueue()

addConnectionStatusListener

boolean addConnectionStatusListener(I_ConnectionStatusListener connectionStatusListener)

addConnectionStatusListener

boolean addConnectionStatusListener(I_ConnectionStatusListener connectionStatusListener,
                                    boolean fireInitial)

removeConnectionStatusListener

boolean removeConnectionStatusListener(I_ConnectionStatusListener connectionStatusListener)

Remove the given listener

Parameters:

connectionStatusListener -

Returns:

true if it was removed

getConnectionStatusListeners

I_ConnectionStatusListener[] getConnectionStatusListeners()

getTypeVersion

java.lang.String getTypeVersion()

The name in the configuration file for the plugin

Returns:

e.g. "Priority,1.0"

getMsgSecurityInterceptor

I_MsgSecurityInterceptor getMsgSecurityInterceptor()

Returns:

The import/export encrypt handle or null if created by a SubjectInfo (no session info available)

getDispatchConnectionsHandler

DispatchConnectionsHandler getDispatchConnectionsHandler()

Returns:

The handler of all callback plugins, is never null

getBurstModeMaxEntries

int getBurstModeMaxEntries()

How many messages maximum shall the callback thread take in one bulk out of the callback queue and deliver in one bulk.

getBurstModeMaxBytes

long getBurstModeMaxBytes()

How many bytes maximum shall the callback thread take in one bulk out of the callback queue and deliver in one bulk.

getAliveSinceTime

long getAliveSinceTime()

Get timestamp when we went to ALIVE state.

Returns:

millis timestamp

getPollingSinceTime

long getPollingSinceTime()

Get timestamp when we went to POLLING state.

Returns:

millis timestamp

toAlive

void toAlive(ConnectionStateEnum oldState)

Call by DispatchConnectionsHandler on state transition NOTE: toAlive is called initially when a protocol plugin is successfully loaded but we don't know yet if it ever is able to connect

reachedAliveSync

void reachedAliveSync(ConnectionStateEnum oldState,
                      I_XmlBlasterAccess connection)

toPolling

void toPolling(ConnectionStateEnum oldState)

Call by DispatchConnectionsHandler on state transition

toDead

void toDead(XmlBlasterException ex)

Parameters:

ex -

shutdownFomAnyState

void shutdownFomAnyState(ConnectionStateEnum oldState,
                         XmlBlasterException ex)

Call by DispatchConnectionsHandler on state transition

postSendNotification

void postSendNotification(MsgQueueEntry entry)

postSendNotification

void postSendNotification(MsgQueueEntry[] entries)

sendingFailedNotification

boolean sendingFailedNotification(MsgQueueEntry[] entries,
                                  XmlBlasterException ex)

Notify I_PostSendListener about problem.

Typically XmlBlasterAccess is notified when message came asynchronously from queue

Parameters:

entryList -

ex -

Returns:

true if processed

See Also:

for explanation

handleSyncWorkerException

void handleSyncWorkerException(java.util.List<I_Entry> entryList,
                               java.lang.Throwable throwable)
                               throws XmlBlasterException

Called by DispatchWorker if an Exception occured in sync mode Only on client side

Throws:

XmlBlasterException

removeFromQueue

void removeFromQueue(MsgQueueEntry[] entries,
                     boolean postSendNotify)
                     throws XmlBlasterException

Messages are successfully sent, remove them now from queue (sort of a commit()): We remove filtered/destroyed messages as well (which doen't show up in entryListChecked)

Parameters:

postSendNotify - TODO

Throws:

XmlBlasterException

handleWorkerException

void handleWorkerException(java.util.List<I_Entry> entryList,
                           java.lang.Throwable throwable)
                           throws XmlBlasterException

Called by DispatchWorker if an Exception occurred in async mode.

Throws:

XmlBlasterException - should never happen but is possible during removing entries from queue

getMsgErrorHandler

I_MsgErrorHandler getMsgErrorHandler()

switchToSyncMode

void switchToSyncMode()

We register a QueuePutListener and all put() into the queue are intercepted - our put() is called instead. We then deliver this QueueEntry directly to the remote connection and return synchronously the returned value or the Exception if one is thrown.

switchToASyncMode

void switchToASyncMode()

Switch back to asynchronous mode. Our thread pool will take the messages out of the queue and deliver them in asynchronous mode.

putPre

boolean putPre(I_QueueEntry queueEntry)
               throws XmlBlasterException

Description copied from interface: I_QueuePutListener

Called by I_Queue implementation when a put() is invoked and somebody has registered for such events

Specified by:

putPre in interface I_QueuePutListener

Parameters:

queueEntry - Is guaranteed to never be null

Returns:

true: Continue to put message into queue, false: return without putting entry into queue

Throws:

XmlBlasterException

See Also:

I_QueuePutListener.putPre(I_QueueEntry)

putPre

boolean putPre(I_QueueEntry[] queueEntries)
               throws XmlBlasterException

Description copied from interface: I_QueuePutListener

Called by I_Queue implementation when a put() is invoked and somebody has registered for such events

Specified by:

putPre in interface I_QueuePutListener

Parameters:

queueEntries - Is guaranteed to never be null

Returns:

true: Continue to put message into queue, false: return without putting entry into queue

Throws:

XmlBlasterException

See Also:

putPre(I_QueueEntry), I_QueuePutListener.putPre(I_QueueEntry[])

putPost

void putPost(I_QueueEntry queueEntry)
             throws XmlBlasterException

Description copied from interface: I_QueuePutListener

Called by I_Queue implementation before leaving put() and somebody has registered for such events. The message is already safely entered to the queue.

Specified by:

putPost in interface I_QueuePutListener

Parameters:

queueEntry - Is guaranteed to never be null

Throws:

XmlBlasterException

See Also:

I_QueuePutListener.putPost(I_QueueEntry)

putPost

void putPost(I_QueueEntry[] queueEntries)
             throws XmlBlasterException

Description copied from interface: I_QueuePutListener

Called by I_Queue implementation before leaving put() and somebody has registered for such events. The message is already safely entered to the queue.

Specified by:

putPost in interface I_QueuePutListener

Parameters:

queueEntries - Is guaranteed to never be null

Throws:

XmlBlasterException

See Also:

putPost(I_QueueEntry), I_QueuePutListener.putPost(I_QueueEntry[])

prepareMsgsFromQueue

java.util.ArrayList prepareMsgsFromQueue(java.util.List<I_Entry> entryList)

Here we prepare messages which are coming directly from the queue.

1. We eliminate destroyed messages
2. We make a shallow copy of the message. We need to do this, out messages are references directly into the queue. The delivery framework is later changing the QoS and plugins may change the content - and this should not modify the queue entries

notifyAboutNewEntry

void notifyAboutNewEntry()

When somebody puts a new entry into the queue, we want to be notified about this after the entry is fed.

Called by I_Queue.putPost()

getNotifyCounter

int getNotifyCounter()

Counts how often a new entry was added since the current worker thread was started.

isDead

boolean isDead()

isPolling

boolean isPolling()

isAlive

boolean isAlive()

lostClientConnection

void lostClientConnection()

Can be called when client connection is lost (NOT the callback connection). Currently only detected by the SOCKET protocol plugin. Others can only detect lost clients with their callback protocol pings

timeout

void timeout(java.lang.Object userData)

We are notified about the burst mode timeout through this method.

Specified by:

timeout in interface I_Timeout

Parameters:

userData - You get bounced back your userData which you passed with Timeout.addTimeoutListener()

getMsgDispatchInterceptor

I_MsgDispatchInterceptor getMsgDispatchInterceptor()

Returns:

The interceptor plugin if available, otherwise null

setAddresses

void setAddresses(AddressBase[] addr)
                  throws XmlBlasterException

Set new callback addresses, typically after a session login/logout

Throws:

XmlBlasterException

setDispatchWorkerIsActive

void setDispatchWorkerIsActive(boolean val)

The worker notifies us that it is finished, if messages are available it is triggered again.

internalError

void internalError(java.lang.Throwable throwable)

Called locally and from TopicHandler when internal error (Throwable) occurred to avoid infinite looping

getDispatchStatistic

DispatchStatistic getDispatchStatistic()

Returns:

A container holding some statistical delivery information

isShutdown

boolean isShutdown()

shutdown

void shutdown()

Stop all callback drivers of this client. Possibly invoked twice (givingUpDelivery() calls it indirectly as well) We don't shutdown the corresponding queue.

getId

java.lang.String getId()

For logging

toXml

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

Dump state of this object into a XML ASCII string.

Parameters:

extraOffset - indenting of tags for nice output

Returns:

internal state as a XML ASCII string

setDispatcherActive

void setDispatcherActive(boolean dispatcherActive)

Inhibits/activates the delivery of asynchronous dispatches of messages.

Parameters:

dispatcherActive -

isDispatcherActive

boolean isDispatcherActive()

Returns:

true if the dispacher is currently activated, i.e. if it is able to deliver asynchronousy messages from the callback queue.

filterDistributorEntries

java.util.ArrayList filterDistributorEntries(java.util.ArrayList entries,
                                             java.lang.Throwable ex)

pingCallbackServer

boolean pingCallbackServer(boolean sync,
                           boolean connectionIsDown)