ix.util
Class IPC

java.lang.Object
  ix.util.IPC

public class IPC
extends java.lang.Object

Support for interprocess communication in a framework that allows different communication strategies to be used in a uniform way. Some simple strategies, such as one that sends serialized objects via sockets, are included.

The framework specifies certain entities only a in very general way. Communication strategies that are meant to be interchangeable must therefore follow shared conventions - not enforced by the framework - chiefly concerning the objects used to represent "destinations" and implementations of the InputMessage interface.

Note that a "destination" need not contain all the information needed for communication with the corresponding agent. Instead, the destination may be merely a name, perhaps as a String, with the rest of the information stored elsewhere.

Nested Class Summary

static class	IPC.BasicDestinationTable A HashMap implementation of the DestinationTable interface.
static class	IPC.BasicInputMessage A minimal implementation of InputMessage.
static class	IPC.BrokenConnectionException
static class	IPC.BufferedMessageListener A MessageListener that enqueues messages for processing in a separate thread of the listener's own.
static interface	IPC.CommunicationStrategy An object that determines how various IPC operations are performed.
static interface	IPC.Connection An object that can send and receive.
static interface	IPC.DestinationTable A mapping from destination names to the data needed to establish connections with the corresponding agents.
static class	IPC.EmptyCommunicationStrategy A strategy that just throws an exception whenever the agent tries to send.
static interface	IPC.InputMessage An object that represents an incoming message.
static class	IPC.IPCException The exception thrown by IPC methods.
static interface	IPC.MessageListener An object that is notified when a message is received.
static class	IPC.SimpleIXCommunicationStrategy An ObjectStream communication strategy for I-X agents.
static class	IPC.SimpleIXXMLCommunicationStrategy An XMLObjectStream communication strategy for I-X agents.
static interface	IPC.SocketlikeCommunicationStrategy A CommunicationStrategy that provides "connections" analogous to sockets and a visible mapping from destination names to the data needed to establish a connection.
static class	IPC.XMLObjectStreamCommunicationStrategy A version of ObjectStreamCommunicationStrategy that encodes the message contents in XML rather than serializing.

Field Summary

(package private) static IPC.CommunicationStrategy	communicationStrategy The communication strategy used by the static methods of this class that do not have a communication strategy as a parameter.
(package private) static java.util.List	ipcListeners Listeners that can observe messages as they're sent and received.
(package private) static java.lang.Object	thisAgentAsDestination

Method Summary

static void	addIPCListener(IPCListener listener)
protected static IPC.CommunicationStrategy	evalStrategyExpr(java.lang.String e) Evaluate the description of a ParameterizedCommStrategy.
static void	fireMessageReceived(IPC.InputMessage message)
static void	fireMessageSent(java.lang.Object dest, java.lang.Object contents)
static void	fireSendingMessage(java.lang.Object dest, java.lang.Object contents)
static IPC.CommunicationStrategy	getCommunicationStrategy() Returns the communication strategy used by the static methods of this class that do not have a communication strategy as a parameter.
static IPC.CommunicationStrategy	makeCommunicationStrategy(java.lang.String strategyName) Returns a CommunicationStrategy based on a name, name, that is either an expression containing a colon, a special abbreviation or the name of a class.
static void	sendObject(java.lang.Object destination, java.lang.Object contents) Sends an object to the specified destination using the global communication strategy.
static void	setCommunicationStrategy(IPC.CommunicationStrategy s) Sets the communication strategy used by the static methods of this class that do not have a communication strategy as a parameter.
static void	setCommunicationStrategy(java.lang.String strategyName) Sets the communication strategy used by the static methods of this class that do not have a communication strategy as a parameter.
static void	setupServer(java.lang.Object destination, IPC.MessageListener listener) Does what is required for this agent to receive messages sent using the global communication strategy.

Methods inherited from class java.lang.Object

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

Field Detail

communicationStrategy

static IPC.CommunicationStrategy communicationStrategy

The communication strategy used by the static methods of this class that do not have a communication strategy as a parameter.

thisAgentAsDestination

static java.lang.Object thisAgentAsDestination

