Class Router

Method Details

• clearCaches

  public static final void clearCaches()

  Not for external use.

  Since:

  0.8.8

• 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()

• getKillVMOnEnd

  public boolean getKillVMOnEnd()

• getConfigFilename

  public String getConfigFilename()

  Returns:

  absolute path

• setConfigFilename

  @Deprecated public void setConfigFilename​(String filename)

  Deprecated.

  unused

• getConfigSetting

  public String getConfigSetting​(String name)

• setConfigSetting

  @Deprecated public void setConfigSetting​(String name, String value)

  Deprecated.

  use saveConfig(String name, String value) or saveConfig(Map toAdd, Set toRemove)

  Warning, race between here and saveConfig(), saveConfig(String name, String value) or saveConfig(Map toAdd, Set toRemove) is recommended.

  Since:

  0.8.13

• removeConfigSetting

  @Deprecated public void removeConfigSetting​(String name)

  Deprecated.

  use saveConfig(String name, String value) or saveConfig(Map toAdd, Set toRemove)

  Warning, race between here and saveConfig(), saveConfig(String name, String value) or saveConfig(Map toAdd, Set toRemove) is recommended.

  Since:

  0.8.13

• getConfigSettings

  public Set<String> getConfigSettings()

  Returns:

  unmodifiable Set, unsorted

• getConfigMap

  public Map<String,​String> getConfigMap()

  Returns:

  unmodifiable Map, unsorted

• 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().

• 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

• getWhenStarted

  public long getWhenStarted()

  Used only by routerconsole.. to be deprecated?

  Returns:

  System time, NOT context time

• 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.

• 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

  Since:

  0.9.25

• 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

• 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

  Since:

  0.9.41

• getUPnPScannerCallback

  public UPnPScannerCallback getUPnPScannerCallback()

  For Android only.

  Returns:

  the callback or null if none

  Since:

  0.9.41

• 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

  Since:

  public as of 0.9 for Android and other embedded uses

• 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.

• isAlive

  public boolean isAlive()

  True during the initial start, but false during a soft restart.

• isRunning

  public boolean isRunning()

  Returns:

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

  Since:

  0.9.39

• isRestarting

  public boolean isRestarting()

  Returns:

  true if router is RESTARTING (soft restart)

  Since:

  0.9.40

• setIsAlive

  public void setIsAlive()

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

  Since:

  0.8.12

• setNetDbReady

  public void setNetDbReady()

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

  Since:

  0.9.18

• setExplTunnelsReady

  public void setExplTunnelsReady()

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

  Since:

  0.9.18

• 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.

• isFinalShutdownInProgress

  public boolean isFinalShutdownInProgress()

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

  Since:

  0.8.12

• 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

• 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

  Since:

  0.9.24

• 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"

  Since:

  0.9.31

• getCapabilities

  public String getCapabilities()

  For building our RI. Not for external use.

  Returns:

  a capabilities string to be added to the RI

• isHidden

  public boolean isHidden()

• eventLog

  public EventLog eventLog()

  Since:

  0.9.3

• killKeys

  public void killKeys()

  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.

• 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

• cancelGracefulShutdown

  public void cancelGracefulShutdown()

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

• 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

• getShutdownTimeRemaining

  public long getShutdownTimeRemaining()

  How long until the graceful shutdown will kill us?

  Returns:

  -1 if no shutdown in progress.

• 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​(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

  Since:

  0.8.13

• 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

  Since:

  0.8.13

• 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)

  Since:

  0.8.8

• 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.

• 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

• 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.

  Since:

  0.0.47

• setEstimatedDowntime

  public void setEstimatedDowntime​(long downtime)

  Only for soft restart. Not for external use.

  Since:

  0.0.47

• 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!

• 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

• 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

• 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.