net.i2p.i2ptunnel

## Class TunnelControllerGroup

- java.lang.Object
- - net.i2p.i2ptunnel.TunnelControllerGroup

- All Implemented Interfaces:
    ClientApp

      public class TunnelControllerGroup
      extends Object
      implements ClientApp

  Coordinates tunnel groups within the JVM, managing configuration persistence.

  Loads and stores tunnel configurations to disk, builds new tunnels on request. Entry point from clients.config.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) static class` | `TunnelControllerGroup.CustomThreadPoolExecutor` Thread pool executor for I2P tunnel client handlers with custom configuration

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `(package private) static String` | `DEFAULT_CONFIG_FILE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `TunnelControllerGroup(I2PAppContext context, ClientAppManager mgr, String[] args)` Instantiation only.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `(package private) void` | `acquire(TunnelController controller, I2PSession session)` Note the fact that the controller is using the session so that it isn't destroyed prematurely.
    `void` | `addController(TunnelController controller)` Add the given tunnel to the set of known controllers (but don't add it to a config file or start it or anything)
    `void` | `cancelDelayedShutdown()` Cancel a delayed server tunnel shutdown and restart any servers that were stopped.
    `List<String>` | `clearAllMessages()` Fetch and clear all outstanding messages from any of the known tunnels.
    `(package private) ThreadPoolExecutor` | `getClientExecutor()`
    `I2PAppContext` | `getContext()` Helper
    `List<TunnelController>` | `getControllers()` Retrieve a list of tunnels known.
    `String` | `getDisplayName()` ClientApp interface
    `static TunnelControllerGroup` | `getInstance()` In I2PAppContext will instantiate if necessary and always return non-null.
    `static TunnelControllerGroup` | `getInstance(I2PAppContext ctx)` In I2PAppContext will instantiate if necessary and always return non-null.
    `int` | `getMaxShutdownDelay()` Get the maximum configured shutdown delay among all server tunnels.
    `String` | `getName()` ClientApp interface
    `static int` | `getRemainingShutdownDelay()` Get the remaining time until the longest-delayed server tunnel will stop.
    `ClientAppState` | `getState()` ClientApp interface
    `static boolean` | `isDelayedShutdownInProgress()` Check if delayed server tunnel shutdown is currently in progress.
    `void` | `loadControllers(File cfgFile)` Load up all of the tunnels configured in the given file.
    `static void` | `main(String[] args)`
    `void` | `prepareGracefulShutdown()` Prepare for graceful shutdown by stopping delayed server tunnels.
    `(package private) void` | `release(TunnelController controller, I2PSession session)` Note the fact that the controller is no longer using the session, and if no other controllers are using it, destroy the session.
    `void` | `reloadControllers()` Stop all tunnels, reload config, and restart those configured to do so.
    `void` | `removeConfig(TunnelController tc)` Remove the configuration of this tunnel only
    `List<String>` | `removeController(TunnelController controller)` Stop and remove the given tunnel.
    `List<String>` | `restartAllControllers()` Restart all tunnels.
    `void` | `saveConfig(TunnelController tc)` Save the configuration of this tunnel only, may be new.
    `void` | `shutdown()` Convenience method - calls shutdown(true) to wait for.
    `void` | `shutdown(boolean waitForDelayed)` Warning - destroys the singleton! Caller must root a new context before calling instance() or main() again.
    `void` | `shutdown(String[] args)` ClientApp interface
    `List<String>` | `startAllControllers()` Start all tunnels.
    `void` | `startup()` ClientApp interface
    `List<String>` | `stopAllControllers()` Stop all tunnels.
    `void` | `unloadControllers()` Stop and remove reference to all known tunnels (but don't delete any config file or do other silly things)

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

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

- - ### Field Detail

    - #### DEFAULT_CONFIG_FILE

          static final String DEFAULT_CONFIG_FILE

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### TunnelControllerGroup

          public TunnelControllerGroup(I2PAppContext context,
                                       ClientAppManager mgr,
                                       String[] args)

      Instantiation only. Caller must call startup(). Config file problems will not throw exception until startup().
      Parameters:
        `mgr` - may be null
        `args` - zero or one args, which may be one config file or one config directory. If not absolute will be relative to the context's config dir, if empty or null, the default is i2ptunnel.config for a config file and i2ptunnel.config.d for a config directory
      Throws:
        `IllegalArgumentException` - if too many args

  - ### Method Detail

    - #### acquire

          void acquire(TunnelController controller,
                       I2PSession session)

      Note the fact that the controller is using the session so that it isn't destroyed prematurely.

    - #### addController

          public void addController(TunnelController controller)

      Add the given tunnel to the set of known controllers (but don't add it to a config file or start it or anything)

    - #### cancelDelayedShutdown

          public void cancelDelayedShutdown()

      Cancel a delayed server tunnel shutdown and restart any servers that were stopped. This should be called when the user cancels a graceful router shutdown/restart.

    - #### clearAllMessages

          public List<String> clearAllMessages()

      Fetch and clear all outstanding messages from any of the known tunnels.
      Returns:
        list of messages the tunnels have generated

    - #### getClientExecutor

          ThreadPoolExecutor getClientExecutor()

      Returns:
        non-null

    - #### getContext

          public I2PAppContext getContext()

      Helper

    - #### getControllers

          public List<TunnelController> getControllers()

      Retrieve a list of tunnels known. Side effect: if the tunnels have not been loaded from config yet, they will be.
      Returns:
        list of TunnelController objects
      Throws:
        `IllegalArgumentException` - if unable to load config from file

    - #### getDisplayName

          public String getDisplayName()

      ClientApp interface
      Specified by:
        `getDisplayName` in interface `ClientApp`
      Returns:
        non-null

    - #### getInstance

          public static TunnelControllerGroup getInstance()

      In I2PAppContext will instantiate if necessary and always return non-null. As of 0.9.4, when in RouterContext, will return null if the TCG has not yet been started by the router. As of 0.9.41, that's true for Android as well. In Android, this should be used for all calls except from LoadClientsJob, as we do not want to instantiate TCG too early. Android must do null checks on the return value.
      Throws:
        `IllegalArgumentException` - if unable to load from i2ptunnel.config

    - #### getInstance

          public static TunnelControllerGroup getInstance(I2PAppContext ctx)

      In I2PAppContext will instantiate if necessary and always return non-null. When in RouterContext, will return null (except in Android) if the TCG has not yet been started by the router. In Android, if the old instance uses a stale context, it will replace it. In Android, this should only be called from LoadClientsJob, as we do not want to instantiate TCG too early.
      Throws:
        `IllegalArgumentException` - if unable to load from i2ptunnel.config

    - #### getMaxShutdownDelay

          public int getMaxShutdownDelay()

      Get the maximum configured shutdown delay among all server tunnels.
      Returns:
        maximum delay in seconds, or 0 if no servers have delays configured

    - #### getName

          public String getName()

      ClientApp interface
      Specified by:
        `getName` in interface `ClientApp`
      Returns:
        non-null

    - #### getRemainingShutdownDelay

          public static int getRemainingShutdownDelay()

      Get the remaining time until the longest-delayed server tunnel will stop.
      Returns:
        remaining delay in seconds, or 0 if shutdown not in progress or delay has passed

    - #### getState

          public ClientAppState getState()

      ClientApp interface
      Specified by:
        `getState` in interface `ClientApp`
      Returns:
        non-null

    - #### isDelayedShutdownInProgress

          public static boolean isDelayedShutdownInProgress()

      Check if delayed server tunnel shutdown is currently in progress.
      Returns:
        true if shutdownDelayedServers() is currently executing

    - #### loadControllers

          public void loadControllers(File cfgFile)

      Load up all of the tunnels configured in the given file. Prior to 0.9.20, also started the tunnels. As of 0.9.20, does not start the tunnels, you must call startup() or getInstance() instead of loadControllers(). DEPRECATED for use outside this class. Use startup() or getInstance().
      Throws:
        `IllegalArgumentException` - if unable to load from file

    - #### main

          public static void main(String[] args)

      Parameters:
        `args` - one arg, the config file, if not absolute will be relative to the context's config dir, if no args, the default is i2ptunnel.config
      Throws:
        `IllegalArgumentException` - if unable to load from config from file

    - #### prepareGracefulShutdown

          public void prepareGracefulShutdown()

      Prepare for graceful shutdown by stopping delayed server tunnels. This should be called during graceful shutdown period, before final shutdown is triggered. It stops server tunnels with delays but does not unload controllers or release resources.

    - #### release

          void release(TunnelController controller,
                       I2PSession session)

      Note the fact that the controller is no longer using the session, and if no other controllers are using it, destroy the session.

    - #### reloadControllers

          public void reloadControllers()

      Stop all tunnels, reload config, and restart those configured to do so. WARNING - Does NOT simply reload the configuration!!! This is probably not what you want. This does not return or clear the controller messages.
      Throws:
        `IllegalArgumentException` - if unable to reload config file

    - #### removeConfig

          public void removeConfig(TunnelController tc)
                            throws IOException

      Remove the configuration of this tunnel only
      Throws:
        `IOException`

    - #### removeController

          public List<String> removeController(TunnelController controller)

      Stop and remove the given tunnel. Side effect - clears all messages the controller. Does NOT delete the configuration - must call saveConfig() or removeConfig() also.
      Returns:
        list of messages from the controller as it is stopped

    - #### restartAllControllers

          public List<String> restartAllControllers()

      Restart all tunnels. Side effect - clears all messages from all controllers.
      Returns:
        list of messages the tunnels generate when restarted

    - #### saveConfig

          public void saveConfig(TunnelController tc)
                          throws IOException

      Save the configuration of this tunnel only, may be new. Side effect: for split config, sets "confFile" property to absolute path.
      Throws:
        `IOException`

    - #### shutdown

          public void shutdown()

      Convenience method - calls shutdown(true) to wait for.

    - #### shutdown

          public void shutdown(boolean waitForDelayed)

      Warning - destroys the singleton! Caller must root a new context before calling instance() or main() again. Agressively kill and null everything to reduce memory usage in the JVM after stopping, and to recognize what must be reinitialized on restart (Android)
      Parameters:
        `waitForDelayed` - true to wait for shutdown-delayed tunnels, false for immediate

    - #### shutdown

          public void shutdown(String[] args)

      ClientApp interface
      Specified by:
        `shutdown` in interface `ClientApp`
      Parameters:
        `args` - generally null but could be stopArgs from clients.config

    - #### startAllControllers

          public List<String> startAllControllers()

      Start all tunnels. Side effect - clears all messages from all controllers.
      Returns:
        list of messages the tunnels generate when started

    - #### startup

          public void startup()

      ClientApp interface
      Specified by:
        `startup` in interface `ClientApp`
      Throws:
        `IllegalArgumentException` - if unable to load config from file

    - #### stopAllControllers

          public List<String> stopAllControllers()

      Stop all tunnels. May be restarted. Side effect - clears all messages from all controllers.
      Returns:
        list of messages the tunnels generate when stopped

    - #### unloadControllers

          public void unloadControllers()

      Stop and remove reference to all known tunnels (but don't delete any config file or do other silly things)