org.sandev.basics.nodecommon
Interface Messager

public interface Messager

The Messager interface defines the methods which must be implemented to provide communication between node instances. An implementation makes use of the fact that every running node instance is Messageable, and local access is provided through the SandRoot. A Messager implementation may be implemented over a variety of technologies including (but not limited to):

• sockets/RMI
• JMS
• web services
• JCA
• other proprietary APIs

Messaging is a critical function and all implementations are assumed be both efficient and trustworthy. If a call terminates normally, then the application may assume that communications are complete. Because messaging is critical, any exception thrown internally by a Messager implementation will likely result in a node shutdown, or a systemwide shutdown.

Sidenote on topic-based messaging implementations:

Most enterprise systems rely on established message servers to provide communications between systems. The Messager interface represents a direct contract between a SAND application and messaging server. In the simplest case, topics are established corresponding to the node instance names. The send method corresponds to publish, and subscribe is what you would expect on the other end. A synchronous call is typically "faked" through publishing on a topic and then waiting until a response is received on a temporary return topic before returning control. Synchronous calls can also be accomplished via RPC, provided that timeout can be achieved.

See also the messaging overview.

Field Summary

static int	MODE_DIRECT Communicate between nodes directly
static int	MODE_INVALID Invalid communications value
static int	MODE_SECURE Communicate between nodes through securing Authorizers
static int	OPTIMIZE_IF_POSSIBLE If it's possible to optimize, do so.
static int	OPTIMIZE_NEVER Do not optimize.
static int	WIRE_BASICSECURITY This messager provides base level security through a secure protocol (like https), but supplemental encryption is supported.
static int	WIRE_SECURECOMMS This messager handles the security of all communications.
static int	WIRE_TRANSPORTONLY The messager provides message transport only.

Method Summary

int	getWireSecurity() Return one of the WIRE_ constants describing the level of transport security provided by this messager for MODE_SECURE communications.
void	init(Messageable node, NodeInstance instance) Initialize the Messager implementation with everything it needs to do its work.
SandMessage	query(SandMessage msg, java.lang.String recipientInstanceName, int optimize, int mode, java.lang.String localAuthorizerInstanceName) Send a synchronous request to the specified recipient and return the result.
void	queryReceiver(Messageable node, java.lang.String messageClass, java.lang.String localAuthorizerInstanceName) Register the node with the local authorizer, as recipient for the specified class of queries.
void	send(SandMessage msg, int optimize, int mode, java.lang.String localAuthorizerInstanceName) Broadcast a message to all subscribers.
void	shutdown() Shut down the Messager and release any cached resources.
void	subscribe(Messageable node, java.lang.String messageClass, java.lang.String senderInstanceName, int optimize, int mode, java.lang.String localAuthorizerInstanceName, SandAttrVal[] matchDescription) Register a node as a subscriber to broadcast messages of the type specified coming from the specified source.
void	unsubscribe(Messageable node, java.lang.String messageClass, java.lang.String senderInstanceName, int optimize, int mode, java.lang.String localAuthorizerInstanceName) Unregister a node as a subscriber to broadcast messages of the type specified coming from the specified source.

Field Detail

OPTIMIZE_IF_POSSIBLE

public static final int OPTIMIZE_IF_POSSIBLE

If it's possible to optimize, do so.

See Also:

Constant Field Values

OPTIMIZE_NEVER

public static final int OPTIMIZE_NEVER

Do not optimize. Send this the standard way regardless.

See Also:

Constant Field Values

MODE_INVALID

public static final int MODE_INVALID

Invalid communications value

See Also:

Constant Field Values

MODE_DIRECT

public static final int MODE_DIRECT

Communicate between nodes directly

See Also:

Constant Field Values

MODE_SECURE

public static final int MODE_SECURE

Communicate between nodes through securing Authorizers

See Also:

Constant Field Values

WIRE_TRANSPORTONLY

public static final int WIRE_TRANSPORTONLY

The messager provides message transport only. No default encryption is supported in communications, so an Authorizer must encrypt the message for communications to be secure.

See Also:

