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

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 messsage 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 a ComPointMailConfig.txt is present. Otherwise, the mail protocol may not be used. The ComPointMailConfig.txt contains two values: a receiver port which is used by the ComPointMailReceiver to forward the mime-decoded messages from the mail handler to the ComPointMail; and a return mail address to which responses may be sent.

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.

The implementation of the ComPoint on the mail protocol requires a receiver port. Currently, this port is defined to be 11432. When the initialization of the communication block is modified to use the preference manager, this port will be specified by the configuration file.

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

Documentation

The following classes implement the ComPoint API:

The following classes implement the Channel API: