com.inspirel.yami
Class Agent

java.lang.Object
  com.inspirel.yami.Agent

public final class Agent
extends java.lang.Object

Message broker.

The message broker that encapsulates physical channel management, incoming and outgoing message queues, listeners and resource management.

A single agent object can manage many listeners, which are responsible for accepting remote connections, and many incoming and outgoing connections.

The objects of this class can be safely used by multiple threads, including the threads that execute incoming message callbacks.

Nested Class Summary

static class

Agent.OutgoingFlowState Helper class for returning the state of outgoing flow.

Constructor Summary

Agent()
Default constructor, creates an agent object without any active listener and with default option values.

Agent(Parameters options)
Constructor, creates an agent object without any active listener and uses the provided configuration options.

Agent(Parameters options, ConnectionEventCallback connectionEventCallback, LogCallback logCallback, LogCallback.LogLevel logLevel)
Constructor, creates an agent object without any active listener and uses the provided configuration options and log callback.

Agent(Parameters options, LogCallback logCallback, LogCallback.LogLevel logLevel)
Constructor, creates an agent object without any active listener and uses the provided configuration options and log callback.

Method Summary

java.lang.String	addListener(java.lang.String target) Adds a new listener for the given target address.
void	close() Cleans up all resources and stops internal threads.
void	closeConnection(java.lang.String target) Closes the given connection with default (lowest) priority.
void	closeConnection(java.lang.String target, int priority) Closes the given connection.
Agent.OutgoingFlowState	getOutgoingFlowState() Obtains the state of overall outgoing flow.
void	openConnection(java.lang.String target) Opens the new connection.
void	registerObject(java.lang.String objectName, IncomingMessageCallback callback) Registers a new logical destination object.
void	registerValuePublisher(java.lang.String objectName, ValuePublisher publisher) Registers the value publisher as a new logical object.
void	removeListener(java.lang.String target) Removes existing listener.
OutgoingMessage	send(OutgoingMessageCallback updateCallback, java.lang.String target, java.lang.String objectName, java.lang.String messageName, YAMISerializable content) Sends the new outgoing message to the given destination.
OutgoingMessage	send(OutgoingMessageCallback updateCallback, java.lang.String target, java.lang.String objectName, java.lang.String messageName, YAMISerializable content, int priority) Sends the new outgoing message to the given destination.
OutgoingMessage	send(OutgoingMessageCallback updateCallback, java.lang.String target, java.lang.String objectName, java.lang.String messageName, YAMISerializable content, int priority, boolean autoConnect) Sends the new outgoing message to the given destination.
OutgoingMessage	send(java.lang.String target, java.lang.String objectName, java.lang.String messageName, YAMISerializable content) Sends the new outgoing message to the given destination.
OutgoingMessage	send(java.lang.String target, java.lang.String objectName, java.lang.String messageName, YAMISerializable content, int priority) Sends the new outgoing message to the given destination.
OutgoingMessage	send(java.lang.String target, java.lang.String objectName, java.lang.String messageName, YAMISerializable content, int priority, boolean autoConnect) Sends the new outgoing message to the given destination.
void	sendOneWay(java.lang.String target, java.lang.String objectName, java.lang.String messageName, YAMISerializable content) Sends the new outgoing message to the given destination, without the possibility to track its progress.
void	sendOneWay(java.lang.String target, java.lang.String objectName, java.lang.String messageName, YAMISerializable content, int priority) Sends the new outgoing message to the given destination, without the possibility to track its progress.
void	sendOneWay(java.lang.String target, java.lang.String objectName, java.lang.String messageName, YAMISerializable content, int priority, boolean autoConnect) Sends the new outgoing message to the given destination, without the possibility to track its progress.
void	unregisterObject(java.lang.String objectName) Unregisters a given destination object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Agent

public Agent()
      throws YAMIIOException

Default constructor, creates an agent object without any active listener and with default option values.

Throws:

YAMIIOException - if the network resources cannot be obtained

Agent

public Agent(Parameters options)
      throws YAMIIOException

Constructor, creates an agent object without any active listener and uses the provided configuration options.

Parameters:

options - set of configuration options

Throws:

YAMIIOException - if the network resources cannot be obtained

Agent

public Agent(Parameters options,
             LogCallback logCallback,
             LogCallback.LogLevel logLevel)
      throws YAMIIOException

Constructor, creates an agent object without any active listener and uses the provided configuration options and log callback.

Parameters:

options - set of configuration options

logCallback - callback object for log events

logLevel - requested log level

Throws:

YAMIIOException - if the network resources cannot be obtained

Agent

public Agent(Parameters options,
             ConnectionEventCallback connectionEventCallback,
             LogCallback logCallback,
             LogCallback.LogLevel logLevel)
      throws YAMIIOException

Constructor, creates an agent object without any active listener and uses the provided configuration options and log callback.

Parameters:

options - set of configuration options

connectionEventCallback - monitor for reporting connection events

logCallback - callback object for log events

logLevel - requested log level

Throws:

YAMIIOException - if the network resources cannot be obtained

Method Detail

addListener

public java.lang.String addListener(java.lang.String target)
                             throws YAMIIOException

Adds a new listener for the given target address.

The supported target formats are: - "tcp://host:port" for TCP/IP connections, where host can be provided in the symbolic or numeric form - "tcp://*:port" for TCP/IP connections, for "any" local address - "tcp://port" for TCP/IP connections, for "any" local address - "udp://host:port" for UDP communication, with rules as for TCP/IP

The port for TCP/IP protocol can be 0, in which case the actual port number is assigned by the system.

Parameters:

target - the target name for the new listener

Returns:

the locally resolved target name - this name can be used by clients to create new connections and by local code to remove the listener

Throws:

YAMIIOException - if the network resources cannot be obtained

removeListener

public void removeListener(java.lang.String target)

Removes existing listener.

Removes the listener denoted by its actual target name. Note that the actual target name might be different from the name provided when the listener was created, due to target resolution. The name which should be used for listener removal is the name that is returned by the addListener function.

Parameters:

target - the (resolved) target name of the listener to be removed

registerObject

public void registerObject(java.lang.String objectName,
                           IncomingMessageCallback callback)

Registers a new logical destination object.

Registers the new "object" that can be a logical destination for incoming messages. The incoming messages that are recognized as being addressed to this new object will be delivered through the IncomingMessageCallback interface, which is therefore supposed to be implemented by the user.

If an object with the given name is already registered, the registration data is replaced.

Parameters:

objectName - name of the newly registered object

callback - the callback implementation

registerValuePublisher

public void registerValuePublisher(java.lang.String objectName,
                                   ValuePublisher publisher)

Registers the value publisher as a new logical object.

If an object with the given name is already registered, the registration data is replaced.

Parameters:

objectName - name of the newly registered object

publisher - value publisher to be registered

unregisterObject

public void unregisterObject(java.lang.String objectName)

Unregisters a given destination object.

If an object with the given name is not registered, this operation does nothing.

Note: Due to performance and design tradeoffs it is not guaranteed that no more messages will be ever dispatched to the given object when this function returns. In fact, some of the messages that have been received by agent and not yet dispatched might be still dispatched shortly after this function returns. Only those messages that are received by agent after this function returns are guaranteed not to be dispatched to the unregistered object.

Parameters:

objectName - name of the object to unregister

openConnection

public void openConnection(java.lang.String target)
                    throws YAMIIOException

Opens the new connection. Opens the new channel or does nothing if the channel already exists. This function is not necessary with automatic connection recovery option in send and sendOneWay.

Parameters:

target - The name of the target endpoint. This name should correspond to the listener name in some target agent object.

Throws:

YAMIIOException - if the channel cannot be established

send

public OutgoingMessage send(java.lang.String target,
                            java.lang.String objectName,
                            java.lang.String messageName,
                            YAMISerializable content)
                     throws YAMIIOException

Sends the new outgoing message to the given destination.

The content object is serialized and is no longer referenced after this function returns. If the content is null, an empty Parameters object is sent.

Note: This function implicitly opens a new communication channel if it is not already open. This channel is kept open until it is explicitly closed (see the closeConnection function) or until the whole agent is closed or the communication error is detected.

Parameters:

target - the name of the target endpoint - this name should correspond to the listener name in some target agent object

objectName - the name of the logical destination object in the target agent

