NIOSocket (Naga API)
Date: 2016-06-28

naga

## Interface NIOSocket

- All Superinterfaces:
    NIOAbstractSocket
  All Known Subinterfaces:
    NIOSocketSSL

      public interface NIOSocket
      extends NIOAbstractSocket

  Interface for the NIOSocket, which is an asynchronous facade to an underlying Socket.

  The NIOSocket executes callbacks to a Socket observer to react to incoming packets and other events.

  Author:
    Christoffer Lerno

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `closeAfterWrite()` Causes the socket to close after writing the current entries in the queue (consequent entries will be thrown away).
    `long` | `getBytesRead()` Return the total number of bytes read on this socket since it was opened.
    `long` | `getBytesWritten()` Return the total number of bytes written on this socket since it was opened.
    `int` | `getMaxQueueSize()` The current maximum queue size in bytes.
    `long` | `getTimeOpen()` Return the time this socket has been open.
    `long` | `getWriteQueueSize()` This method returns the number of bytes queued for dispatch.
    `void` | `listen(SocketObserver socketObserver)` Opens the socket for reads.
    `void` | `queue(java.lang.Runnable runnable)` Queue a runnable in the packet queue.
    `void` | `setMaxQueueSize(int maxQueueSize)` Sets the maximum number of bytes allowed in the queue for this socket.
    `void` | `setPacketReader(PacketReader packetReader)` Sets the packet reader for this socket.
    `void` | `setPacketWriter(PacketWriter packetWriter)` Sets the packet writer for this socket.
    `java.net.Socket` | `socket()` Allows access to the underlying socket.
    `boolean` | `write(byte[] packet)` Write a packet of bytes asynchronously on this socket.
    `boolean` | `write(byte[] packet, java.lang.Object tag)` Write a packet of bytes asynchronously on this socket.

    - ### Methods inherited from interface naga.NIOAbstractSocket

      `close, getAddress, getIp, getPort, getTag, isOpen, setTag`

- - ### Method Detail

    - #### write

          boolean write(byte[] packet)

      Write a packet of bytes asynchronously on this socket.

      The bytes will be sent to the PacketWriter belonging to this socket for dispatch. However, if the queue is full (i.e. the new queue size would exceed `getMaxQueueSize()`), the packet is discarded and the method returns false.

      This method is thread-safe.

      Parameters:
        `packet` - the packet to send.
      Returns:
        true if the packet was queued, false if the queue limit was reached and the packet was thrown away.

    - #### write

          boolean write(byte[] packet,
                      java.lang.Object tag)

      Write a packet of bytes asynchronously on this socket.

      The bytes will be sent to the PacketWriter belonging to this socket for dispatch. However, if the queue is full (i.e. the new queue size would exceed `getMaxQueueSize()`), the packet is discarded and the method returns false.

      This method is thread-safe.

      Parameters:
        `packet` - the packet to send.
        `tag` - an optional tag to tag the packet (used in `SocketObserver.packetSent(NIOSocket, Object)`).
      Returns:
        true if the packet was queued, false if the queue limit was reached and the packet was thrown away.

    - #### queue

          void queue(java.lang.Runnable runnable)

      Queue a runnable in the packet queue. This runnable will execute after the latest packet in the queue is sent.

      This method is thread-safe.

      Parameters:
        `runnable` - the runnable to queue.

    - #### getBytesRead

          long getBytesRead()

      Return the total number of bytes read on this socket since it was opened.

      This method is thread-safe.

      Returns:
        the total number of bytes read on this socket.

    - #### getBytesWritten

          long getBytesWritten()

      Return the total number of bytes written on this socket since it was opened.

      This method is thread-safe.

      Returns:
        the total number of bytes written on this socket.

    - #### getTimeOpen

          long getTimeOpen()

      Return the time this socket has been open.

      This method is thread-safe.

      Returns:
        the time this socket has been open in ms.

    - #### getWriteQueueSize

          long getWriteQueueSize()

      This method returns the number of bytes queued for dispatch. This size is compared against the maximum queue size to determine if additional packets will be refused or not.

      However, this number does not include the packet currently waiting to be written.

      This method is thread-safe.

      Returns:
        the total size of the packets waiting to be dispatched, exluding the currently dispatching packet.

    - #### getMaxQueueSize

          int getMaxQueueSize()

      The current maximum queue size in bytes.

      This method is thread-safe.

      Returns:
        the current maximum queue size.

    - #### setMaxQueueSize

          void setMaxQueueSize(int maxQueueSize)

      Sets the maximum number of bytes allowed in the queue for this socket. If this number is less than 1, the queue is unbounded.

      This method is thread-safe.

      Parameters:
        `maxQueueSize` - the new max queue size. A value less than 1 is an unbounded queue.

    - #### setPacketReader

          void setPacketReader(PacketReader packetReader)

      Sets the packet reader for this socket.
      Parameters:
        `packetReader` - the packet reader to interpret the incoming byte stream.

    - #### setPacketWriter

          void setPacketWriter(PacketWriter packetWriter)

      Sets the packet writer for this socket.

      This method is thread-safe and all packets posted before the writer is changed is guaranteed to be serialized using the previous writer.

      Parameters:
        `packetWriter` - the packet writer to interpret the incoming byte stream.

    - #### listen

          void listen(SocketObserver socketObserver)

      Opens the socket for reads.

      The socket observer will receive connects, disconnects and packets. If the socket was opened or disconnected before the observer was attached, the socket observer will still receive those callbacks.

      This method is thread-safe, but may only be called once.

      Parameters:
        `socketObserver` - the observer to receive packets and be notified of connects/disconnects.
      Throws:
        `java.lang.IllegalStateException` - if the method already has been called.

    - #### closeAfterWrite

          void closeAfterWrite()

      Causes the socket to close after writing the current entries in the queue (consequent entries will be thrown away).

      Also see `close()` if you want to immediately close the socket.

      This method is thread-safe.

    - #### socket

          java.net.Socket socket()

      Allows access to the underlying socket.

      Note that accessing streams or closing the socket will put this NIOSocket in an undefined state

      Returns:
        return the underlying socket.