com.idimiddleware.objectq

Class Dispatcher

java.lang.Object

com.idimiddleware.objectq.Dispatcher

public class Dispatcher
extends java.lang.Object

The dispatcher is created when the ObjectQ class is instantiated. It sends an envelope to the object that will process it. It can dispatch a service request to a service provider (an agent object), an asynchronous response to a client (through a manager object), or an event notification to a event handler (manager object).
The Dispatcher class supports asynchronous client requests in client processes and requests to service providers in server processes. It registers/unregisters servers, messages, and events. It also tracks the status of agents as being busy or not busy.
Once an envelope is received, the dispatcher examines the envelope and handles these types of incoming messages:

• Request Message - Using the service name in the envelope, the dispatcher executes the requestHandler function of an available object that has registered to provide that service.
• Response Message - Using the invoke id in the envelope, the dispatcher executes the responseHandler function of the object which has registered that invoke id.
• Event Report Request Message - Using a subscription id and the service name, the dispatcher executes the eventHandler function of the object which has registered as an event handler for that subscription id and service.

In support of service providers, the dispatcher maintains a list of service providers that contains the following information:

• Name of service.
• The object (that is, the agent) providing the service.
• Status of object providing the service (busy or not busy).

In response to a query of this list, the dispatcher can indicate how many agents for a given service are available. When an actual service is called, if all agents for that service are busy, the dispatcher generates an exception.
In support of asynchronous message processing, the dispatcher maintains a list of outstanding messages. The list contains the following information:

• Invoke id (a unique request/response identifier).
• The object (that is, the manager) waiting for the result.
• Time-out value (at the application level).

When the dispatcher object receives a response message, it determines which object should receive the message, based on the invoke id, and executes the response handling function of that object. Each object that receives responses asynchronously must have a response handling function.
For event notification processing, the dispatcher maintains a list of event handling objects. The list contains the following information:

• Service name and subscription id.
• The object (that is, the manager) providing event notification handling.

If the message is an Event Report Request message, the dispatcher gets the service name and subscription id from the envelope. It then determines which object(s) should receive the message, and executes the event handling function of that object. Each object that handles event notification messages must have an event handling function.
The dispatcher also provides timeout processing. When requested, the dispatcher looks through its list of messages awaiting responses and determines if any have timed out, based on the timeout value given when the message was registered. For each message that has timed out, the dispatcher executes a timeout handler function on the registered object and removes the message from its list.

Field Summary

Fields

Modifier and Type	Field and Description
static int	AGENT_BUSY
static int	AGENT_NOT_BUSY

Method Summary

Modifier and Type	Method and Description
void	dispatch(Envelope envelope) Dispatch the envelope to he appropriate object's message handler.
void	processTimeOuts() Invoke timeout processing for each message where timeout has occurred.
void	registerEventHandler(java.lang.String service, long subscriptionId, Manager manager) Register a manager as an event message handler for a service/subscription.
void	registerMessage(java.lang.String invokeId, Manager manager) Register a manager as a message handler for an invoke id.
void	registerMessage(java.lang.String invokeId, Manager manager, int timeout) Register a manager as a message handler for an invoke id.
void	registerServer(java.lang.String service, Agent agent) Register an agent as a message handler for a service
void	serverAvailable(java.lang.String service, Agent agent) Mark an agent as available.
int	serverCount(java.lang.String service) Get the count of agents for a service.
int	serverCountAvailable(java.lang.String service) Get the count of available agents for a service.
void	serverUnavailable(java.lang.String service, Agent agent) Mark an agent as unavailable.
java.lang.String	toString()
void	unregisterEventHandler(java.lang.String service, long subscriptionId) Unregister a manager for a service/subscription.
void	unregisterMessage(java.lang.String invokeId) Unregister a manager for an invoke id.
void	unregisterServer(java.lang.String service, Agent agent) Unregister an agent for a service.

Methods inherited from class java.lang.Object

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

Field Detail

AGENT_BUSY

public static final int AGENT_BUSY

See Also:

Constant Field Values

AGENT_NOT_BUSY

public static final int AGENT_NOT_BUSY

See Also:

Constant Field Values

Method Detail

dispatch

public void dispatch(Envelope envelope)
              throws NoHandlerException,
                     EnvelopeOverflowException,
                     VendorTransportException

Dispatch the envelope to he appropriate object's message handler.

Parameters:

envelope - The envelope to be dispatched.

Throws:

NoHandlerException - There is no available handler for this envelope.

EnvelopeOverflowException

VendorTransportException

processTimeOuts

public void processTimeOuts()

Invoke timeout processing for each message where timeout has occurred.

registerEventHandler

public void registerEventHandler(java.lang.String service,
                                 long subscriptionId,
                                 Manager manager)
                          throws java.lang.IllegalArgumentException,
                                 DuplicateEntryException

Register a manager as an event message handler for a service/subscription.

Parameters:

service - The service (for example, "Demo.Sales").

subscriptionId - The subscription's id (obtained from the response envelope).

manager - The manager handling this subscription.

Throws:

java.lang.IllegalArgumentException - The service is not recognised.

DuplicateEntryException - There's already an entry for this service/agent.

registerMessage

public void registerMessage(java.lang.String invokeId,
                            Manager manager)
                     throws DuplicateEntryException

Register a manager as a message handler for an invoke id. The timeout value, after which it will be assumed there is no response, is the default 600 seconds.

Parameters:

invokeId - The invoke id (obtained from the request envelope).

manager - The manager handling this invoke id.

Throws:

DuplicateEntryException - There's already an entry for this invoke id/manager.

registerMessage

public void registerMessage(java.lang.String invokeId,
                            Manager manager,
                            int timeout)
                     throws DuplicateEntryException

Register a manager as a message handler for an invoke id. The timeout value, after which it will be assumed there is no response, is in seconds.

Parameters:

invokeId - The invoke id (obtained from the request envelope).

manager - The manager handling this invoke id.

timeout - The timeout, in seconds.

Throws:

DuplicateEntryException - There's already an entry for this invoke id/manager.

registerServer

public void registerServer(java.lang.String service,
                           Agent agent)
                    throws DuplicateEntryException

Register an agent as a message handler for a service

Parameters:

service - The service (for example, "Demo.Sales").

agent - The agent handling this service.

Throws:

DuplicateEntryException - There's already an entry for this service/agent.

serverAvailable

public void serverAvailable(java.lang.String service,
                            Agent agent)
                     throws java.lang.IllegalArgumentException

Mark an agent as available.

Parameters:

service - The service being handled.

agent - The agent.

Throws:

java.lang.IllegalArgumentException - The agent has not been previously registered.

serverCount

public int serverCount(java.lang.String service)

Get the count of agents for a service.

Parameters:

service - The service.

Returns:

The total number of registered agents.

serverCountAvailable

public int serverCountAvailable(java.lang.String service)

Get the count of available agents for a service.

Parameters:

service - The service.

Returns:

The total number of registered agents that ae available to handle requests.

serverUnavailable

public void serverUnavailable(java.lang.String service,
                              Agent agent)
                       throws java.lang.IllegalArgumentException

Mark an agent as unavailable.

Parameters:

service - The service being handled.

agent - The agent.

Throws:

java.lang.IllegalArgumentException - The agent has not been previously registered.

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

unregisterEventHandler

public void unregisterEventHandler(java.lang.String service,
                                   long subscriptionId)
                            throws java.lang.IllegalArgumentException

Unregister a manager for a service/subscription. If it was not previously registered, it is silently ignored.

Parameters:

service - The service.

subscriptionId - The subscription id.

Throws:

java.lang.IllegalArgumentException

unregisterMessage

public void unregisterMessage(java.lang.String invokeId)

Unregister a manager for an invoke id. If it was not previously registered, it is silently ignored.

Parameters:

invokeId - The invoke id.

unregisterServer

public void unregisterServer(java.lang.String service,
                             Agent agent)

Unregister an agent for a service. If it was not previously registered, it is silently ignored.

Parameters:

service - The service.

agent - The agent.