messageName - the name of the message

content - the content of the message

Returns:

the handler to the outgoing message object

Throws:

YAMIIOException - if the channel cannot be established

send

public OutgoingMessage send(java.lang.String target,
                            java.lang.String objectName,
                            java.lang.String messageName,
                            YAMISerializable content,
                            int priority)
                     throws YAMIIOException

Sends the new outgoing message to the given destination.

The content object is serialized and is no longer referenced after this function returns. If the content is null, an empty Parameters object is sent.

Note: This function implicitly opens a new communication channel if it is not already open. This channel is kept open until it is explicitly closed (see the closeConnection function) or until the whole agent is closed or the communication error is detected.

Parameters:

target - the name of the target endpoint - this name should correspond to the listener name in some target agent object

objectName - the name of the logical destination object in the target agent

messageName - the name of the message

content - the content of the message

priority - the priority of the message

Returns:

the handler to the outgoing message object

Throws:

YAMIIOException - if the channel cannot be established

send

public OutgoingMessage send(java.lang.String target,
                            java.lang.String objectName,
                            java.lang.String messageName,
                            YAMISerializable content,
                            int priority,
                            boolean autoConnect)
                     throws YAMIIOException

Sends the new outgoing message to the given destination.

The content object is serialized and is no longer referenced after this function returns. If the content is null, an empty Parameters object is sent.

Note: This function implicitly opens a new communication channel if it is not already open. This channel is kept open until it is explicitly closed (see the closeConnection function) or until the whole agent is closed or the communication error is detected.

Parameters:

target - the name of the target endpoint - this name should correspond to the listener name in some target agent object

objectName - the name of the logical destination object in the target agent

messageName - the name of the message

content - the content of the message

priority - the priority of the message

autoConnect - the flag controlling automatic (re)connection

Returns:

the handler to the outgoing message object

Throws:

YAMIIOException - if the channel cannot be established

send

public OutgoingMessage send(OutgoingMessageCallback updateCallback,
                            java.lang.String target,
                            java.lang.String objectName,
                            java.lang.String messageName,
                            YAMISerializable content)
                     throws YAMIIOException

Sends the new outgoing message to the given destination.

The content object is serialized and is no longer referenced after this function returns. If the content is null, an empty Parameters object is sent.

Note: This function implicitly opens a new communication channel if it is not already open. This channel is kept open until it is explicitly closed (see the closeConnection function) or until the whole agent is closed or the communication error is detected.

Parameters:

updateCallback - object that will be called when the state of outgoing message changes

target - the name of the target endpoint - this name should correspond to the listener name in some target agent object

objectName - the name of the logical destination object in the target agent

messageName - the name of the message

content - the content of the message

Returns:

the handler to the outgoing message object

Throws:

YAMIIOException - if the channel cannot be established

send

public OutgoingMessage send(OutgoingMessageCallback updateCallback,
                            java.lang.String target,
                            java.lang.String objectName,
                            java.lang.String messageName,
                            YAMISerializable content,
                            int priority)
                     throws YAMIIOException

Sends the new outgoing message to the given destination.

The content object is serialized and is no longer referenced after this function returns. If the content is null, an empty Parameters object is sent.

Note: This function implicitly opens a new communication channel if it is not already open. This channel is kept open until it is explicitly closed (see the closeConnection function) or until the whole agent is closed or the communication error is detected.

Parameters:

updateCallback - object that will be called when the state of outgoing message changes

target - the name of the target endpoint - this name should correspond to the listener name in some target agent object

objectName - the name of the logical destination object in the target agent

messageName - the name of the message

content - the content of the message

priority - the priority of the message

Returns:

the handler to the outgoing message object

Throws:

YAMIIOException - if the channel cannot be established

send

public OutgoingMessage send(OutgoingMessageCallback updateCallback,
                            java.lang.String target,
                            java.lang.String objectName,
                            java.lang.String messageName,
                            YAMISerializable content,
                            int priority,
                            boolean autoConnect)
                     throws YAMIIOException

Sends the new outgoing message to the given destination.

The content object is serialized and is no longer referenced after this function returns. If the content is null, an empty Parameters object is sent.

