TunnelControllerGroup (Javadocs [I2P+ 2.11.0+]

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

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.

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)

Class TunnelControllerGroup

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_CONFIG_FILE

Constructor Detail

TunnelControllerGroup

Method Detail

acquire

addController

cancelDelayedShutdown

clearAllMessages

getClientExecutor

getContext

getControllers

getDisplayName

getInstance

getInstance

getMaxShutdownDelay

getName

getRemainingShutdownDelay

getState

isDelayedShutdownInProgress

loadControllers

main

prepareGracefulShutdown

release

reloadControllers

removeConfig

removeController

restartAllControllers

saveConfig

shutdown

shutdown

shutdown

startAllControllers

startup

stopAllControllers

unloadControllers