Communication Package

Document #: 221ZR025
Authors: M. Nassehi (ZRL), M. Steiner (ZRL)
Editor: M. Nassehi (ZRL)
Reviewer: T. Himstedt (GMD)
Status: Draft Version. 5, SEMPER internal

Note: Please see the Changes section at the end of this document. J.Brauckmann

Communication Service

The communication package of SEMPER provides connectivity between modules in separate entities. The basic communication service is provided by ComPoints. A ComPoint is an object which allows an application program to access the underlying communication protocol, e.g., tcp or http. It allows a module to receive all messages directed to its port. This service is refined by Channels, which allow the receiving module to specify the correlator of the message that it is expecting. ComPoint and Channel APIs are based on the synchronous, i.e. blocking, model.

ComPoints

ComPoint, like socket, is an object which allows an application program to access the underlying communication protocol. For each supported protocol, there is class that implements ComPoint. In order to simplify the task of the application programs, these implementation classes are not a part of API. Instead, a ComManager class is provided which examines the protocol field in the desired address and constructs a ComPoint of the corresponding implementation class. The addresses themselves are defined by ComPointAddress. The constants are defined in ComPointConstants. There are also ComPointExceptions which are thrown in case of errors, but, for the sake of simplicity, are not caught in the following code samples.

Note that the Communication Block must be initialized through the init method of the ComManager class. This init method invokes the corresponding methods of the classes implementing the communication protocols, currently ComPointTCP, ComPointHTTP and ComPointMail. The invocation of the init method of ComPointMail will result in an actual initialization, only if the three parameters which are used by ComPointMail (see the section on the configuration parameters below) are set in the configuration file. Otherwise, the mail protocol may not be used.

The initiator is the module which sends the first message and the responder is the module receiving it. Here is a sample code for the initiator side:

  // Create the address of the responder.
  ComPointAddress address = new ComPointAddress(protocol, host, port, path);

  // Open an initiator ComPoint.
  ComPoint comPoint =
    ComManager.comPoint(ComPointConstants.COMPOINT_INITIATOR, address);

  // Send a message.
  Message message = Message(...);
  comPoint.write(message);

  // Receive a response.
  Response response = (Response)comPoint.read();

  // Exchange of more messages and responses.
  ...
  ...

  // Close the initiator ComPoint.
  comPoint.close();

and here is the corresponding code for the responder side:

  // Create the local address.
  ComPointAddress address = new ComPointAddress(protocol, port);

  // Open the server ComPoint.
  serverComPoint = ComManager.comPoint(COMPOINT_SERVER, address);

  // Accept the connection from the initiator, creating the responder ComPoint.
  ComPoint comPoint = serverComPoint.accept();

  // Receive the message.
  Message message = (Message)comPoint.read();

  // Send the response.
  Response response = new Response(...);
  comPoint.write(response);

  // Exchange of more messages and responses.
  ...
  ...

  // Close the responder ComPoint.
  comPoint.close();

  // Eventually close the server ComPoint.
  serverComPoint.close();

The only sequence constraint between the initiator and responder code executions is that the server ComPoint must have been opened before the initiator ComPoint. Message and Response are user defined classes implementing Streamable; refer to semper.util.serial.

Channels

Channel refines the communication services of ComPoint. It allows more than one pairs of modules to use a specific port number between two hosts, without the outstanding responder comPoints blocking each other. This is achieved through establishing channels between initiator and responder modules. A channel between two hosts is identified by a port number together with a correlator string. The initiator module requests a channel to a specific host with a specific port and correlator by invoking openInitiatorChannel , which returns an initiator ComPoint. If the responder module has already invoked openResponderChannel to indicate that it expects such a channel, then a responder ComPoint is returned to the responder module. Otherwise, the channel is queued at the host where the responder resides until the responder invokes the openResponderChannel method. Therefore, Channel not only provides multiplexing over individual port numbers, it also lets the responder module to act after the initiator module. Here is a sample code for the initiator side:

  // Create the address of the responder.
  ComPointAddress address = new ComPointAddress(protocol, host, port, path);

  // Open an initiator ComPoint and initiate a channel.
  ComPoint comPoint =
    Channel.openInitiatorChannel(address, options, correlator);

  // Send a message.
  String message = new Message(...);
  comPoint.write(message);

  // Receive a response.
  String response = (Response)comPoint.read();

  // Exchange of more messages and responses.
  ...
  ...

  // Close the ComPoint and channel.
  comPoint.close();

and here is the corresponding code for the responder:

  // Create the local address.
  ComPointAddress address = new ComPointAddress(protocol, port);

  // Start a service-point thread.
  ChannelServicePointThread servicePoint =
    Channel.startServicePointThread(address);

  // Accept a channel with a specific correlator and open a responder ComPoint.
  ComPoint comPoint =
    servicePoint.openResponderChannel(options, correlator);
  
  // Receive the message.
  String message = (Message)comPoint.read();

  // Send the response.
  String response = new Response(...);
  comPoint.write(response);

  // Exchange of more messages and responses.
  ...
  ...

  // Close the responder ComPoint.
  comPoint.close();

  // Eventually stop the service-point thread.
  servicePoint.stop();

The only sequence constraint between the initiator and responder code executions is that the service-point thread must have been started before the initiator opens the channel.

How to setup ComPointMail

In order to use ComPointMail, a mailcap should be set up such that whenever an e-mail is received from the remote ComPointMail, it is forwarded through ComPointMailReceiver to the local ComPointMail. The e-mails sent by ComPointMail have the mime content-type application/x-semper and are mime-base-64 encoded. For the local mail handler, a mailcap must be setup for this content-type. Whenever an e-mail with content-type application/x-semper, either automatically or by user clicking on an icon, ComPointMailReceiver is invoked on the content of the mail. As an example of what a mailcap which invokes ComPointMailReceiver looks like, for zmail on AIX, it is setup through the following attachment type:

ENCODE  application/x-semper      None
TYPE    application/x-semper   \
        "java semper.comm.ComPointMailReceiver '%s'&" \
	None \
	"SEMPER Message"
BITMAP  application/x-semper  ~/SEMPER/zmail/SEMPER.xbm

Also note that there should be a _sempconfig file in your home-directory or you have to go to whatever directory your config-file is in before invoking java in mailcap. The reason for this is that ComPointMailReceiver gets the receiverPort parameter from the config-file.

Configuration Parameters

The following are the configuration parameters of the communication block:

semper.comm.tcp.remoteTelnet -- the fully qualified remote telnet command. (this can be used if there is a customized telnet program which allows bridging firewalls in cases where this is not possible directly through java sockets. Note though that for SOCKS firewalls java itself IS socksified: set the properties 'socksProxyHost' and 'socksProxyPort' e.g as 'java -DsocksProxyHost=YOUR_SOCKS_GATEWAY -DsocksProxyPort=YOUR_SOCKS_GATEWAYS_PORT_NORMALY_1080 ....')
semper.comm.http.proxyHost -- http-proxy host.
semper.comm.http.proxyPort -- http-proxy port.
semper.comm.mail.receiverPort -- the port which ComPointMail may use to receive messages from ComPointMailReceiver, which runs on the same host; i.e., this port is used only locally.
semper.comm.mail.returnMailAddr -- return mail address for all the messages sent by ComPointMail.
semper.comm.mail.localMailServer -- the local host on which SMTP server runs.

Documentation

The following classes implement the ComPoint API:

ComPoint: provides a unified interface for accessing the underlying communication protocols.
ComManager provides the static methods for creating ComPoints; at initialization, it registers the protocol-specific ComPoints.
ComPointConstants defines constants for the ComPoint types, communication protocols, and service types.
ComPointAddress unifies the addressing across communication protocols and, like in URL, provides a field for identifying the protocol.
ComPointException is thrown in case of a ComPoint error.

The following classes implement the Channel API:

Channel provides static methods for starting service-point threads and opening initiator channels.
ChannelServicePointThread accepts requests for and captures channels for a specific port and correlator.
ChannelException is thrown in case of a Channel error.
ChannelTimeoutException is thrown in case of a timeout.

Changes

1/15/98 Change in ChannelServicePointThread.java and ChannelCleanerThread.java to support multiple pending initiator and responder requests with the same correlator. The following code is now legal:
```
C: i1 = Channel.openInitiatorChannel( Correlator_A);
C: i2 = Channel.openInitiatorChannel( Correlator_A);
S: r1 = spt.openResponderChannel( Correlator_A);
S: r2 = spt.openResponderChannel( Correlator_A);
```
where C denotes a client machine and S a server machine. The requests are served in a FIFO way. J.Brauckmann SRB