Message broker. More...

Classes
class	OutgoingFlowState
	Helper class for returning the state of outgoing flow. More...
class	Util
Public Member Functions
	Agent ()
	Default constructor, creates new instance of the Agent class with default option values.
	Agent (Parameters options)
	Creates new instance of the Agent class using provided configuration options.
	Agent (LogHandler logHandler, LogEventArgs.LogLevel logLevel)
	Creates new instance of the Agent class with default options values, appends handler for Log event.
	Agent (Parameters options, LogHandler logHandler, LogEventArgs.LogLevel logLevel)
	Creates new instance of the Agent class, appends handler for Log event and uses the provided configuration options.
string	AddListener (string target)
	Adds a new listener for the given target address.
void	RemoveListener (string target)
	Removes existing listener.
void	RegisterObject (string objectName, IncomingMessageHandler callback)
	Registers a new logical destination object.
void	RegisterValuePublisher (string objectName, ValuePublisher publisher)
	Registers the value publisher as a new logical object.
void	UnregisterObject (string objectName)
	Unregisters a given destination object.
void	OpenConnection (string target)
	Opens the new connection.
OutgoingMessage	Send (string target, string objectName, string messageName, YAMISerializable content)
	Sends the new outgoing message to the given destination.
OutgoingMessage	Send (string target, string objectName, string messageName, YAMISerializable content, int priority)
	Sends the new outgoing message to the given destination.
OutgoingMessage	Send (string target, string objectName, string messageName, YAMISerializable content, int priority, bool autoConnect)
	Sends the new outgoing message to the given destination.
void	SendOneWay (string target, string objectName, string messageName, YAMISerializable content)
	Sends the new outgoing message to the given destination, without the possibility to track its progress.
void	SendOneWay (string target, string objectName, string messageName, YAMISerializable content, int priority)
	Sends the new outgoing message to the given destination, without the possibility to track its progress.
void	SendOneWay (string target, string objectName, string messageName, YAMISerializable content, int priority, bool autoConnect)
	Sends the new outgoing message to the given destination, without the possibility to track its progress.
void	CloseConnection (string target)
	Closes the given connection with default (lowest) priority.
void	CloseConnection (string target, int priority)
	Closes the given connection.
OutgoingFlowState	GetOutgoingFlowState ()
	Obtains the state of overall outgoing flow.
void	Close ()
	Cleans up all resources and stops internal threads.
Properties
LogEventArgs.LogLevel	LogLevel `[get, set]`
	Gets or sets logging level for which Log event will be raised.
Events
LogHandler	Log
	Occurs when YAMI library wants to log anything on currently set logging level.
ConnectionEventHandler	ConnectionsChanged
	Occurs when state of connections was changed.

Detailed Description

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.

Constructor & Destructor Documentation

Inspirel.YAMI.Agent.Agent ( )

Default constructor, creates new instance of the Agent class with default option values.

if the network resources cannot be obtained

Inspirel.YAMI.Agent.Agent ( Parameters options )

Creates new instance of the Agent class using provided configuration options.

Parameters:

options set of configuration options

Inspirel.YAMI.Agent.Agent	(	LogHandler	logHandler,
		LogEventArgs.LogLevel	logLevel
	)

Creates new instance of the Agent class with default options values, appends handler for Log event.

Parameters:

logHandler	Handler for Logevent
logLevel	Initial log level

Inspirel.YAMI.Agent.Agent	(	Parameters	options,
		LogHandler	logHandler,
		LogEventArgs.LogLevel	logLevel
	)

Creates new instance of the Agent class, appends handler for Log event and uses the provided configuration options.

Parameters:

options	set of configuration options
logHandler	Handler for Logevent
logLevel	Initial log level

Member Function Documentation

string Inspirel.YAMI.Agent.AddListener ( string target )

Adds a new listener for the given target address.

format
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

Exceptions:

YAMIIOException if the network resources cannot be obtained

void Inspirel.YAMI.Agent.Close ( )

Cleans up all resources and stops internal threads.

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

void Inspirel.YAMI.Agent.CloseConnection ( string target )

Closes the given connection with default (lowest) priority.

See CloseConnection(string, int) for details.

Parameters:

target the name of connection to close

void Inspirel.YAMI.Agent.CloseConnection	(	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

OutgoingFlowState Inspirel.YAMI.Agent.GetOutgoingFlowState ( )

Obtains the state of overall outgoing flow.

Returns:: Current outgoing flow state.

The outgoing flow is a combination of all outgoing traffic, and is not tied to any particular communication channel.

void Inspirel.YAMI.Agent.OpenConnection ( string target )

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(string, string, string, Inspirel.YAMI.YAMISerializable, int, bool) and SendOneWay(string, string, string, Inspirel.YAMI.YAMISerializable, int, bool).

Parameters:

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

Exceptions:

YAMIIOException if the channel cannot be established

void Inspirel.YAMI.Agent.RegisterObject	(	string	objectName,
		IncomingMessageHandler	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 IncomingMessageHandler implementation 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 handler implementation

See also:: IncomingMessageArgs

void Inspirel.YAMI.Agent.RegisterValuePublisher	(	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

void Inspirel.YAMI.Agent.RemoveListener ( 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

OutgoingMessage Inspirel.YAMI.Agent.Send	(	string	target,
		string	objectName,
		string	messageName,
		YAMISerializable	content,
		int	priority,
		bool	autoConnect
	)

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(string, int) 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

Exceptions:

YAMIIOException if the channel cannot be established

OutgoingMessage Inspirel.YAMI.Agent.Send	(	string	target,
		string	objectName,
		string	messageName,
		YAMISerializable	content,
		int	priority
	)

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(string, int) 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

Exceptions:

YAMIIOException if the channel cannot be established

OutgoingMessage Inspirel.YAMI.Agent.Send	(	string	target,
		string	objectName,
		string	messageName,
		YAMISerializable	content
	)

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(string, int) 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

Exceptions:

YAMIIOException if the channel cannot be established

void Inspirel.YAMI.Agent.SendOneWay	(	string	target,
		string	objectName,
		string	messageName,
		YAMISerializable	content
	)

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(string, int) 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

Exceptions:

YAMIIOException if the channel cannot be established

void Inspirel.YAMI.Agent.SendOneWay	(	string	target,
		string	objectName,
		string	messageName,
		YAMISerializable	content,
		int	priority
	)

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(string, int) 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

Exceptions:

YAMIIOException if the channel cannot be established

void Inspirel.YAMI.Agent.SendOneWay	(	string	target,
		string	objectName,
		string	messageName,
		YAMISerializable	content,
		int	priority,
		bool	autoConnect
	)

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(string, int) 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

Exceptions:

YAMIIOException if the channel cannot be established

void Inspirel.YAMI.Agent.UnregisterObject ( 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

Property Documentation

LogEventArgs.LogLevel Inspirel.YAMI.Agent.LogLevel [get, set]

Gets or sets logging level for which Log event will be raised.

Event Documentation

ConnectionEventHandler Inspirel.YAMI.Agent.ConnectionsChanged

Occurs when state of connections was changed.

See also:: ConnectionEventArgs

LogHandler Inspirel.YAMI.Agent.Log

Occurs when YAMI library wants to log anything on currently set logging level.

See also:: LogEventArgs, LogEventArgs.LogLevel, LogLevel

The documentation for this class was generated from the following file:

src/Agent.cs

Inspirel.YAMI.Agent Class Reference

Classes

Public Member Functions

Properties

Events

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Property Documentation

Event Documentation