net.i2p.sam

## Class SAMStreamSession

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

- Direct Known Subclasses:
    SAMv2StreamSession, SAMv3StreamSession

      public class SAMStreamSession
      extends Object

  SAM STREAM session class.
  Author:
    human

- - ### 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 class` | `SAMStreamSession.StreamSender` Lets us push data through the stream without blocking, (even after exceeding the I2PSocket's buffer)
    `protected class` | `SAMStreamSession.v1StreamSender`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `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
    Constructor and Description
    `SAMStreamSession()`
    `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

    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.
    `protected SAMStreamSession.SAMStreamSessionSocketReader` | `getSocketReader(int id)` Get a SAM STREAM session socket handler.
    `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.
    `(package private) boolean` | `setReceiveLimit(int id, long limit, boolean nolimit)`

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

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

- - ### Field Detail

    - #### SOCKET_HANDLER_BUF_SIZE

          protected static final int SOCKET_HANDLER_BUF_SIZE

      See Also:
        Constant Field Values

    - #### recv

          protected SAMStreamReceiver recv

    - #### server

          protected SAMStreamSession.SAMStreamSessionServer server

    - #### socketMgr

          protected I2PSocketManager socketMgr

    - #### canCreate

          protected boolean canCreate

    - #### forceFlush

          protected 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 String PROP_FORCE_FLUSH

    - #### DEFAULT_FORCE_FLUSH

          public static String DEFAULT_FORCE_FLUSH

  - ### Constructor Detail

    - #### SAMStreamSession

          public SAMStreamSession()

    - #### SAMStreamSession

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

      Create a new SAM STREAM session.
      Parameters:
        `dest` - Base64-encoded destination (private key)
        `dir` - Session direction ("RECEIVE", "CREATE" or "BOTH")
        `props` - Properties to setup the I2P session
        `recv` - Object that will receive incoming data
      Throws:
        `IOException`
        `DataFormatException`
        `SAMException`

    - #### SAMStreamSession

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

      Create a new SAM STREAM session.
      Parameters:
        `destStream` - Input stream containing the destination keys
        `dir` - Session direction ("RECEIVE", "CREATE" or "BOTH")
        `props` - Properties to setup the I2P session
        `recv` - Object that will receive incoming data
      Throws:
        `IOException`
        `DataFormatException`
        `SAMException`

  - ### Method Detail

    - #### getDestination

          public Destination getDestination()

      Get the SAM STREAM session Destination.
      Returns:
        The SAM STREAM session Destination.

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

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

    - #### close

          public void close()

      Close a SAM STREAM session.

    - #### closeConnection

          public boolean closeConnection(int id)

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

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

    - #### getSocketReader

          protected SAMStreamSession.SAMStreamSessionSocketReader getSocketReader(int id)

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

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

    - #### removeSocketHandler

          protected void removeSocketHandler(int id)

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

    - #### setReceiveLimit

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

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