org.sandev.basics.util
Interface CommBridge

public interface CommBridge

A bridge between communications used internally by the application, and communications used outside the application. Essentially this is a messaging adaptor callback interface implemented by a node to support moving from the internal messaging mechanism to one outside the application.

As an example, consider an application that communicates via direct messaging within a server, and JMS when going across servers. If this application also wants to support web services, but doesn't want that to pervade their core messaging implementation, then the web service adaptor is going to need an anchor point into the application to do its work. This interface describes that anchor point.

The callback for synchronous communications is through the onReceive method. Asynchronous communications can be done either through a thread interrupt, or polling/buffering. The settings depend on the technology being adapted. For a standard messaging conversion, you would expect a short polling interval and small retention buffer. For something more batch oriented, the interval might be long with a correspondingly large retention buffer. The correct values depend on the bridge.

The CommBridge is responsible for authentication. This is typically handled by decrypting an incoming message using the key for the specified user, to confirm that the message is in fact coming from them. Broadcast messages are encrypted as needed to prevent unauthorized receipt.

Method Summary

AuthUserLookup	getAuthUserLookup() Return an AuthUserLookup instance used for authenticating the source of an incoming request.
AuthWrapper	getBufferedMessages() Return the currently buffered messages.
SandEncryptor	getEncryptor() Return a SandEncryptor instance used for decyphering the request message and returning the result.
Logger	getLogger() Return a logger for output messages.
int	getMaxRetention() Returns the maximum number of asynchronous send messages that can be retained.
long	getMinSendIntervalMillis() The minimum number of milliseconds between each asynchronous message arrival.
int	getPreferredRetention() Returns the preferred number of asynchronous send messages to be retained.
int	getRetention() Returns the number of asynchronous send messages currently being retained.
CharSerializer	getSerializer() Return a CharSerializer instance used for reconstituting the request message or result message.
AuthWrapper	onReceive(AuthWrapper message) Process the given message and return the result.
void	popBufferedMessages(SandMessage[] messages) Remove the specified messages from the front of the message buffer as they have now been processed.
void	setAsynchThread(java.lang.Thread thread) When a message is delivered to the bridge asynchronously, it can signal the bridged comms technology that a new message has arrived by calling the interrupt method of the given thread.
void	setRetention(int numMessages) Sets the maximum number of asynchronous send messages that should be maintained.

Method Detail

getAuthUserLookup

AuthUserLookup getAuthUserLookup()

Return an AuthUserLookup instance used for authenticating the source of an incoming request.

getEncryptor

SandEncryptor getEncryptor()

Return a SandEncryptor instance used for decyphering the request message and returning the result.

getSerializer

CharSerializer getSerializer()

Return a CharSerializer instance used for reconstituting the request message or result message.

onReceive

AuthWrapper onReceive(AuthWrapper message)
                      throws SandException

Process the given message and return the result. This is used to handle synchronous calls from outside the app.

Throws:

SandException

setAsynchThread

void setAsynchThread(java.lang.Thread thread)
                     throws SandException

When a message is delivered to the bridge asynchronously, it can signal the bridged comms technology that a new message has arrived by calling the interrupt method of the given thread. The bridged comms technology will then read the new message from the retention buffer and process it. Not all bridged technologies will provide this capability (they may rely solely on polling). The implementing class must check for null and handle any exceptions that arise from attempting to interrupt the thread.

This is not a mechanism for managing broadcast to a multitude of client processes. However this thread may be for a broadcast manager which takes care of this.

Throws:

SandException

getMinSendIntervalMillis

long getMinSendIntervalMillis()

The minimum number of milliseconds between each asynchronous message arrival. A polling comms implementation may use this information to set its interval (for example it might poll at the same rate or faster). If unknown, the implementing class should return zero.

getBufferedMessages

AuthWrapper getBufferedMessages()

Return the currently buffered messages. This is an array of SandTransmitMessages that has been packaged into an AuthWrapper. To support polling interfaces, the implementing class must set the sandTransmitCounter in each message so that clients can keep track of what they have processed already.

popBufferedMessages

void popBufferedMessages(SandMessage[] messages)

Remove the specified messages from the front of the message buffer as they have now been processed.

getMaxRetention

int getMaxRetention()

Returns the maximum number of asynchronous send messages that can be retained.

getPreferredRetention

int getPreferredRetention()

Returns the preferred number of asynchronous send messages to be retained.

getRetention

int getRetention()

Returns the number of asynchronous send messages currently being retained.

setRetention

void setRetention(int numMessages)

Sets the maximum number of asynchronous send messages that should be maintained.

getLogger

Logger getLogger()

Return a logger for output messages.