net.i2p.sam

## Class SAMStreamSession

- java.lang.Object
- - net.i2p.sam.SAMStreamSession

- All Implemented Interfaces:
    Closeable, AutoCloseable, SAMMessageSess
  Direct Known Subclasses:
    SAMv2StreamSession, SAMv3StreamSession

      class SAMStreamSession
      extends Object
      implements SAMMessageSess

  SAM STREAM session class.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected class` | `SAMStreamSession.DisconnectListener`
    `class` | `SAMStreamSession.SAMStreamSessionServer` SAM STREAM session server, running in its own thread.
    `class` | `SAMStreamSession.SAMStreamSessionSocketReader` SAM STREAM socket reader, running in its own thread.
    `class` | `SAMStreamSession.SAMv1StreamSessionSocketReader`
    `protected static class` | `SAMStreamSession.StreamSender` Lets us push data through the stream without blocking, (even after exceeding the I2PSocket's buffer)

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `_isOwnSession`
    `protected Log` | `_log`
    `protected boolean` | `canCreate`
    `static String` | `DEFAULT_FORCE_FLUSH`
    `protected boolean` | `forceFlush` should we flush every time we get a STREAM SEND, or leave that up to the streaming lib to decide?
    `static String` | `PROP_FORCE_FLUSH`
    `protected SAMStreamReceiver` | `recv`
    `protected SAMStreamSession.SAMStreamSessionServer` | `server`
    `protected static int` | `SOCKET_HANDLER_BUF_SIZE`
    `protected I2PSocketManager` | `socketMgr`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SAMStreamSession(I2PSocketManager mgr, Properties props, SAMStreamReceiver recv, int listenport)` Create a new SAM STREAM session on an existing socket manager.
    `protected` | `SAMStreamSession(InputStream destStream, String dir, Properties props, SAMStreamReceiver recv)` Create a new SAM STREAM session.
    `` | `SAMStreamSession(String dest, String dir, Properties props, SAMStreamReceiver recv)` Create a new SAM STREAM session.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected boolean` | `checkSocketHandlerId(int id)` Check whether a SAM STREAM session socket handler id is still in use.
    `void` | `close()` Close a SAM STREAM session.
    `boolean` | `closeConnection(int id)` Close a connection managed by the SAM STREAM session.
    `boolean` | `connect(int id, String dest, Properties props)` Connect the SAM STREAM session to the specified Destination
    `protected int` | `createSocketHandler(I2PSocket s, int id)` Create a new SAM STREAM session socket handler, detaching its thread.
    `Destination` | `getDestination()` Get the SAM STREAM session Destination.
    `int` | `getListenPort()`
    `int` | `getListenProtocol()`
    `protected SAMStreamSession.SAMStreamSessionSocketReader` | `getSocketReader(int id)` Get a SAM STREAM session socket handler.
    `boolean` | `isDestroyed()` Is the underlying streaming socket manager destroyed?
    `protected SAMStreamSession.SAMStreamSessionSocketReader` | `newSAMStreamSessionSocketReader(I2PSocket s, int id)`
    `protected SAMStreamSession.StreamSender` | `newStreamSender(I2PSocket s, int id)`
    `protected void` | `removeSocketHandler(int id)` Remove and gracefully close a SAM STREAM session socket handler.
    `boolean` | `sendBytes(int id, InputStream in, int size)` Send bytes through a SAM STREAM session.
    `boolean` | `sendBytes(String s, byte[] b, int pr, int fp, int tp)` Unsupported
    `boolean` | `sendBytes(String s, byte[] b, int pr, int fp, int tp, boolean sendLeaseSet, int sendTags, int tagThreshold, int expiration)` Unsupported
    `(package private) boolean` | `setReceiveLimit(int id, long limit, boolean nolimit)`
    `void` | `start()` Start a SAM message-based session.

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

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

- - ### Field Detail

    - #### _isOwnSession

          protected final boolean _isOwnSession

    - #### _log

          protected final Log _log

    - #### canCreate

          protected final boolean canCreate

    - #### DEFAULT_FORCE_FLUSH

          public static final String DEFAULT_FORCE_FLUSH

      See Also:
        Constant Field Values

    - #### forceFlush

          protected final boolean forceFlush

      should we flush every time we get a STREAM SEND, or leave that up to the streaming lib to decide?

    - #### PROP_FORCE_FLUSH

          public static final String PROP_FORCE_FLUSH

      See Also:
        Constant Field Values

    - #### recv

          protected final SAMStreamReceiver recv

    - #### server

          protected final SAMStreamSession.SAMStreamSessionServer server

    - #### SOCKET_HANDLER_BUF_SIZE

          protected static final int SOCKET_HANDLER_BUF_SIZE

      See Also:
        Constant Field Values

    - #### socketMgr

          protected final I2PSocketManager socketMgr

  - ### Constructor Detail

    - #### SAMStreamSession

          protected SAMStreamSession(I2PSocketManager mgr,
                                     Properties props,
                                     SAMStreamReceiver recv,
                                     int listenport)
                              throws IOException,
                                     DataFormatException,
                                     SAMException

      Create a new SAM STREAM session on an existing socket manager. v3 only.
      Parameters:
        `props` - Properties to setup the I2P session
        `recv` - Object that will receive incoming data
      Throws:
        `IOException`
        `DataFormatException`
        `SAMException`

    - #### SAMStreamSession

          protected SAMStreamSession(InputStream destStream,
                                     String dir,
                                     Properties props,
                                     SAMStreamReceiver recv)
                              throws IOException,
                                     DataFormatException,
                                     SAMException

      Create a new SAM STREAM session. Caller MUST call start().
      Parameters:
        `destStream` - Input stream containing the binary destination and private keys, and optional offline signature section (same format as PrivateKeyFile)
        `dir` - Session direction ("RECEIVE", "CREATE" or "BOTH") or "__v3__" if extended by SAMv3StreamSession
        `props` - Properties to setup the I2P session
        `recv` - Object that will receive incoming data
      Throws:
        `IOException`
        `DataFormatException`
        `SAMException`

    - #### SAMStreamSession

          public SAMStreamSession(String dest,
                                  String dir,
                                  Properties props,
                                  SAMStreamReceiver recv)
                           throws IOException,
                                  DataFormatException,
                                  SAMException

      Create a new SAM STREAM session. Caller MUST call start().
      Parameters:
        `dest` - Base64-encoded destination and private keys, and optional offline signature section (same format as PrivateKeyFile)
        `dir` - Session direction ("RECEIVE", "CREATE" or "BOTH") or "__v3__" if extended by SAMv3StreamSession
        `props` - Properties to setup the I2P session
        `recv` - Object that will receive incoming data
      Throws:
        `IOException`
        `DataFormatException`
        `SAMException`

  - ### Method Detail

    - #### checkSocketHandlerId

          protected boolean checkSocketHandlerId(int id)

      Check whether a SAM STREAM session socket handler id is still in use.
      Parameters:
        `id` - Handler id
      Returns:
        True if in use

    - #### close

          public void close()

      Close a SAM STREAM session.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `SAMMessageSess`

    - #### closeConnection

          public boolean closeConnection(int id)

      Close a connection managed by the SAM STREAM session.
      Parameters:
        `id` - Connection id
      Returns:
        true on success

    - #### connect

          public boolean connect(int id,
                                 String dest,
                                 Properties props)
                          throws I2PException,
                                 ConnectException,
                                 NoRouteToHostException,
                                 DataFormatException,
                                 InterruptedIOException,
                                 SAMInvalidDirectionException,
                                 IOException

      Connect the SAM STREAM session to the specified Destination
      Parameters:
        `id` - Unique id for the connection
        `dest` - Base64-encoded Destination to connect to
        `props` - Options to be used for connection
      Returns:
        true if successful
      Throws:
        `DataFormatException` - if the destination is not valid
        `SAMInvalidDirectionException` - if trying to connect through a receive-only session
        `ConnectException` - if the destination refuses connections
        `NoRouteToHostException` - if the destination can't be reached
        `InterruptedIOException` - if the connection timeouts
        `I2PException` - if there's another I2P-related error
        `IOException`

    - #### createSocketHandler

          protected int createSocketHandler(I2PSocket s,
                                            int id)

      Create a new SAM STREAM session socket handler, detaching its thread.
      Parameters:
        `s` - Socket to be handled
        `id` - Socket id, or 0 if it must be auto-generated
      Returns:
        An id associated to the socket handler

    - #### getDestination

          public Destination getDestination()

      Get the SAM STREAM session Destination.
      Specified by:
        `getDestination` in interface `SAMMessageSess`
      Returns:
        The SAM STREAM session Destination.

    - #### getListenPort

          public int getListenPort()

      Specified by:
        `getListenPort` in interface `SAMMessageSess`

    - #### getListenProtocol

          public int getListenProtocol()

      Specified by:
        `getListenProtocol` in interface `SAMMessageSess`

    - #### getSocketReader

          protected SAMStreamSession.SAMStreamSessionSocketReader getSocketReader(int id)

      Get a SAM STREAM session socket handler.
      Parameters:
        `id` - Handler id
      Returns:
        SAM StreamSender handler

    - #### isDestroyed

          public boolean isDestroyed()

      Is the underlying streaming socket manager destroyed?

    - #### newSAMStreamSessionSocketReader

          protected SAMStreamSession.SAMStreamSessionSocketReader newSAMStreamSessionSocketReader(I2PSocket s,
                                                                                                  int id)
                                                                                           throws IOException

      Throws:
        `IOException`

    - #### newStreamSender

          protected SAMStreamSession.StreamSender newStreamSender(I2PSocket s,
                                                                  int id)
                                                           throws IOException

      Throws:
        `IOException`

    - #### removeSocketHandler

          protected void removeSocketHandler(int id)

      Remove and gracefully close a SAM STREAM session socket handler.
      Parameters:
        `id` - Handler id to be removed

    - #### sendBytes

          public boolean sendBytes(int id,
                                   InputStream in,
                                   int size)
                            throws IOException

      Send bytes through a SAM STREAM session.
      Parameters:
        `id` - Stream Id
        `in` - Datastream input
        `size` - Count of bytes to send
      Returns:
        True if the data was queued for sending, false otherwise
      Throws:
        `IOException`

    - #### sendBytes

          public boolean sendBytes(String s,
                                   byte[] b,
                                   int pr,
                                   int fp,
                                   int tp)
                            throws I2PSessionException

      Unsupported
      Specified by:
        `sendBytes` in interface `SAMMessageSess`
      Parameters:
        `s` - Destination
        `b` - Bytes to be sent
      Returns:
        True if the data was sent, false otherwise
      Throws:
        `I2PSessionException` - always

    - #### sendBytes

          public boolean sendBytes(String s,
                                   byte[] b,
                                   int pr,
                                   int fp,
                                   int tp,
                                   boolean sendLeaseSet,
                                   int sendTags,
                                   int tagThreshold,
                                   int expiration)
                            throws I2PSessionException

      Unsupported
      Specified by:
        `sendBytes` in interface `SAMMessageSess`
      Throws:
        `I2PSessionException` - always

    - #### setReceiveLimit

          boolean setReceiveLimit(int id,
                                  long limit,
                                  boolean nolimit)

    - #### start

          public void start()

      Description copied from interface: `SAMMessageSess`
      Start a SAM message-based session. MUST be called after constructor.
      Specified by:
        `start` in interface `SAMMessageSess`