Note: This function implicitly opens a new communication channel if it is not already open. This channel is kept open until it is explicitly closed (see the closeConnection function) or until the whole agent is closed or the communication error is detected.

Parameters:

updateCallback - object that will be called when the state of outgoing message changes

target - the name of the target endpoint - this name should correspond to the listener name in some target agent object

objectName - the name of the logical destination object in the target agent

messageName - the name of the message

content - the content of the message

priority - the priority of the message

autoConnect - the flag controlling automatic (re)connection

Returns:

the handler to the outgoing message object

Throws:

YAMIIOException - if the channel cannot be established

sendOneWay

public void sendOneWay(java.lang.String target,
                       java.lang.String objectName,
                       java.lang.String messageName,
                       YAMISerializable content)
                throws YAMIIOException

Sends the new outgoing message to the given destination, without the possibility to track its progress.

The content object is serialized and is no longer referenced after this function returns. If the content is null, an empty Parameters object is sent.

Note: This function implicitly opens a new communication channel if it is not already open. This channel is kept open until it is explicitly closed (see the closeConnection function) or until the whole agent is closed or the communication error is detected.

Parameters:

target - the name of the target endpoint - this name should correspond to the listener name in some target agent object

objectName - the name of the logical destination object in the target agent

messageName - the name of the message

content - the content of the message

Throws:

YAMIIOException - if the channel cannot be established

sendOneWay

public void sendOneWay(java.lang.String target,
                       java.lang.String objectName,
                       java.lang.String messageName,
                       YAMISerializable content,
                       int priority)
                throws YAMIIOException

Sends the new outgoing message to the given destination, without the possibility to track its progress.

The content object is serialized and is no longer referenced after this function returns. If the content is null, an empty Parameters object is sent.

Note: This function implicitly opens a new communication channel if it is not already open. This channel is kept open until it is explicitly closed (see the closeConnection function) or until the agent is closed or the communication error is detected.

Parameters:

target - the name of the target endpoint - this name should correspond to the listener name in some target agent object

objectName - the name of the logical destination object in the target agent

messageName - the name of the message

content - the content of the message

priority - the priority of the message

Throws:

YAMIIOException - if the channel cannot be established

sendOneWay

public void sendOneWay(java.lang.String target,
                       java.lang.String objectName,
                       java.lang.String messageName,
                       YAMISerializable content,
                       int priority,
                       boolean autoConnect)
                throws YAMIIOException

Sends the new outgoing message to the given destination, without the possibility to track its progress.

The content object is serialized and is no longer referenced after this function returns. If the content is null, an empty Parameters object is sent.

Note: This function implicitly opens a new communication channel if it is not already open. This channel is kept open until it is explicitly closed (see the closeConnection function) or until the agent is closed or the communication error is detected.

Parameters:

target - the name of the target endpoint - this name should correspond to the listener name in some target agent object

objectName - the name of the logical destination object in the target agent

messageName - the name of the message

content - the content of the message

priority - the priority of the message

autoConnect - the flag controlling automatic (re)connection

Throws:

YAMIIOException - if the channel cannot be established

closeConnection

public void closeConnection(java.lang.String target)

Closes the given connection with default (lowest) priority.

Parameters:

target - the name of connection to close

closeConnection

public void closeConnection(java.lang.String target,
                            int priority)

Closes the given connection.

The priority allows to properly handle the existing outgoing messages that are waiting in the outgoing queue for transmission.

The existing messages with lower priority are abandoned, whereas the existing messages with priority equal or higher to the one provided as parameter are retained in the outgoing queue and are properly pushed for transmission before the channel is physically closed.

The channel is closed immediately only if there are no messages waiting in its outgoing queue.

If the failover group is given then all targets from the group are closed.

Closing the channel that does not exist is a no-op.

Parameters:

target - the name of connection to close

priority - proprity of the request, respects existing messages in the outgoing queue

getOutgoingFlowState

public Agent.OutgoingFlowState getOutgoingFlowState()

Obtains the state of overall outgoing flow. Obtains the state of overall outgoing flow. Note: The outgoing flow is a combination of all outgoing traffic, and is not tied to any particular communication channel.

close

public void close()

Cleans up all resources and stops internal threads.

Note: After this function is called the agent should not be used any longer.