net.i2p.sam

## Class SAMBridge

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

- All Implemented Interfaces:
    Runnable, ClientApp

      public class SAMBridge
      extends Object
      implements Runnable, ClientApp

  SAM bridge implementation. This is the main entry point for SAM.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static String` | `DEFAULT_DATAGRAM_HOST`
    `protected static String` | `DEFAULT_DATAGRAM_PORT`
    `protected static int` | `DEFAULT_DATAGRAM_PORT_INT`
    `(package private) static String` | `DEFAULT_SAM_CONFIGFILE`
    `static String` | `DEFAULT_SAM_KEYFILE`
    `protected static String` | `DEFAULT_TCP_HOST`
    `protected static String` | `DEFAULT_TCP_PORT`
    `static String` | `PROP_AUTH`
    `static String` | `PROP_DATAGRAM_HOST`
    `static String` | `PROP_DATAGRAM_PORT`
    `static String` | `PROP_PW_PREFIX`
    `static String` | `PROP_PW_SUFFIX`
    `static String` | `PROP_TCP_HOST`
    `static String` | `PROP_TCP_PORT`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SAMBridge(I2PAppContext context, ClientAppManager mgr, String[] args)` For ClientApp interface.
    `SAMBridge(String listenHost, int listenPort, boolean isSSL, Properties i2cpProps, String persistFile, File configFile)` Build a new SAM bridge.
    `SAMBridge(String listenHost, int listenPort, boolean isSSL, Properties i2cpProps, String persistFile, File configFile, SAMSecureSessionInterface secureSession)` Build a new SAM bridge.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addKeystream(String name, String stream)` Specify that the given keystream should be used for the given name
    `String` | `getDisplayName()` The display name of the ClientApp, used in user interfaces.
    `String` | `getKeystream(String name)` Retrieve the I2P private keystream for the given name, formatted as a base64 string (Destination+PrivateKey+SessionPrivateKey, as I2CP stores it).
    `String` | `getName()` The generic name of the ClientApp, used for registration, e.g.
    `ClientAppState` | `getState()` The current state of the ClientApp.
    `(package private) SAMv3DatagramServer` | `getV3DatagramServer(Properties props)` Was a static singleton, now a singleton for this bridge.
    `static void` | `main(String[] args)` Usage:
    `void` | `register(Handler handler)` Handlers must call on startup
    `void` | `run()`
    `void` | `saveConfig()`
    `SAMSecureSessionInterface` | `secureSession()`
    `void` | `shutdown(String[] args)` As of 0.9.20, stops running handlers and sessions.
    `void` | `startup()` Do not take a long time.
    `void` | `unregister(Handler handler)` Handlers must call on stop

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

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

- - ### Field Detail

    - #### DEFAULT_DATAGRAM_HOST

          protected static final String DEFAULT_DATAGRAM_HOST

      See Also:
        Constant Field Values

    - #### DEFAULT_DATAGRAM_PORT

          protected static final String DEFAULT_DATAGRAM_PORT

    - #### DEFAULT_DATAGRAM_PORT_INT

          protected static final int DEFAULT_DATAGRAM_PORT_INT

      See Also:
        Constant Field Values

    - #### DEFAULT_SAM_CONFIGFILE

          static final String DEFAULT_SAM_CONFIGFILE

      See Also:
        Constant Field Values

    - #### DEFAULT_SAM_KEYFILE

          public static final String DEFAULT_SAM_KEYFILE

      See Also:
        Constant Field Values

    - #### DEFAULT_TCP_HOST

          protected static final String DEFAULT_TCP_HOST

      See Also:
        Constant Field Values

    - #### DEFAULT_TCP_PORT

          protected static final String DEFAULT_TCP_PORT

      See Also:
        Constant Field Values

    - #### PROP_AUTH

          public static final String PROP_AUTH

      See Also:
        Constant Field Values

    - #### PROP_DATAGRAM_HOST

          public static final String PROP_DATAGRAM_HOST

      See Also:
        Constant Field Values

    - #### PROP_DATAGRAM_PORT

          public static final String PROP_DATAGRAM_PORT

      See Also:
        Constant Field Values

    - #### PROP_PW_PREFIX

          public static final String PROP_PW_PREFIX

      See Also:
        Constant Field Values

    - #### PROP_PW_SUFFIX

          public static final String PROP_PW_SUFFIX

      See Also:
        Constant Field Values

    - #### PROP_TCP_HOST

          public static final String PROP_TCP_HOST

      See Also:
        Constant Field Values

    - #### PROP_TCP_PORT

          public static final String PROP_TCP_PORT

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### SAMBridge

          public SAMBridge(I2PAppContext context,
                           ClientAppManager mgr,
                           String[] args)
                    throws Exception

      For ClientApp interface. Recommended constructor for external use. Does NOT open the listener socket or start threads; caller must call startup()
      Parameters:
        `mgr` - may be null
        `args` - non-null
      Throws:
        `Exception` - on bad args

    - #### SAMBridge

          public SAMBridge(String listenHost,
                           int listenPort,
                           boolean isSSL,
                           Properties i2cpProps,
                           String persistFile,
                           File configFile)

      Build a new SAM bridge. NOT recommended for external use. Opens the listener socket but does NOT start the thread, and there's no way to do that externally. Use main(), or use the other constructor and call startup(). Deprecated for external use, to be made private.
      Parameters:
        `listenHost` - hostname to listen for SAM connections on ("0.0.0.0" for all)
        `listenPort` - port number to listen for SAM connections on
        `i2cpProps` - set of I2CP properties for finding and communicating with the router
        `persistFile` - location to store/load named keys to/from
      Throws:
        `RuntimeException` - if a server socket can't be opened

    - #### SAMBridge

          public SAMBridge(String listenHost,
                           int listenPort,
                           boolean isSSL,
                           Properties i2cpProps,
                           String persistFile,
                           File configFile,
                           SAMSecureSessionInterface secureSession)

      Build a new SAM bridge. NOT recommended for external use. Opens the listener socket but does NOT start the thread, and there's no way to do that externally. Use main(), or use the other constructor and call startup(). Deprecated for external use, to be made private.
      Parameters:
        `listenHost` - hostname to listen for SAM connections on ("0.0.0.0" for all)
        `listenPort` - port number to listen for SAM connections on
        `i2cpProps` - set of I2CP properties for finding and communicating with the router
        `persistFile` - location to store/load named keys to/from
        `secureSession` - an instance of a Secure Session to use
      Throws:
        `RuntimeException` - if a server socket can't be opened

  - ### Method Detail

    - #### addKeystream

          public void addKeystream(String name,
                                   String stream)

      Specify that the given keystream should be used for the given name
      Parameters:
        `name` - Name of the destination
        `stream` - Name of the stream

    - #### getDisplayName

          public String getDisplayName()

      Description copied from interface: `ClientApp`
      The display name of the ClientApp, used in user interfaces. The app must translate.
      Specified by:
        `getDisplayName` in interface `ClientApp`
      Returns:
        non-null

    - #### getKeystream

          public String getKeystream(String name)

      Retrieve the I2P private keystream for the given name, formatted as a base64 string (Destination+PrivateKey+SessionPrivateKey, as I2CP stores it).
      Parameters:
        `name` - Name of the destination
      Returns:
        null if the name does not exist, else the stream

    - #### getName

          public String getName()

      Description copied from interface: `ClientApp`
      The generic name of the ClientApp, used for registration, e.g. "console". Do not translate.
      Specified by:
        `getName` in interface `ClientApp`
      Returns:
        non-null

    - #### getState

          public ClientAppState getState()

      Description copied from interface: `ClientApp`
      The current state of the ClientApp.
      Specified by:
        `getState` in interface `ClientApp`
      Returns:
        non-null

    - #### getV3DatagramServer

          SAMv3DatagramServer getV3DatagramServer(Properties props)
                                           throws IOException

      Was a static singleton, now a singleton for this bridge. Instantiate and start server if it doesn't exist. We only listen on one host and port, as specified in the sam.udp.host and sam.udp.port properties. TODO we could have multiple servers on different hosts/ports in the future.
      Parameters:
        `props` - non-null instantiate and start server if it doesn't exist
      Returns:
        non-null
      Throws:
        `IOException` - if can't bind to host/port, or if different than existing

    - #### main

          public static void main(String[] args)

      Usage:

           SAMBridge [ keyfile [listenHost ] listenPort [ name=val ]* ]

      or:

           SAMBridge [ name=val ]*

      name=val options are passed to the I2CP code to build a session, allowing the bridge to specify an alternate I2CP host and port, tunnel depth, etc.
      Parameters:
        `args` - [ keyfile [ listenHost ] listenPort [ name=val ]* ]

    - #### register

          public void register(Handler handler)

      Handlers must call on startup

    - #### run

          public void run()

      Specified by:
        `run` in interface `Runnable`

    - #### saveConfig

          public void saveConfig()
                          throws IOException

      Throws:
        `IOException`

    - #### secureSession

          public SAMSecureSessionInterface secureSession()

    - #### shutdown

          public void shutdown(String[] args)

      As of 0.9.20, stops running handlers and sessions.
      Specified by:
        `shutdown` in interface `ClientApp`
      Parameters:
        `args` - generally null but could be stopArgs from clients.config

    - #### startup

          public void startup()
                       throws IOException

      Description copied from interface: `ClientApp`
      Do not take a long time. Do not block. Start threads here if necessary. Client must call ClientAppManager.notify() at least once within this method to change the state from INITIALIZED to something else. Will not be called multiple times on the same object.
      Specified by:
        `startup` in interface `ClientApp`
      Throws:
        `IOException`

    - #### unregister

          public void unregister(Handler handler)

      Handlers must call on stop