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. A default communication strategy that sends serialized objects via sockets is 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.

Inner Class Summary

static class	IPC.BasicDestinationTable A HashMap implementation of the DestinationTable interface.
static class	IPC.BasicInputMessage A minimal implementation of InputMessage.
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 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.ObjectStreamCommunicationStrategy A communication strategy in which a destination is mapped to a host and port number, and objects are sent by writing their serialization to a socket.
static class	IPC.ObjectStreamConnection A Connection that is used to send and receive serialized objects via a socket.
static class	IPC.ObjectStreamNameServer A Thread that acts as a name-server on a specified port.
static class	IPC.ObjectStreamServer A Thread that accepts connections to a ServerSocket and creates an object-reading thread for each connection.
static class	IPC.ServiceAddress An object that contains a host name and a port number.
static class	IPC.SimpleIXCommunicationStrategy An ObjectStream communication strategy that provides default host and port assignments for standard I-X agents.
static class	IPC.SimpleIXDestinationTable A DestinationTable that provides default host and port assignments for standard I-X agents, suitable for use with an instance of ObjectStreamCommunicationStrategy.
static class	IPC.SimpleIXXMLCommunicationStrategy An ObjectStream communication strategy that provides default host and port assignments for standard I-X agents and encodes the message contents in XML rather than serializing.
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

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

Method Summary

static void	exceptionlessSend(java.lang.Object destination, java.lang.Object contents) Like sendObject but catches any IPC.IPCException.
static IPC.CommunicationStrategy	getCommunicationStrategy(java.lang.String strategyName) Returns a CommunicationStrategy based on a name that is either 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 default communication strategy.
static void	setDefaultCommunicationStrategy(IPC.CommunicationStrategy s) Sets the communication strategy used when none is explicitly specified.
static void	setDefaultCommunicationStrategy(java.lang.String strategyName) Sets the communication strategy used when none is explicitly specified.
static void	setupServer(java.lang.Object destination, IPC.MessageListener listener) Does what is required for this agent to receive messages sent using the default communication strategy.

Methods inherited from class java.lang.Object

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

Field Detail

defaultCommunicationStrategy

static IPC.CommunicationStrategy defaultCommunicationStrategy

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

Method Detail

setDefaultCommunicationStrategy

public static void setDefaultCommunicationStrategy(IPC.CommunicationStrategy s)

Sets the communication strategy used when none is explicitly specified.

setDefaultCommunicationStrategy

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

Sets the communication strategy used when none is explicitly specified. The strategyName is interpreted by the getCommunicationStrategy(String) method.

See Also:

getCommunicationStrategy(String)

getCommunicationStrategy

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

Returns a CommunicationStrategy based on a name that is either a special abbreviation or the name of a class. The algorithm is as follows:

1. if name is "", 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, where Name is name with its first character changed to upper case, use that class;
5. else throw an IllegalArgumentException.

See Also:

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

sendObject

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

Sends an object to the specified destination using the default 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.

exceptionlessSend

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

Like sendObject but catches any IPC.IPCException. It can be used in cases where you don't want to detect a failure and don't want an exception to be thrown any further.

See Also:

IPC.IPCException, sendObject(Object, Object)

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 default 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.