net.i2p.sam

## Class SAMMessageSession

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

- All Implemented Interfaces:
    Closeable, AutoCloseable, SAMMessageSess
  Direct Known Subclasses:
    SAMDatagramSession, SAMRawSession

      abstract class SAMMessageSession
      extends Object
      implements SAMMessageSess

  Base abstract class for SAM message-based sessions.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `_isOwnSession`
    `protected Log` | `_log`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `SAMMessageSession(I2PSession sess, int listenProtocol, int listenPort)` Initialize a new SAM message-based session using an existing I2PSession.
    `protected` | `SAMMessageSession(InputStream destStream, Properties props)` Initialize a new SAM message-based session.
    `protected` | `SAMMessageSession(String dest, Properties props)` Initialize a new SAM message-based session.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `close()` Close a SAM message-based session.
    `Destination` | `getDestination()` Get the SAM message-based session Destination.
    `protected I2PSession` | `getI2PSession()` Get the I2PSession object used by the SAM message-based session.
    `int` | `getListenPort()`
    `int` | `getListenProtocol()`
    `protected abstract void` | `messageReceived(byte[] msg, int proto, int fromPort, int toPort)` Handle a new received message
    `abstract boolean` | `sendBytes(String dest, byte[] data, int proto, int fromPort, int toPort)` Send bytes through a SAM message-based session.
    `protected boolean` | `sendBytesThroughMessageSession(String dest, byte[] data, int proto, int fromPort, int toPort)` Actually send bytes through the SAM message-based session I2PSession (er...).
    `protected boolean` | `sendBytesThroughMessageSession(String dest, byte[] data, int proto, int fromPort, int toPort, boolean sendLeaseSet, int sendTags, int tagThreshold, int expiration)` Actually send bytes through the SAM message-based session I2PSession, using per-message extended options.
    `protected abstract void` | `shutDown()` Do whatever is needed to shutdown the SAM session
    `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`

    - ### Methods inherited from interface net.i2p.sam.SAMMessageSess

      `sendBytes`

- - ### Field Detail

    - #### _isOwnSession

          protected final boolean _isOwnSession

    - #### _log

          protected final Log _log

  - ### Constructor Detail

    - #### SAMMessageSession

          protected SAMMessageSession(I2PSession sess,
                                      int listenProtocol,
                                      int listenPort)
                               throws IOException,
                                      DataFormatException,
                                      I2PSessionException

      Initialize a new SAM message-based session using an existing I2PSession.
      Throws:
        `IOException`
        `DataFormatException`
        `I2PSessionException`

    - #### SAMMessageSession

          protected SAMMessageSession(InputStream destStream,
                                      Properties props)
                               throws IOException,
                                      DataFormatException,
                                      I2PSessionException

      Initialize a new SAM message-based session.
      Parameters:
        `destStream` - Input stream containing the binary destination and private keys, and optional offline signature section (same format as PrivateKeyFile)
        `props` - Properties to setup the I2P session
      Throws:
        `IOException`
        `DataFormatException`
        `I2PSessionException`

    - #### SAMMessageSession

          protected SAMMessageSession(String dest,
                                      Properties props)
                               throws IOException,
                                      DataFormatException,
                                      I2PSessionException

      Initialize a new SAM message-based session.
      Parameters:
        `dest` - Base64-encoded destination and private keys, and optional offline signature section (same format as PrivateKeyFile)
        `props` - Properties to setup the I2P session
      Throws:
        `IOException`
        `DataFormatException`
        `I2PSessionException`

  - ### Method Detail

    - #### close

          public void close()

      Close a SAM message-based session.
      Specified by:
        `close` in interface `Closeable`
      Specified by:
        `close` in interface `AutoCloseable`
      Specified by:
        `close` in interface `SAMMessageSess`

    - #### getDestination

          public Destination getDestination()

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

    - #### getI2PSession

          protected I2PSession getI2PSession()

      Get the I2PSession object used by the SAM message-based session.
      Returns:
        The I2PSession of the SAM message-based session

    - #### getListenPort

          public int getListenPort()

      Specified by:
        `getListenPort` in interface `SAMMessageSess`

    - #### getListenProtocol

          public int getListenProtocol()

      Specified by:
        `getListenProtocol` in interface `SAMMessageSess`

    - #### messageReceived

          protected abstract void messageReceived(byte[] msg,
                                                  int proto,
                                                  int fromPort,
                                                  int toPort)

      Handle a new received message
      Parameters:
        `msg` - Message payload

    - #### sendBytes

          public abstract boolean sendBytes(String dest,
                                            byte[] data,
                                            int proto,
                                            int fromPort,
                                            int toPort)
                                     throws DataFormatException,
                                            I2PSessionException

      Send bytes through a SAM message-based session.
      Specified by:
        `sendBytes` in interface `SAMMessageSess`
      Parameters:
        `dest` - Destination
        `data` - Bytes to be sent
      Returns:
        True if the data was sent, false otherwise
      Throws:
        `DataFormatException` - on unknown / bad dest
        `I2PSessionException` - on serious error, probably session closed

    - #### sendBytesThroughMessageSession

          protected boolean sendBytesThroughMessageSession(String dest,
                                                           byte[] data,
                                                           int proto,
                                                           int fromPort,
                                                           int toPort)
                                                    throws DataFormatException,
                                                           I2PSessionException

      Actually send bytes through the SAM message-based session I2PSession (er...).
      Parameters:
        `dest` - Destination
        `data` - Bytes to be sent
        `proto` - I2CP protocol
        `fromPort` - I2CP from port
        `toPort` - I2CP to port
      Returns:
        True if the data was sent, false otherwise
      Throws:
        `DataFormatException` - on unknown / bad dest
        `I2PSessionException` - on serious error, probably session closed

    - #### sendBytesThroughMessageSession

          protected boolean sendBytesThroughMessageSession(String dest,
                                                           byte[] data,
                                                           int proto,
                                                           int fromPort,
                                                           int toPort,
                                                           boolean sendLeaseSet,
                                                           int sendTags,
                                                           int tagThreshold,
                                                           int expiration)
                                                    throws DataFormatException,
                                                           I2PSessionException

      Actually send bytes through the SAM message-based session I2PSession, using per-message extended options. For efficiency, use the method without all the extra options if they are all defaults.
      Parameters:
        `dest` - Destination
        `data` - Bytes to be sent
        `proto` - I2CP protocol
        `fromPort` - I2CP from port
        `toPort` - I2CP to port
        `sendLeaseSet` - true is the usual setting and the I2CP default
        `sendTags` - 0 to leave as default
        `tagThreshold` - 0 to leave as default
        `expiration` - SECONDS from now, NOT absolute time, 0 to leave as default
      Returns:
        True if the data was sent, false otherwise
      Throws:
        `DataFormatException` - on unknown / bad dest
        `I2PSessionException` - on serious error, probably session closed

    - #### shutDown

          protected abstract void shutDown()

      Do whatever is needed to shutdown the SAM session

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