Siena (v.1.5.5) API documentation

siena.comm
Interface PacketReceiver

All Known Implementing Classes:
KAPacketReceiver, SSLPacketReceiver, TCPPacketReceiver, UDPPacketReceiver

public interface PacketReceiver

abstract packet receiver.

Encapsulates a passive acceptor of packets. This acceptor is passive in the sense that it uses the caller's thread to accept and assemble the incoming packet. PacketReceivers, together with their corresponding PacketSenders, form the communication layer underneath the distributed network of Siena components.

The implementations of Siena (see HierarchicalDispatcher and ThinClient) use a PacketReceiver as their acceptor of external subscriptions, notifications, etc.

See Also:
PacketSender

Method Summary
 byte[] address()
          external address for this receiver.
 int receive(byte[] packet)
          receives a packet in the given buffer.
 int receive(byte[] packet, long timeout)
          receives a packet in the given buffer, with the given timeout.
 void shutdown()
          closes the receiver.
 byte[] uri()
          Deprecated. since 1.4.0. Please use address() instead.
 

Method Detail

address

byte[] address()
external address for this receiver. An external address must allow other applications to contact this receiver. Every implementation of this interface must define an address format that is compatible (i.e., that does not conflict) with every other implementation. Notice also that every implementation of a PacketReceiver must have a corresponding PacketSender, and that PacketSenderFactory must understand its address to construct the corresponding PacketSender.

In order to allow separate implementations to share the same global address space, every implementation must be associated with a unique schema. A schema is simply an identifier for a specitic receiver/sender implementation. An external address must therefore have the following general syntax:
address ::= schema:schema-dependent-part
schema ::= a character string not containing the ":" character
schema-dependent-part ::= implementation-dependent part. Every implementation is free to define an appropriate syntax for this part of the address string.

See Also:
PacketSender, PacketSenderFactory

uri

byte[] uri()
Deprecated. since 1.4.0. Please use address() instead.

This method has been replaced by address(). The reason for this change is more conceptual than practical: the term "address" is more appropriate than the term "uri" because it provides a way to reach a PacketReceiver, rather than an identifier.


receive

int receive(byte[] packet)
            throws PacketReceiverException
receives a packet in the given buffer. This method must be reentrant. Siena clients and servers must be able to use several threads to receive packets from the same receiver.

Returns:
the number of bytes read into the buffer. The return value must not be negative. On error conditions, this method must throw an exception.
Throws:
PacketReceiverException - in case an error occurrs while reading.

receive

int receive(byte[] packet,
            long timeout)
            throws PacketReceiverException,
                   TimeoutExpired
receives a packet in the given buffer, with the given timeout. This method must be reentrant. Siena clients and servers must be able to use several threads to receive packets from the same receiver.

Returns:
the number of bytes read into the buffer. The return value must not be negative. On error conditions, this method must throw an exception.
Throws:
PacketReceiverException - in case an error occurrs while reading.
TimeoutExpired - in case the timout expires before a packet is available

shutdown

void shutdown()
              throws PacketReceiverException
closes the receiver.

Throws:
PacketReceiverException

Siena (v.1.5.5) API documentation

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