java.lang.Object
net.i2p.client.streaming.I2PSocketManagerFactory
public class I2PSocketManagerFactoryextends Object
Simplify the creation of I2PSession and transient I2P Destination objects if necessary to create a socket manager. This class is most likely how classes will begin their use of the socket library. For new applications, createDisconnectedManager() is the preferred method. It is non-blocking and throws on all errors. All createManager() methods are blocking and return null on error. Note that for all methods, host and port arguments are ignored if in RouterContext; it will connect internally to the router in the JVM. You cannot connect out from a router JVM to another router. Factory for creating I2PSocketManager instances.

  • Field Details

  • Constructor Details

    • I2PSocketManagerFactory

      public I2PSocketManagerFactory()
      Constructor. Managers are always built by the static createManager() family below, so an instance carries no state.

  • Method Details

    • createManager

      public static I2PSocketManager createManager()
      Create a socket manager using a brand new destination connected to the I2CP router on the local machine on the default port (7654). Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(IncomingConnectionFilter filter)
      Create a socket manager using a brand new destination connected to the I2CP router on the local machine on the default port (7654) with the specified incoming connection filter. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      filter - The filter for incoming connections
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(Properties opts)
      Create a socket manager using a brand new destination connected to the I2CP router on the local machine on the default port (7654). Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      opts - Streaming and I2CP options, may be null
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(Properties opts, IncomingConnectionFilter filter)
      Create a socket manager using a brand new destination connected to the I2CP router on the local machine on the default port (7654). Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      opts - Streaming and I2CP options, may be null
      filter - The filter to use for incoming connections
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(String host, int port)
      Create a socket manager using a brand new destination connected to the I2CP router on the specified host and port. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      host - I2CP host null to use default, ignored if in router context
      port - I2CP port <= 0 to use default, ignored if in router context
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(String host, int port, IncomingConnectionFilter filter)
      Create a socket manager using a brand new destination connected to the I2CP router on the specified host and port with the specified connection filter. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      host - I2CP host null to use default, ignored if in router context
      port - I2CP port <= 0 to use default, ignored if in router context
      filter - The filter to use for incoming connections
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(String i2cpHost, int i2cpPort, Properties opts)
      Create a socket manager using a brand new destination connected to the I2CP router on the given machine reachable through the given port. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      i2cpHost - I2CP host null to use default, ignored if in router context
      i2cpPort - I2CP port <= 0 to use default, ignored if in router context
      opts - Streaming and I2CP options, may be null
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(String i2cpHost, int i2cpPort, Properties opts, IncomingConnectionFilter filter)
      Create a socket manager using a brand new destination connected to the I2CP router on the given machine reachable through the given port with the specified connection filter. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      i2cpHost - I2CP host null to use default, ignored if in router context
      i2cpPort - I2CP port <= 0 to use default, ignored if in router context
      opts - Streaming and I2CP options, may be null
      filter - The filter to use for incoming connections
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(InputStream myPrivateKeyStream)
      Create a socket manager using the destination loaded from the given private key stream and connected to the default I2CP host and port. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      myPrivateKeyStream - private key stream, format is specified in PrivateKeyFile or null for a transient destination. Caller must close.
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(InputStream myPrivateKeyStream, IncomingConnectionFilter filter)
      Create a socket manager using the destination loaded from the given private key stream and connected to the default I2CP host and port with the specified connection filter. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      myPrivateKeyStream - private key stream, format is specified in PrivateKeyFile or null for a transient destination. Caller must close.
      filter - The filter to use for incoming connections
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(InputStream myPrivateKeyStream, Properties opts)
      Create a socket manager using the destination loaded from the given private key stream and connected to the default I2CP host and port. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      myPrivateKeyStream - private key stream, format is specified in PrivateKeyFile or null for a transient destination. Caller must close.
      opts - Streaming and I2CP options, may be null
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(InputStream myPrivateKeyStream, Properties opts, IncomingConnectionFilter filter)
      Create a socket manager using the destination loaded from the given private key stream and connected to the default I2CP host and port. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      myPrivateKeyStream - private key stream, format is specified in PrivateKeyFile or null for a transient destination. Caller must close.
      opts - Streaming and I2CP options, may be null
      filter - The filter to use for incoming connections
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(InputStream myPrivateKeyStream, String i2cpHost, int i2cpPort, Properties opts)
      Create a socket manager using the destination loaded from the given private key stream and connected to the I2CP router on the specified machine on the given port. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      myPrivateKeyStream - private key stream, format is specified in PrivateKeyFile or null for a transient destination. Caller must close.
      i2cpHost - I2CP host null to use default, ignored if in router context
      i2cpPort - I2CP port <= 0 to use default, ignored if in router context
      opts - Streaming and I2CP options, may be null
      Returns:
      the newly created socket manager, or null if there were errors

    • createManager

      public static I2PSocketManager createManager(InputStream myPrivateKeyStream, String i2cpHost, int i2cpPort, Properties opts, IncomingConnectionFilter filter)
      Create a socket manager using the destination loaded from the given private key stream and connected to the I2CP router on the specified machine on the given port. Blocks for a long time while the router builds tunnels. The nonblocking createDisconnectedManager() is preferred.
      Parameters:
      myPrivateKeyStream - private key stream, format is specified in PrivateKeyFile or null for a transient destination. Caller must close.
      i2cpHost - I2CP host null to use default, ignored if in router context
      i2cpPort - I2CP port <= 0 to use default, ignored if in router context
      opts - Streaming and I2CP options, may be null
      filter - The filter to use for incoming connections
      Returns:
      the newly created socket manager, or null if there were errors

    • isSessionInterrupt

      static boolean isSessionInterrupt(I2PSessionException ise)
      Whether a session failure was just an interrupt.

      Distinguishes "we asked this thread to stop" from a genuine fault, which is what decides WARN versus ERROR at the call site.

      Parameters:
      ise - the session failure, may be null
      Returns:
      true if the cause was an InterruptedException

    • describeSessionFailure

      static String describeSessionFailure(I2PSessionException ise, String threadName)
      Renders a session-creation failure with enough identity to act on: which thread was doing the work, which stage of session setup was interrupted, and the exception type rather than only its message.
      Parameters:
      ise - the failure, may be null
      threadName - name of the thread that was creating the manager
      Returns:
      a single-line description naming the thread and the cause

    • createDisconnectedManager

      public static I2PSocketManager createDisconnectedManager(InputStream myPrivateKeyStream, String i2cpHost, int i2cpPort, Properties opts) throws I2PSessionException
      Create a disconnected socket manager using the destination loaded from the given private key stream, or null for a transient destination. Non-blocking. Does not connect to the router or build tunnels. For servers, caller MUST call getSession().connect() to build tunnels and start listening. For clients, caller may do that to build tunnels in advance; otherwise, the first call to connect() will initiate a connection to the router, with significant delay for tunnel building.
      Parameters:
      myPrivateKeyStream - private key stream, format is specified in PrivateKeyFile or null for a transient destination. Caller must close.
      i2cpHost - I2CP host null to use default, ignored if in router context
      i2cpPort - I2CP port <= 0 to use default, ignored if in router context
      opts - Streaming and I2CP options, may be null
      Returns:
      the newly created socket manager, non-null (throws on error)
      Throws:
      I2PSessionException - if the manager could not be created, including failure to generate a transient destination or to establish the session with the router

    • createDisconnectedManager

      public static I2PSocketManager createDisconnectedManager(InputStream myPrivateKeyStream, String i2cpHost, int i2cpPort, Properties opts, IncomingConnectionFilter filter) throws I2PSessionException
      Create a disconnected socket manager using the destination loaded from the given private key stream, or null for a transient destination. Non-blocking. Does not connect to the router or build tunnels. For servers, caller MUST call getSession().connect() to build tunnels and start listening. For clients, caller may do that to build tunnels in advance; otherwise, the first call to connect() will initiate a connection to the router, with significant delay for tunnel building.
      Parameters:
      myPrivateKeyStream - private key stream, format is specified in PrivateKeyFile or null for a transient destination. Caller must close.
      i2cpHost - I2CP host null to use default, ignored if in router context
      i2cpPort - I2CP port <= 0 to use default, ignored if in router context
      opts - Streaming and I2CP options, may be null
      filter - the incoming connection filter providing allow/deny decisions
      Returns:
      the newly created socket manager, non-null (throws on error)
      Throws:
      I2PSessionException - if the keys for a transient destination could not be generated, or the manager could not be created with the given connection filter

    • createManager

      private static I2PSocketManager createManager(InputStream myPrivateKeyStream, String i2cpHost, int i2cpPort, Properties opts, boolean connect, IncomingConnectionFilter filter) throws I2PSessionException
      Create a socket manager using the destination loaded from the given private key stream and connected to the I2CP router on the specified machine on the given port. Blocks for a long time while the router builds tunnels if connect is true.
      Parameters:
      myPrivateKeyStream - private key stream, format is specified in PrivateKeyFile non-null. Caller must close.
      i2cpHost - I2CP host null to use default, ignored if in router context
      i2cpPort - I2CP port <= 0 to use default, ignored if in router context
      opts - Streaming and I2CP options, may be null
      connect - true to connect (blocking)
      filter - The filter to use for incoming connections
      Returns:
      the newly created socket manager, non-null (throws on error)
      Throws:
      I2PSessionException - if the session cannot be created from the key stream, or connect is true and connecting fails

    • createManager

      private static I2PSocketManager createManager(I2PSession session, Properties opts, String name, IncomingConnectionFilter filter)
      Wraps a session as a socket manager.
      Parameters:
      session - the session to wrap
      opts - the socket options
      name - the manager's name
      filter - filter for incoming connections
      Returns:
      the new manager

    • getHost

      private static String getHost()
      Host taken from the options or the environment.
      Returns:
      the host to connect to

    • getPort

      private static int getPort()
      Port taken from the options or the environment.
      Returns:
      the port to connect to

    • getSigType

      private static SigType getSigType(Properties opts)
      Determine the configured signature type from the given options.
      Parameters:
      opts - may be null
      Returns:
      the sig type

    • getLog

      private static Log getLog()
      The logger for this class.
      Returns:
      the Log instance from the global context's log manager