Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.Name `CommunicationStrategy` 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)

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD