SAMBridge (Javadocs [I2P+ 2.13.0+] - API Version 0.9.70+)

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` Default datagram host.
`protected static String`	`DEFAULT_DATAGRAM_PORT` Default datagram port.
`protected static int`	`DEFAULT_DATAGRAM_PORT_INT` Default datagram port int.
`(package private) static String`	`DEFAULT_SAM_CONFIGFILE`
`static String`	`DEFAULT_SAM_KEYFILE` Default filename for persistent SAM private key storage.
`protected static String`	`DEFAULT_TCP_HOST` Default TCP host.
`protected static String`	`DEFAULT_TCP_PORT` Default TCP port.
`static String`	`PROP_AUTH` Property to enable SAM bridge authentication.
`static String`	`PROP_DATAGRAM_HOST` Property for the SAM datagram listen address.
`static String`	`PROP_DATAGRAM_PORT` Property for the SAM datagram listen port.
`static String`	`PROP_PW_PREFIX` Property prefix for SAM password hash entries.
`static String`	`PROP_PW_SUFFIX` Property suffix for SAM password hash entries.
`static String`	`PROP_TCP_HOST` Property for the SAM TCP listen address.
`static String`	`PROP_TCP_PORT` Property for the SAM TCP listen 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()` Return the display name
`int`	`getHandlerCount()`
`(package private) SAMHandlerPool`	`getHandlerPool()` Access the shared handler pool for v3 connections.
`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()` Return the name
`int`	`getPoolActiveCount()`
`int`	`getPoolRegisteredCount()`
`int`	`getPoolSize()`
`int`	`getQueueSize()`
`int`	`getSessionCount()`
`ClientAppState`	`getState()` Return the state
`int`	`getStolenSocketCount()` Count handlers whose socket has been stolen for data streaming.
`(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`	`renderSessionTableHTML(Writer out)` Render the session table and handler summary as HTML.
`void`	`run()` Accept incoming SAM connections and dispatch to handlers.
`void`	`saveConfig()` Save the current configuration to disk.
`SAMSecureSessionInterface`	`secureSession()` Returns the interactive Secure Session manager which requires SAM applications to seek "approval" for their initial connections from the user before they can start the session.
`void`	`shutdown(String[] args)` As of 0.9.20, stops running handlers and sessions.
`void`	`startup()` Start the bridge
`void`	`unregister(Handler handler)` Handlers must call on stop
`(package private) void`	`unregisterHandlerFromPool(SAMv3Handler handler)` Remove a v3 handler from the shared handler pool.

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
```
    Default datagram host.
    See Also:
    Constant Field Values
  - DEFAULT_DATAGRAM_PORT
```
protected static final String DEFAULT_DATAGRAM_PORT
```
    Default datagram port.
  - DEFAULT_DATAGRAM_PORT_INT
```
protected static final int DEFAULT_DATAGRAM_PORT_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
```
    Default filename for persistent SAM private key storage.
    See Also:
    Constant Field Values
  - DEFAULT_TCP_HOST
```
protected static final String DEFAULT_TCP_HOST
```
    Default TCP host.
    See Also:
    Constant Field Values
  - DEFAULT_TCP_PORT
```
protected static final String DEFAULT_TCP_PORT
```
    Default TCP port.
    See Also:
    Constant Field Values
  - PROP_AUTH
```
public static final String PROP_AUTH
```
    Property to enable SAM bridge authentication.
    See Also:
    Constant Field Values
  - PROP_DATAGRAM_HOST
```
public static final String PROP_DATAGRAM_HOST
```
    Property for the SAM datagram listen address.
    See Also:
    Constant Field Values
  - PROP_DATAGRAM_PORT
```
public static final String PROP_DATAGRAM_PORT
```
    Property for the SAM datagram listen port.
    See Also:
    Constant Field Values
  - PROP_PW_PREFIX
```
public static final String PROP_PW_PREFIX
```
    Property prefix for SAM password hash entries.
    See Also:
    Constant Field Values
  - PROP_PW_SUFFIX
```
public static final String PROP_PW_SUFFIX
```
    Property suffix for SAM password hash entries.
    See Also:
    Constant Field Values
  - PROP_TCP_HOST
```
public static final String PROP_TCP_HOST
```
    Property for the SAM TCP listen address.
    See Also:
    Constant Field Values
  - PROP_TCP_PORT
```
public static final String PROP_TCP_PORT
```
    Property for the SAM TCP listen 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 - Base64-encoded private key stream (Destination+PrivateKey+SigningPrivateKey)
  - getDisplayName
```
public String getDisplayName()
```
    Return the display name
    Specified by:
    getDisplayName in interface ClientApp
    Returns:
    the display name
  - getHandlerCount
```
public int getHandlerCount()
```
    Returns:
    number of connected handlers
  - getHandlerPool
```
SAMHandlerPool getHandlerPool()
```
    Access the shared handler pool for v3 connections.
    Returns:
    the handler pool, or null if not started
  - 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()
```
    Return the name
    Specified by:
    getName in interface ClientApp
    Returns:
    the name
  - getPoolActiveCount
```
public int getPoolActiveCount()
```
    Returns:
    active pool worker threads, or 0 if pool not started
  - getPoolRegisteredCount
```
public int getPoolRegisteredCount()
```
    Returns:
    handlers registered in the pool, or 0 if pool not started
  - getPoolSize
```
public int getPoolSize()
```
    Returns:
    total pool worker threads, or 0 if pool not started
  - getQueueSize
```
public int getQueueSize()
```
    Returns:
    commands queued in the pool, or 0 if pool not started
  - getSessionCount
```
public int getSessionCount()
```
    Returns:
    number of registered streams from SessionsDB, or 0 if null
  - getState
```
public ClientAppState getState()
```
    Return the state
    Specified by:
    getState in interface ClientApp
    Returns:
    the state
  - getStolenSocketCount
```
public int getStolenSocketCount()
```
    Count handlers whose socket has been stolen for data streaming.
    Returns:
    the stolen socket count
  - 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
  - renderSessionTableHTML
```
public void renderSessionTableHTML(Writer out)
                            throws IOException
```
    Render the session table and handler summary as HTML. Called by the router console debug page.
    Parameters:
    out - non-null
    Throws:
    IOException - if the writer fails
  - run
```
public void run()
```
    Accept incoming SAM connections and dispatch to handlers.
    Specified by:
    run in interface Runnable
  - saveConfig
```
public void saveConfig()
                throws IOException
```
    Save the current configuration to disk.
    Throws:
    IOException - if the config file cannot be written
  - secureSession
```
public SAMSecureSessionInterface secureSession()
```
    Returns the interactive Secure Session manager which requires SAM applications to seek "approval" for their initial connections from the user before they can start the session.
    Returns:
    the secure session interface, or null if not configured
  - 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
```
    Start the bridge
    Specified by:
    startup in interface ClientApp
    Throws:
    IOException
  - unregister
```
public void unregister(Handler handler)
```
    Handlers must call on stop
  - unregisterHandlerFromPool
```
void unregisterHandlerFromPool(SAMv3Handler handler)
```
    Remove a v3 handler from the shared handler pool. Called by SAMv3Handler.stopHandling().
    Parameters:
    handler - non-null

Class SAMBridge

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_DATAGRAM_HOST

DEFAULT_DATAGRAM_PORT

DEFAULT_DATAGRAM_PORT_INT

DEFAULT_SAM_CONFIGFILE

DEFAULT_SAM_KEYFILE

DEFAULT_TCP_HOST

DEFAULT_TCP_PORT

PROP_AUTH

PROP_DATAGRAM_HOST

PROP_DATAGRAM_PORT

PROP_PW_PREFIX

PROP_PW_SUFFIX

PROP_TCP_HOST

PROP_TCP_PORT

Constructor Detail

SAMBridge

SAMBridge

SAMBridge

Method Detail

addKeystream

getDisplayName

getHandlerCount

getHandlerPool

getKeystream

getName

getPoolActiveCount

getPoolRegisteredCount

getPoolSize

getQueueSize

getSessionCount

getState

getStolenSocketCount

getV3DatagramServer

main

register

renderSessionTableHTML

run

saveConfig

secureSession

shutdown

startup

unregister

unregisterHandlerFromPool