net.i2p.router

## Class Router

- java.lang.Object
- - net.i2p.router.Router

- All Implemented Interfaces:
    RouterClock.ClockShiftListener

      public class Router
      extends Object
      implements RouterClock.ClockShiftListener

  Core router implementation that manages I2P node lifecycle, configuration, and subsystem coordination. Handles startup/shutdown, router info management, bandwidth capabilities, and provides the main entry point for both embedded and standalone router operation. For embedded use, instantiate, call setKillVMOnEnd(false), and then call runRouter().

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `Object` | `_familyKeyLock`
    `static char` | `CAPABILITY_BW_UNLIMITED`
    `static char` | `CAPABILITY_BW12`
    `static char` | `CAPABILITY_BW128`
    `static char` | `CAPABILITY_BW256`
    `static char` | `CAPABILITY_BW32`
    `static char` | `CAPABILITY_BW512`
    `static char` | `CAPABILITY_BW64`
    `static char` | `CAPABILITY_CONGESTION_MODERATE`
    `static char` | `CAPABILITY_CONGESTION_SEVERE`
    `static char` | `CAPABILITY_NO_TUNNELS`
    `static char` | `CAPABILITY_REACHABLE`
    `static char` | `CAPABILITY_UNREACHABLE`
    `static long` | `CLOCK_FUDGE_FACTOR` let clocks be off by 1 minute
    `static int` | `COALESCE_TIME` coalesce stats this often - should be a little less than one minute, so the graphs get updated
    `static int` | `DEFAULT_SHARE_PERCENTAGE`
    `static int` | `EXIT_GRACEFUL` shut down after all tunnels are gone
    `static int` | `EXIT_GRACEFUL_RESTART` shut down after all tunnels are gone, and tell the wrapper to restart
    `static int` | `EXIT_HARD` shut down immediately
    `static int` | `EXIT_HARD_RESTART` shut down immediately, and tell the wrapper to restart
    `static int` | `EXIT_OOM` shut down immediately
    `static int` | `MIN_BW_K` In binary (1024) Kbytes
    `static int` | `MIN_BW_L` In binary (1024) Kbytes
    `static int` | `MIN_BW_M` In binary (1024) Kbytes
    `static int` | `MIN_BW_N` In binary (1024) Kbytes
    `static int` | `MIN_BW_O` In binary (1024) Kbytes
    `static int` | `MIN_BW_P` In binary (1024) Kbytes
    `static int` | `MIN_BW_X` In binary (1024) Kbytes
    `static String` | `PROP_BANDWIDTH_SHARE_PERCENTAGE`
    `static String` | `PROP_CONFIG_FILE`
    `static String` | `PROP_DYNAMIC_KEYS` New router keys at every restart.
    `static String` | `PROP_FORCE_BWCLASS` for testing
    `static String` | `PROP_FORCE_UNREACHABLE` for testing
    `static String` | `PROP_HIDDEN` this puts an 'H' in your routerInfo
    `static String` | `PROP_HIDDEN_HIDDEN` this does not put an 'H' in your routerInfo
    `static String` | `PROP_IB_RANDOM_KEY`
    `static String` | `PROP_OB_RANDOM_KEY`
    `static String` | `PROP_REBUILD_KEYS` New router keys once only.
    `Object` | `routerInfoFileLock` not for external use
    `static String` | `UPDATE_FILE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Router()` Instantiation only.
    `Router(Properties envProps)` Instantiation only.
    `Router(String configFilename)` Instantiation only.
    `Router(String configFilename, Properties envProps)` Instantiation only.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cancelGracefulShutdown()` Cancel any prior request to shut the router down gracefully.
    `static void` | `clearCaches()` Not for external use.
    `void` | `clockShift(long delta)` The clock shift listener.
    `EventLog` | `eventLog()`
    `int` | `get15sRate()` Max of inbound and outbound rate in bytes per second
    `int` | `get15sRate(boolean outboundOnly)` When outboundOnly is false, outbound rate in bytes per second.
    `int` | `get15sRateIn()` Inbound rate in bytes per second
    `int` | `get1mRate()` Max of inbound and outbound rate in bytes per second
    `int` | `get1mRate(boolean outboundOnly)` When outboundOnly is false, outbound rate in bytes per second.
    `int` | `get1mRateIn()` Inbound rate in bytes per second
    `int` | `get1sRate()` Max of inbound and outbound rate in bytes per second
    `int` | `get1sRate(boolean outboundOnly)` When outboundOnly is false, outbound rate in bytes per second.
    `int` | `get1sRateIn()` Inbound rate in bytes per second
    `int` | `get5mRate()` Max of inbound and outbound rate in bytes per second
    `int` | `get5mRate(boolean outboundOnly)` When outboundOnly is false, outbound rate in bytes per second.
    `char` | `getBandwidthClass()` The current bandwidth class.
    `String` | `getCapabilities()` For building our RI.
    `String` | `getConfigFilename()` Get the absolute path to the router configuration file.
    `Map<String,String>` | `getConfigMap()` Get an unmodifiable map of all configuration settings.
    `String` | `getConfigSetting(String name)` Retrieve a configuration setting by name.
    `Set<String>` | `getConfigSettings()` Get an unmodifiable set of all configuration property names.
    `RouterContext` | `getContext()` Non-null, but take care when accessing context items before runRouter() is called as the context will not be initialized.
    `long` | `getEstimatedDowntime()` How long this router was down before it started, or 0 if unknown.
    `FamilyKeyCrypto` | `getFamilyKeyCrypto()` Family Key Crypto Signer / Verifier.
    `boolean` | `getKillVMOnEnd()` Check whether the router is configured to kill the JVM on shutdown.
    `int` | `getNetworkID()` The network ID.
    `Hash` | `getRouterHash()` Our current router hash.
    `RouterIdentity` | `getRouterIdentity()` Our current router identity.
    `RouterInfo` | `getRouterInfo()` Our current router info.
    `double` | `getSharePercentage()` What fraction of the bandwidth specified in our bandwidth limits should we allow to be consumed by participating tunnels?
    `long` | `getShutdownTimeRemaining()` How long until the graceful shutdown will kill us?
    `UPnPScannerCallback` | `getUPnPScannerCallback()` For Android only.
    `long` | `getUptime()` Wall clock uptime.
    `long` | `getWhenStarted()` Used only by routerconsole..
    `boolean` | `gracefulShutdownInProgress()` Is a graceful shutdown in progress? This may be cancelled.
    `boolean` | `isAdvanced()`
    `boolean` | `isAlive()` Check if the router is alive (in startup or running state).
    `boolean` | `isFinalShutdownInProgress()` Is a final shutdown in progress? This may not be cancelled.
    `boolean` | `isHidden()`
    `boolean` | `isRestarting()`
    `boolean` | `isRunning()`
    `void` | `killKeys()` Not for external use.
    `static void` | `main(String[] args)` Usage: Router [rebuild] No other options allowed, for now Instantiates Router(), and either installs updates and exits, or calls runRouter().
    `void` | `readConfig()` This updates the config with all settings found in the file.
    `void` | `rebuildNewIdentity()` Rebuild a new identity the hard way - delete all of our old identity files, then reboot the router.
    `void` | `rebuildRouterInfo()` Rebuild and republish our routerInfo since something significant has changed.
    `void` | `rebuildRouterInfo(boolean blockingRebuild)` Rebuild and republish our routerInfo since something significant has changed.
    `void` | `restart()` A "soft" restart, primarily of the comm system, after a port change or large step-change in system time.
    `void` | `runRouter()` This must be called after instantiation.
    `boolean` | `saveConfig()` Save the current config options (returning true if save was successful, false otherwise) Synchronized with file read in getConfig()
    `boolean` | `saveConfig(Map toAdd, Collection<String> toRemove)` Updates the current config and then saves it.
    `boolean` | `saveConfig(String name, String value)` Updates the current config with the given key/value and then saves it.
    `int` | `scheduledGracefulExitCode()` What exit code do we plan on using when we shut down (or -1, if there isn't a graceful shutdown planned)
    `void` | `setEstimatedDowntime(long downtime)` Only for soft restart.
    `void` | `setExplTunnelsReady()` Only for Tunnel Building, after we have non-zero-hop expl.
    `void` | `setIsAlive()` Only for Restarter, after soft restart is complete.
    `void` | `setKillVMOnEnd(boolean shouldDie)` Configure the router to kill the JVM when the router shuts down, as well as whether to explicitly halt the JVM during the hard fail process.
    `void` | `setNetDbReady()` Only for NetDB, after RIs are loaded.
    `void` | `setRouterInfo(RouterInfo info)` Caller must ensure info is valid - no validation done here.
    `void` | `setUPnPScannerCallback(UPnPScannerCallback callback)` For Android only.
    `void` | `shutdown(int exitCode)` Shutdown with no chance of cancellation.
    `void` | `shutdown2(int exitCode)` Cancel the JVM runtime hook before calling this.
    `void` | `shutdownGracefully()` Non-blocking shutdown.
    `void` | `shutdownGracefully(int exitCode)` Non-blocking shutdown.

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

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

- - ### Field Detail

    - #### _familyKeyLock

          public final Object _familyKeyLock

    - #### CAPABILITY_BW_UNLIMITED

          public static final char CAPABILITY_BW_UNLIMITED

      See Also:
        Constant Field Values

    - #### CAPABILITY_BW12

          public static final char CAPABILITY_BW12

      See Also:
        Constant Field Values

    - #### CAPABILITY_BW128

          public static final char CAPABILITY_BW128

      See Also:
        Constant Field Values

    - #### CAPABILITY_BW256

          public static final char CAPABILITY_BW256

      See Also:
        Constant Field Values

    - #### CAPABILITY_BW32

          public static final char CAPABILITY_BW32

      See Also:
        Constant Field Values

    - #### CAPABILITY_BW512

          public static final char CAPABILITY_BW512

      See Also:
        Constant Field Values

    - #### CAPABILITY_BW64

          public static final char CAPABILITY_BW64

      See Also:
        Constant Field Values

    - #### CAPABILITY_CONGESTION_MODERATE

          public static final char CAPABILITY_CONGESTION_MODERATE

      See Also:
        Constant Field Values

    - #### CAPABILITY_CONGESTION_SEVERE

          public static final char CAPABILITY_CONGESTION_SEVERE

      See Also:
        Constant Field Values

    - #### CAPABILITY_NO_TUNNELS

          public static final char CAPABILITY_NO_TUNNELS

      See Also:
        Constant Field Values

    - #### CAPABILITY_REACHABLE

          public static final char CAPABILITY_REACHABLE

      See Also:
        Constant Field Values

    - #### CAPABILITY_UNREACHABLE

          public static final char CAPABILITY_UNREACHABLE

      See Also:
        Constant Field Values

    - #### CLOCK_FUDGE_FACTOR

          public static final long CLOCK_FUDGE_FACTOR

      let clocks be off by 1 minute
      See Also:
        Constant Field Values

    - #### COALESCE_TIME

          public static final int COALESCE_TIME

      coalesce stats this often - should be a little less than one minute, so the graphs get updated
      See Also:
        Constant Field Values

    - #### DEFAULT_SHARE_PERCENTAGE

          public static final int DEFAULT_SHARE_PERCENTAGE

      See Also:
        Constant Field Values

    - #### EXIT_GRACEFUL

          public static final int EXIT_GRACEFUL

      shut down after all tunnels are gone
      See Also:
        Constant Field Values

    - #### EXIT_GRACEFUL_RESTART

          public static final int EXIT_GRACEFUL_RESTART

      shut down after all tunnels are gone, and tell the wrapper to restart
      See Also:
        Constant Field Values

    - #### EXIT_HARD

          public static final int EXIT_HARD

      shut down immediately
      See Also:
        Constant Field Values

    - #### EXIT_HARD_RESTART

          public static final int EXIT_HARD_RESTART

      shut down immediately, and tell the wrapper to restart
      See Also:
        Constant Field Values

    - #### EXIT_OOM

          public static final int EXIT_OOM

      shut down immediately
      See Also:
        Constant Field Values

    - #### MIN_BW_K

          public static final int MIN_BW_K

      In binary (1024) Kbytes
      See Also:
        Constant Field Values

    - #### MIN_BW_L

          public static final int MIN_BW_L

      In binary (1024) Kbytes
      See Also:
        Constant Field Values

    - #### MIN_BW_M

          public static final int MIN_BW_M

      In binary (1024) Kbytes
      See Also:
        Constant Field Values

    - #### MIN_BW_N

          public static final int MIN_BW_N

      In binary (1024) Kbytes
      See Also:
        Constant Field Values

    - #### MIN_BW_O

          public static final int MIN_BW_O

      In binary (1024) Kbytes
      See Also:
        Constant Field Values

    - #### MIN_BW_P

          public static final int MIN_BW_P

      In binary (1024) Kbytes
      See Also:
        Constant Field Values

    - #### MIN_BW_X

          public static final int MIN_BW_X

      In binary (1024) Kbytes
      See Also:
        Constant Field Values

    - #### PROP_BANDWIDTH_SHARE_PERCENTAGE

          public static final String PROP_BANDWIDTH_SHARE_PERCENTAGE

      See Also:
        Constant Field Values

    - #### PROP_CONFIG_FILE

          public static final String PROP_CONFIG_FILE

      See Also:
        Constant Field Values

    - #### PROP_DYNAMIC_KEYS

          public static final String PROP_DYNAMIC_KEYS

      New router keys at every restart. Disabled.
      See Also:
        Constant Field Values

    - #### PROP_FORCE_BWCLASS

          public static final String PROP_FORCE_BWCLASS

      for testing
      See Also:
        Constant Field Values

    - #### PROP_FORCE_UNREACHABLE

          public static final String PROP_FORCE_UNREACHABLE

      for testing
      See Also:
        Constant Field Values

    - #### PROP_HIDDEN

          public static final String PROP_HIDDEN

      this puts an 'H' in your routerInfo
      See Also:
        Constant Field Values

    - #### PROP_HIDDEN_HIDDEN

          public static final String PROP_HIDDEN_HIDDEN

      this does not put an 'H' in your routerInfo
      See Also:
        Constant Field Values

    - #### PROP_IB_RANDOM_KEY

          public static final String PROP_IB_RANDOM_KEY

      See Also:
        Constant Field Values

    - #### PROP_OB_RANDOM_KEY

          public static final String PROP_OB_RANDOM_KEY

      See Also:
        Constant Field Values

    - #### PROP_REBUILD_KEYS

          public static final String PROP_REBUILD_KEYS

      New router keys once only.
      See Also:
        Constant Field Values

    - #### routerInfoFileLock

          public final Object routerInfoFileLock

      not for external use

    - #### UPDATE_FILE

          public static final String UPDATE_FILE

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Router

          public Router()

      Instantiation only. Starts no threads. Does not install updates. RouterContext is created but not initialized. You must call runRouter() after any constructor to start things up. Config file name is "router.config" unless router.configLocation set in system properties. See two-arg constructor for more information.
      Throws:
        `IllegalStateException` - since 0.9.19 if another router with this config is running

    - #### Router

          public Router(Properties envProps)

      Instantiation only. Starts no threads. Does not install updates. RouterContext is created but not initialized. You must call runRouter() after any constructor to start things up. Config file name is "router.config" unless router.configLocation set in envProps or system properties. See two-arg constructor for more information.
      Parameters:
        `envProps` - may be null
      Throws:
        `IllegalStateException` - since 0.9.19 if another router with this config is running

    - #### Router

          public Router(String configFilename)

      Instantiation only. Starts no threads. Does not install updates. RouterContext is created but not initialized. You must call runRouter() after any constructor to start things up. See two-arg constructor for more information.
      Parameters:
        `configFilename` - may be null
      Throws:
        `IllegalStateException` - since 0.9.19 if another router with this config is running

    - #### Router

          public Router(String configFilename,
                        Properties envProps)

      Instantiation only. Starts no threads. Does not install updates. RouterContext is created but not initialized. You must call runRouter() after any constructor to start things up. If configFilename is non-null, configuration is read in from there. Else if envProps is non-null, configuration is read in from the location given in the router.configLocation property. Else it's read in from the System property router.configLocation. Else from the file "router.config". The most important properties are i2p.dir.base (the install directory, may be read-only) and i2p.dir.config (the user's configuration/data directory). i2p.dir.base defaults to user.dir (CWD) but should almost always be set. i2p.dir.config default depends on OS, user name (to detect if running as a service or not), and auto-detection of whether there appears to be previous data files in the base dir. See WorkingDir for details. If the config dir does not exist, it will be created, and files migrated from the base dir, in this constructor. If files in an existing config dir indicate that another router is already running with this directory, the constructor will delay for several seconds to be sure, and then throw an IllegalStateException.
      Parameters:
        `configFilename` - may be null
        `envProps` - may be null
      Throws:
        `IllegalStateException` - since 0.9.19 if another router with this config is running

  - ### Method Detail

    - #### cancelGracefulShutdown

          public void cancelGracefulShutdown()

      Cancel any prior request to shut the router down gracefully. Returns silently if a final shutdown is already in progress.

    - #### clearCaches

          public static final void clearCaches()

      Not for external use.

    - #### clockShift

          public void clockShift(long delta)

      The clock shift listener. Restart the router if we should.
      Specified by:
        `clockShift` in interface `RouterClock.ClockShiftListener`
      Parameters:
        `delta` - The system clock and adjusted clock just changed by this much, in milliseconds (approximately)

    - #### eventLog

          public EventLog eventLog()

    - #### get15sRate

          public int get15sRate()

      Max of inbound and outbound rate in bytes per second

    - #### get15sRate

          public int get15sRate(boolean outboundOnly)

      When outboundOnly is false, outbound rate in bytes per second. When true, max of inbound and outbound rate in bytes per second.

    - #### get15sRateIn

          public int get15sRateIn()

      Inbound rate in bytes per second

    - #### get1mRate

          public int get1mRate()

      Max of inbound and outbound rate in bytes per second

    - #### get1mRate

          public int get1mRate(boolean outboundOnly)

      When outboundOnly is false, outbound rate in bytes per second. When true, max of inbound and outbound rate in bytes per second.

    - #### get1mRateIn

          public int get1mRateIn()

      Inbound rate in bytes per second

    - #### get1sRate

          public int get1sRate()

      Max of inbound and outbound rate in bytes per second

    - #### get1sRate

          public int get1sRate(boolean outboundOnly)

      When outboundOnly is false, outbound rate in bytes per second. When true, max of inbound and outbound rate in bytes per second.

    - #### get1sRateIn

          public int get1sRateIn()

      Inbound rate in bytes per second

    - #### get5mRate

          public int get5mRate()

      Max of inbound and outbound rate in bytes per second

    - #### get5mRate

          public int get5mRate(boolean outboundOnly)

      When outboundOnly is false, outbound rate in bytes per second. When true, max of inbound and outbound rate in bytes per second.

    - #### getBandwidthClass

          public char getBandwidthClass()

      The current bandwidth class. For building our RI. Not for external use.
      Returns:
        a character to be added to the RI, one of "KLMNOPX"

    - #### getCapabilities

          public String getCapabilities()

      For building our RI. Not for external use.
      Returns:
        a capabilities string to be added to the RI

    - #### getConfigFilename

          public String getConfigFilename()

      Get the absolute path to the router configuration file.
      Returns:
        absolute path to the configuration file

    - #### getConfigMap

          public Map<String,String> getConfigMap()

      Get an unmodifiable map of all configuration settings.
      Returns:
        unmodifiable Map of configuration property names to values (unsorted)

    - #### getConfigSetting

          public String getConfigSetting(String name)

      Retrieve a configuration setting by name.
      Parameters:
        `name` - the configuration property name
      Returns:
        the configuration value, or null if not set

    - #### getConfigSettings

          public Set<String> getConfigSettings()

      Get an unmodifiable set of all configuration property names.
      Returns:
        unmodifiable Set of configuration property names (unsorted)

    - #### getContext

          public RouterContext getContext()

      Non-null, but take care when accessing context items before runRouter() is called as the context will not be initialized.
      Returns:
        non-null

    - #### getEstimatedDowntime

          public long getEstimatedDowntime()

      How long this router was down before it started, or 0 if unknown. This may be used for a determination of whether to regenerate keys, for example. We use the timestamp of the previous ping file left behind on crash, as set by isOnlyRouterRunning(), if present. Otherwise, the last STOPPED entry in the event log. May take a while to run the first time, if it has to go through the event log. Once called, the result is cached.

    - #### getFamilyKeyCrypto

          public FamilyKeyCrypto getFamilyKeyCrypto()

      Family Key Crypto Signer / Verifier. Not for external use. If family key is set, first call Will take a while to generate keys. Warning - risk of deadlock - do not call while holding locks (other than routerInfoLock)
      Returns:
        null on initialization failure

    - #### getKillVMOnEnd

          public boolean getKillVMOnEnd()

      Check whether the router is configured to kill the JVM on shutdown.
      Returns:
        true if VM will be killed on router shutdown

    - #### getNetworkID

          public int getNetworkID()

      The network ID. Default 2. May be changed with the config property router.networkID (restart required). Change only if running a test network to prevent cross-network contamination.
      Returns:
        2 - 254

    - #### getRouterHash

          public Hash getRouterHash()

      Our current router hash. Warning, may be null if called very early. Lockless.

    - #### getRouterIdentity

          public RouterIdentity getRouterIdentity()

      Our current router identity. Warning, may be null if called very early. Lockless.

    - #### getRouterInfo

          public RouterInfo getRouterInfo()

      Our current router info. Warning, may be null if called very early. Warning - risk of deadlock - do not call while holding locks Note: Due to lock contention, especially during a rebuild of the router info, this may take a long time. For determining the current status of the router, use RouterContext.commSystem().getStatus().

    - #### getSharePercentage

          public double getSharePercentage()

      What fraction of the bandwidth specified in our bandwidth limits should we allow to be consumed by participating tunnels?
      Returns:
        a number less than one, not a percentage!

    - #### getShutdownTimeRemaining

          public long getShutdownTimeRemaining()

      How long until the graceful shutdown will kill us?
      Returns:
        -1 if no shutdown in progress.

    - #### getUPnPScannerCallback

          public UPnPScannerCallback getUPnPScannerCallback()

      For Android only.
      Returns:
        the callback or null if none

    - #### getUptime

          public long getUptime()

      Wall clock uptime. This uses System time, NOT context time, so context clock shifts will not affect it. This is important if NTP fails and the clock then shifts from a SSU peer source just after startup.

    - #### getWhenStarted

          public long getWhenStarted()

      Used only by routerconsole.. to be deprecated?
      Returns:
        System time, NOT context time

    - #### gracefulShutdownInProgress

          public boolean gracefulShutdownInProgress()

      Is a graceful shutdown in progress? This may be cancelled. Note that this also returns true if an uncancellable final shutdown is in progress.

    - #### isAdvanced

          public boolean isAdvanced()

    - #### isAlive

          public boolean isAlive()

      Check if the router is alive (in startup or running state). True during initial startup, false during soft restart.
      Returns:
        true if router is in an alive state

    - #### isFinalShutdownInProgress

          public boolean isFinalShutdownInProgress()

      Is a final shutdown in progress? This may not be cancelled.

    - #### isHidden

          public boolean isHidden()

    - #### isRestarting

          public boolean isRestarting()

      Returns:
        true if router is RESTARTING (soft restart)

    - #### isRunning

          public boolean isRunning()

      Returns:
        true if router is RUNNING, i.e NetDB and Expl. tunnels are ready.

    - #### killKeys

          public void killKeys()

      Not for external use.

    - #### main

          public static void main(String[] args)

      Usage: Router [rebuild] No other options allowed, for now Instantiates Router(), and either installs updates and exits, or calls runRouter(). Not recommended for embedded use. Applications bundling I2P should instantiate a Router and call runRouter().
      Parameters:
        `args` - null ok
      Throws:
        `IllegalArgumentException`

    - #### readConfig

          public void readConfig()

      This updates the config with all settings found in the file. It does not clear the config first, so settings not found in the file will remain in the config. This is synchronized with saveConfig(). Not for external use.

    - #### rebuildNewIdentity

          public void rebuildNewIdentity()

      Rebuild a new identity the hard way - delete all of our old identity files, then reboot the router. Calls exit(), never returns. Not for external use.

    - #### rebuildRouterInfo

          public void rebuildRouterInfo()

      Rebuild and republish our routerInfo since something significant has changed. This is a non-blocking rebuild. Not for external use. Warning - risk of deadlock - do not call while holding locks

    - #### rebuildRouterInfo

          public void rebuildRouterInfo(boolean blockingRebuild)

      Rebuild and republish our routerInfo since something significant has changed. Not for external use. Warning - risk of deadlock - do not call while holding locks
      Parameters:
        `blockingRebuild` - ignored, always nonblocking

    - #### restart

          public void restart()

      A "soft" restart, primarily of the comm system, after a port change or large step-change in system time. Does not stop the whole JVM, so it is safe even in the absence of the wrapper. This is not a graceful restart - all peer connections are dropped immediately. As of 0.8.8, this returns immediately and does the actual restart in a separate thread. Poll isAlive() if you need to know when the restart is complete. Not recommended for external use.

    - #### runRouter

          public void runRouter()

      This must be called after instantiation. Starts the threads. Does not install updates. This is for embedded use. Standard standalone installation uses main() instead, which checks for updates and then calls this. This may take quite a while, especially if NTP fails or the system lacks entropy
      Throws:
        `IllegalStateException` - if called more than once

    - #### saveConfig

          public boolean saveConfig()

      Save the current config options (returning true if save was successful, false otherwise) Synchronized with file read in getConfig()

    - #### saveConfig

          public boolean saveConfig(Map toAdd,
                                    Collection<String> toRemove)

      Updates the current config and then saves it. Prevents a race in the interval between setConfigSetting() / removeConfigSetting() and saveConfig(), Synchronized with getConfig() / saveConfig()
      Parameters:
        `toAdd` - settings to add/change before saving, may be null or empty
        `toRemove` - settings to remove before saving, may be null or empty
      Returns:
        success

    - #### saveConfig

          public boolean saveConfig(String name,
                                    String value)

      Updates the current config with the given key/value and then saves it. Prevents a race in the interval between setConfigSetting() / removeConfigSetting() and saveConfig(), Synchronized with getConfig() / saveConfig()
      Parameters:
        `name` - setting to add/change/remove before saving
        `value` - if non-null, updated value; if null, setting will be removed
      Returns:
        success

    - #### scheduledGracefulExitCode

          public int scheduledGracefulExitCode()

      What exit code do we plan on using when we shut down (or -1, if there isn't a graceful shutdown planned)
      Returns:
        one of the EXIT_* values or -1

    - #### setEstimatedDowntime

          public void setEstimatedDowntime(long downtime)

      Only for soft restart. Not for external use.

    - #### setExplTunnelsReady

          public void setExplTunnelsReady()

      Only for Tunnel Building, after we have non-zero-hop expl. tunnels. Not for external use.

    - #### setIsAlive

          public void setIsAlive()

      Only for Restarter, after soft restart is complete. Not for external use.

    - #### setKillVMOnEnd

          public void setKillVMOnEnd(boolean shouldDie)

      Configure the router to kill the JVM when the router shuts down, as well as whether to explicitly halt the JVM during the hard fail process. Defaults to true. Set to false for embedded before calling runRouter()
      Parameters:
        `shouldDie` - true to kill VM on shutdown, false for embedded use

    - #### setNetDbReady

          public void setNetDbReady()

      Only for NetDB, after RIs are loaded. Not for external use.

    - #### setRouterInfo

          public void setRouterInfo(RouterInfo info)

      Caller must ensure info is valid - no validation done here. Not for external use. Warning - risk of deadlock - do not call while holding locks

    - #### setUPnPScannerCallback

          public void setUPnPScannerCallback(UPnPScannerCallback callback)

      For Android only. MUST be set before runRouter() is called.
      Parameters:
        `callback` - the callback or null to clear it

    - #### shutdown

          public void shutdown(int exitCode)

      Shutdown with no chance of cancellation. Blocking, will call exit() and not return unless setKillVMOnExit(false) was previously called, or a final shutdown is already in progress. May take several seconds as it runs all the shutdown hooks.
      Parameters:
        `exitCode` - one of the EXIT_* values, non-negative
      Throws:
        `IllegalArgumentException` - if exitCode negative

    - #### shutdown2

          public void shutdown2(int exitCode)

      Cancel the JVM runtime hook before calling this. Called by the ShutdownHook. NOT to be called by others, use shutdown().
      Parameters:
        `exitCode` - one of the EXIT_* values, non-negative
      Throws:
        `IllegalArgumentException` - if exitCode negative

    - #### shutdownGracefully

          public void shutdownGracefully()

      Non-blocking shutdown. Call this if we want the router to kill itself as soon as we aren't participating in any more tunnels (etc). This will not block and doesn't guarantee any particular time frame for shutting down. To shut the router down immediately, use `shutdown(int)`. If you want to cancel the graceful shutdown (prior to actual shutdown ;), call `cancelGracefulShutdown()`. Exit code will be EXIT_GRACEFUL. Shutdown delay will be from zero to 11 minutes.

    - #### shutdownGracefully

          public void shutdownGracefully(int exitCode)

      Non-blocking shutdown. Call this with EXIT_HARD or EXIT_HARD_RESTART for a non-blocking, hard, non-graceful shutdown with a brief delay to allow a UI response Returns silently if a final shutdown is already in progress.
      Parameters:
        `exitCode` - one of the EXIT_* values, non-negative
      Throws:
        `IllegalArgumentException` - if exitCode negative