siena.comm (Siena 2.0.4 API Documentation)
Date: 2015-05-17

# Package siena.comm

Communication mechanisms used by Siena.

See: Description

- Interface Summary
  Interface | Description
  --- | ---
  PacketReceiver | abstract packet receiver.
  PacketReceiverFactory | creates PacketReceiver based on an external string representation.
  PacketSender | packet sender.
  PacketSenderFactory | creates PacketSenders based on the external address of their corresponding receivers.

- Class Summary
  Class | Description
  --- | ---
  GenericReceiverFactory | generic packet receiver factory.
  GenericSenderFactory | generic packet sender factory.
  KAPacketReceiver | receives packets through a TCP port.
  KAZipPacketReceiver |
  KAZipPacketSender |
  MultiPacketReceiver |
  SSLPacketReceiver | receives packets through an SSL connection.
  TCPPacketReceiver | receives packets through a TCP port.
  UDPPacketReceiver | receives packets through a UDP port.

- Exception Summary
  Exception | Description
  --- | ---
  InvalidReceiverException | invalid Siena receiver handler.
  InvalidSenderException | invalid Siena handler.
  PacketReceiverClosed | packet receiver has been closed
  PacketReceiverException | generic exception occurring when receiving packets
  PacketReceiverFatalError | fatal error in packet receiver
  PacketSenderException | generic error in sending packets
  TimeoutExpired | a timeout has expired during Siena operations

## Package siena.comm Description

Communication mechanisms used by Siena.

### Basic Communication in Siena

The basis for communication between Siena components is a generic, uni-directional, point-to-point, packet-based communication service. In essence, this mechanism is an abstraction of a datagram link between two components. A link is defined by the `PacketSender` and `PacketReceiver` interfaces, representing the sender's and receiver's ends respectively.

As a first step in establishing a communication link, a receiver creates a `PacketReceiver` object. Once a `PacketReceiver` is active, a sender can create a corresponding `PacketSender` object to send packets to the receiver. `PacketSender` objects are created idirectly through `PacketSenderFactory`, using the receiver's `external address`.

An external address of a `PacketReceiver` is a byte string that serves as a universal locator for that receiver. The space of external addresses is obviously shared by all link types and implementations. Therefore, in order to partition the address space, an external address must comply with the following syntax:

address ::= schema`:`schema-dependent-part

Where schema is a short string, not containing the `":"` (colon) charachter, that uniquely identifies the type of receiver, and schema-dependent-part is another string whose format is specific to that type of receiver.

The current implementation of Siena provides three sender/receiver implementation pairs:

- `KAPacketSender`/`KAPacketReceiver`: schema identifier `"ka"`. Sends packets through TCP connections. This sender/receiver pair attempts to maintain and reuse persistent TCP connections ("KA" stands for keep alive).
- `TCPPacketSender`/`TCPPacketReceiver`: schema identifier `"tcp"`. sends packets through TCP connections. This sender/receiver pair uses one connection per packet.
- `UDPPacketSender`/`UDPPacketReceiver`: schema identifier `"udp"`. Sends packets using UDP datagrams.
- `SSLPacketSender`/`SSLPacketReceiver`: schema identifier `"ssl"`. Sends packets through persistent ssl connections. This sender/receiver pair attempts to maintain and reuse SSL connections.

### Extending the Communication Capabilities of Siena

Siena can be easily extended with new packet sender/receiver implementation pairs. For example, a developer may want to implement a communication mechanism that uses, say, an infra-red port. In order to do that, the developer must:

1. choose a globally unique schema identifier, for example `"ir"`.
2. provide a pair of specific implementations of `PacketReceiver` and `PacketSender` that make use of the infra-red port. For example, these could be called `org.xyz.IRPacketReceiver` and `org.xyz.IRPacketSender`.
3. provide a specific sender factory, say `org.xyz.IRSenderFactory`, to be used directly by applications, or indirectly through the `factory registration` feature of `GenericSenderFactory`.

Copyright © 2000-2005 University of Colorado.
Copyright © 2005-2011 Antonio Carzaniga.
This documentation is maintained by Antonio Carzaniga