ipcListeners

static java.util.List ipcListeners

Listeners that can observe messages as they're sent and received.

Method Detail

getCommunicationStrategy

public static IPC.CommunicationStrategy getCommunicationStrategy()

Returns the communication strategy used by the static methods of this class that do not have a communication strategy as a parameter.

setCommunicationStrategy

public static void setCommunicationStrategy(IPC.CommunicationStrategy s)

Sets the communication strategy used by the static methods of this class that do not have a communication strategy as a parameter.

setCommunicationStrategy

public static void setCommunicationStrategy(java.lang.String strategyName)

Sets the communication strategy used by the static methods of this class that do not have a communication strategy as a parameter. The strategyName is interpreted by the makeCommunicationStrategy(String) method.

makeCommunicationStrategy

public static IPC.CommunicationStrategy makeCommunicationStrategy(java.lang.String strategyName)

Returns a CommunicationStrategy based on a name, name, that is either an expression containing a colon, a special abbreviation or the name of a class. For the expression case, see evalStrategyExpr(String); otherwise, the algorithm is as follows, with Name standing for name with its first character changed to upper case:

1. if name is "" or "simple", use SimpleIXCommunicationStrategy;
2. else if name is "xml", use SimpleIXXMLCommunicationStrategy;
3. else if a class named name exists, use that class;
4. else if a class named ix.name.NameCommunicationStrategy exists, use that class;
5. else if a class named ix.util.ipc.NameStrategy exists, use that class;
6. else throw an IllegalArgumentException.

See Also:

IPC.SimpleIXCommunicationStrategy, IPC.SimpleIXXMLCommunicationStrategy, setCommunicationStrategy(String strategyName)

evalStrategyExpr

protected static IPC.CommunicationStrategy evalStrategyExpr(java.lang.String e)

Evaluate the description of a ParameterizedCommStrategy. The syntax is name:args where name is the name of a ParameterizedCommStrategy and args is a comma-separated list. The interpretation of the arguments is up to the parameterized comm strategy, but usually the arguments will be comm strategy names or expressions. Some strategies that expect more than one strategy as parameters use the syntax default:strategyExpr to say which strategy is the default.

Examples:

    tracing:xml
    wrapper:somepack.subpack.SomeCommunicationStrategy
    dispatching:jabber,default:xml,tracing:xml
    dispatching:jabber,xml,default:tracing:xml
    random:this,might,be,anything
 

There's an obvious problem if one of the parameter strategies expects muliple parameters of its own. For example, "tracing:dispatching:a,b,c" will give the tracing strategy parameters "dispatching:a", "b", and "c". If this becomes a problem in practice, we'll define a parser that can handle parenthesized subexpressions.

sendObject

public static void sendObject(java.lang.Object destination,
                              java.lang.Object contents)

Sends an object to the specified destination using the global communication strategy. The agents who are sent these objects must be using a compatible strategy. The recipient should in effect get a copy of the object that was sent, but the exact relationship between the two objects depends on the communication strategy.

If the object being sent implements the Sendable interface and has a null sender-id, the sender-id will be set to the "destination" recorded by the setupServer method. (The sender-id is actually set in a clone of the original object so that the original isn't modified.)

See Also:

setupServer(Object destination, MessageListener listener)

setupServer

public static void setupServer(java.lang.Object destination,
                               IPC.MessageListener listener)

Does what is required for this agent to receive messages sent using the global communication strategy. Here the "destination" is the agent in which setupServer was called, not a remote agent. The (remote) agents sending messages to the server must be using a compatible communication strategy. Note that setupServer does not assume that all messages are "sending an object" in the sense of the sendObject method.

The destination is recorded and will be used by the sendObject method to fill in the sender-id of Sendable objects.

addIPCListener

public static void addIPCListener(IPCListener listener)

fireSendingMessage

public static void fireSendingMessage(java.lang.Object dest,
                                      java.lang.Object contents)

fireMessageSent

public static void fireMessageSent(java.lang.Object dest,
                                   java.lang.Object contents)

fireMessageReceived

public static void fireMessageReceived(IPC.InputMessage message)