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

siena.comm

## Class KAPacketReceiver

- java.lang.Object
- - siena.comm.KAPacketReceiver

- All Implemented Interfaces:
    PacketReceiver
  Direct Known Subclasses:
    KAZipPacketReceiver, SSLPacketReceiver

      public class KAPacketReceiver
      extends java.lang.Object
      implements PacketReceiver

  receives packets through a TCP port. Uses persistent TCP connections to receive one or more packets.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `AcceptPollingInterval` controls the accept-close workaround.
    `static int` | `DefaultMaxActiveConnections` default limit for active connections.
    `static int` | `DefaultPort`
    `static int` | `DefaultReceiveTimeout` default value for the receive timeout.
    `int` | `receive_timeout` limits the duration of blocking input when receiving packets.
    `static java.lang.String` | `Schema`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `KAPacketReceiver()` creates a receiver listening to the a random port.
    `KAPacketReceiver(int port_number)` creates a receiver listening to the given port.
    `KAPacketReceiver(int port_number, int qsize)` creates a receiver listening to the given port with a given maximum queue for TCP connections.
    `KAPacketReceiver(java.net.ServerSocket s)` creates a receiver listening to the given port.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `byte[]` | `address()` external address of this packet receiver.
    `protected static java.net.InetAddress` | `guessMyIPAddress()`
    `protected static java.net.InetAddress` | `guessMyIPAddress(java.net.DatagramSocket s)`
    `protected static java.net.InetAddress` | `guessMyIPAddress(java.net.ServerSocket s)`
    `int` | `receive(byte[] buf)` receives a packet in the given buffer.
    `int` | `receive(byte[] buf, long timeout)` not yet implemented.
    `static int` | `receive(java.net.Socket sock, byte[] buf)`
    `void` | `setHostName(java.lang.String hostname)` explicitly sets the address of this packet receiver.
    `void` | `setMaxActiveConnections(int m)` limits the number of active connections.
    `void` | `shutdown()` closes the receiver.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface siena.comm.PacketReceiver

      `address`

- - ### Field Detail

    - #### Schema

          public static final java.lang.String Schema

      See Also:
        Constant Field Values

    - #### DefaultPort

          public static final int DefaultPort

      See Also:
        Constant Field Values

    - #### AcceptPollingInterval

          public static int AcceptPollingInterval

      controls the accept-close workaround. See `TCPPacketReceiver.AcceptPollingInterval` for an explanation of this parameter.

    - #### DefaultReceiveTimeout

          public static int DefaultReceiveTimeout

      default value for the receive timeout.
      See Also:
        `receive_timeout`

    - #### receive_timeout

          public int receive_timeout

      limits the duration of blocking input when receiving packets. A positive value defines a timeout for receive operations for this receiver. This parameter affects new connections only. A value <=0 means infinite timeout.

    - #### DefaultMaxActiveConnections

          public static int DefaultMaxActiveConnections

      default limit for active connections.
      See Also:
        `setMaxActiveConnections(int)`

  - ### Constructor Detail

    - #### KAPacketReceiver

          public KAPacketReceiver()
                           throws java.io.IOException

      creates a receiver listening to the a random port.
      Throws:
        `java.io.IOException` - if an I/O error occurs when opening the socket port.

    - #### KAPacketReceiver

          public KAPacketReceiver(int port_number)
                           throws java.io.IOException

      creates a receiver listening to the given port.
      Parameters:
        `port_number` - must be a valid TCP port number, or it can be 0 in which case a random port is used
      Throws:
        `java.io.IOException` - if an I/O error occurs when opening the socket. typically, when the given port is already in use.

    - #### KAPacketReceiver

          public KAPacketReceiver(int port_number,
                          int qsize)
                           throws java.io.IOException

      creates a receiver listening to the given port with a given maximum queue for TCP connections.
      Parameters:
        `port_number` - must be a valid TCP port number, or it can be 0 in which case a random port is used
      Throws:
        `java.io.IOException` - if an I/O error occurs when opening the socket. typically, when the given port is already in use.

    - #### KAPacketReceiver

          public KAPacketReceiver(java.net.ServerSocket s)
                           throws java.io.IOException

      creates a receiver listening to the given port.
      Parameters:
        `s` - server socket used to accept connections.
      Throws:
        `java.net.UnknownHostException` - if an error occurrs while resolving the hostname for this host.
        `java.io.IOException`

  - ### Method Detail

    - #### setMaxActiveConnections

          public void setMaxActiveConnections(int m)

      limits the number of active connections. This receiver will maintain at most `m` active connections. If a new connection is accepted when `m` connections are active, the new accepted connections will replace the oldest active connection.

      When the limit is lowered and x > m connections are active, the oldest x - m connections are closed.

    - #### setHostName

          public void setHostName(java.lang.String hostname)

      explicitly sets the address of this packet receiver. This method allows users to set the host name or IP address that this receiver advertises as its externally-visible address. This might be necessary in the cases in which the Java VM can not reliably figure out such an address by itself.

    - #### receive

          public int receive(byte[] buf)
                      throws PacketReceiverException

      Description copied from interface: `PacketReceiver`
      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.
      Specified by:
        `receive` in interface `PacketReceiver`
      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

          public int receive(byte[] buf,
                    long timeout)

      not yet implemented.
      Specified by:
        `receive` in interface `PacketReceiver`
      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.

    - #### shutdown

          public void shutdown()
                        throws PacketReceiverException

      Description copied from interface: `PacketReceiver`
      closes the receiver.
      Specified by:
        `shutdown` in interface `PacketReceiver`
      Throws:
        `PacketReceiverException`

    - #### receive

          public static int receive(java.net.Socket sock,
                    byte[] buf)
                             throws java.lang.InterruptedException,
                                    java.io.IOException

      Throws:
        `java.lang.InterruptedException`
        `java.io.IOException`

    - #### address

          public byte[] address()

      external address of this packet receiver. Uses the following schema syntax:
      schema`:`host`:`port
      See Also:
        `PacketReceiver.address()`

    - #### guessMyIPAddress

          protected static java.net.InetAddress guessMyIPAddress()
                                                          throws java.net.UnknownHostException

      Throws:
        `java.net.UnknownHostException`

    - #### guessMyIPAddress

          protected static java.net.InetAddress guessMyIPAddress(java.net.ServerSocket s)
                                                          throws java.net.UnknownHostException

      Throws:
        `java.net.UnknownHostException`

    - #### guessMyIPAddress

          protected static java.net.InetAddress guessMyIPAddress(java.net.DatagramSocket s)
                                                          throws java.net.UnknownHostException

      Throws:
        `java.net.UnknownHostException`

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