PacketReceiver (Siena 2.0.4 API Documentation)
Date: 2015-05-17

siena.comm

## Interface PacketReceiver

- All Known Implementing Classes:
    KAPacketReceiver, KAZipPacketReceiver, MultiPacketReceiver, 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. `PacketReceiver`s, together with their corresponding `PacketSender`s, 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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.

- - ### 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`

    - #### 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`

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