Constant Field Values

WIRE_BASICSECURITY

public static final int WIRE_BASICSECURITY

This messager provides base level security through a secure protocol (like https), but supplemental encryption is supported. An Authorizer should employ additional encryption if available.

See Also:

Constant Field Values

WIRE_SECURECOMMS

public static final int WIRE_SECURECOMMS

This messager handles the security of all communications. The messager implementation automatically secures all transmissions and the Authorizer should NOT encrypt the message because that will add overhead and possibly disable management functionality such as smart routing, debugging, trace flows etc.

See Also:

Constant Field Values

Method Detail

init

public void init(Messageable node,
                 NodeInstance instance)
          throws MessagerException

Initialize the Messager implementation with everything it needs to do its work.

Throws:

MessagerException

shutdown

public void shutdown()

Shut down the Messager and release any cached resources.

send

public void send(SandMessage msg,
                 int optimize,
                 int mode,
                 java.lang.String localAuthorizerInstanceName)
          throws MessagerException

Broadcast a message to all subscribers. If there are no subscribers then this method may simply return. Messager implementations are encouraged to minimize the lag time between a call to send, and receipt of the message by all subscribers.

Throws:

MessagerException

subscribe

public void subscribe(Messageable node,
                      java.lang.String messageClass,
                      java.lang.String senderInstanceName,
                      int optimize,
                      int mode,
                      java.lang.String localAuthorizerInstanceName,
                      SandAttrVal[] matchDescription)
               throws MessagerException

Register a node as a subscriber to broadcast messages of the type specified coming from the specified source. If the subscription is secure, then subscribe our local authorizer to the authorizer for the source.

If matchDescription is not null, then it is only necessary to deliver messages matching the description. A Messager may choose not to send unmatching messages for efficiency reasons. A subscribing node must always be prepared to accept any message of the given type, even those not matching the description.

Throws:

MessagerException

unsubscribe

public void unsubscribe(Messageable node,
                        java.lang.String messageClass,
                        java.lang.String senderInstanceName,
                        int optimize,
                        int mode,
                        java.lang.String localAuthorizerInstanceName)
                 throws MessagerException

Unregister a node as a subscriber to broadcast messages of the type specified coming from the specified source. If the subscription is secure, then subscribe our local authorizer to the authorizer for the source. This method is used by the node messaging infrastructure to suspend delivery of incoming messages in the even the node is no longer running.

Throws:

MessagerException

query

public SandMessage query(SandMessage msg,
                         java.lang.String recipientInstanceName,
                         int optimize,
                         int mode,
                         java.lang.String localAuthorizerInstanceName)
                  throws MessagerException

Send a synchronous request to the specified recipient and return the result. This method waits for a response, but MUST NOT WAIT FOREVER. It must return with either an exception or a result within a fixed time period. The appropriate time period varies with the Messager implementation.

There is no corresponding receive method defined for the interface. While the use of a receive method is common in Messager implementations, it is not strictly necessary, and its signature tends vary from one implementation to the next.

Throws:

MessagerException

queryReceiver

public void queryReceiver(Messageable node,
                          java.lang.String messageClass,
                          java.lang.String localAuthorizerInstanceName)
                   throws MessagerException

Register the node with the local authorizer, as recipient for the specified class of queries. Nodes that receive queries directly do not have to call here. This is only for secure messaging, so the local Authorizer knows who is handling which queries.

If this method is given null or the empty string for the localAuthorizerInstanceName, it can simply ignore the call.

Throws:

MessagerException

getWireSecurity

public int getWireSecurity()

Return one of the WIRE_ constants describing the level of transport security provided by this messager for MODE_SECURE communications. The wire security is independent of encryption capabilities of the Authorizer, which will typically employ its own encryption on top of the transport layer.

By returning WIRE_SECURECOMMS, a messager implementation can effectively override use of encryption in the Authorizer. If a messager provides secure communications, but it is not appropriate to override Authorizer encryption in all cases, then the Messager should return WIRE_BASICSECURITY, and NullEncryptors can be configured to optimize specific Authorizer paths.