Changeset 4c6aaa32


Ignore:
Timestamp:
Mar 15, 2015 11:42:00 AM (6 years ago)
Author:
zzz <zzz@…>
Branches:
master
Children:
76cf80a
Parents:
74ab1bf
Message:

Router javadocs, stub out class P,
throw ISE instead of exit() if another router running

File:
1 edited

Legend:

Unmodified
Added
Removed
  • router/java/src/net/i2p/router/Router.java

    r74ab1bf r4c6aaa32  
    6565 * Main driver for the router.
    6666 *
     67 * For embedded use, instantiate and then call runRouter().
     68 *
    6769 */
    6870public class Router implements RouterClock.ClockShiftListener {
     
    7375    private String _configFilename;
    7476    private RouterInfo _routerInfo;
     77    /** not for external use */
    7578    public final Object routerInfoFileLock = new Object();
    7679    private final Object _configFileLock = new Object();
    7780    private long _started;
    7881    private boolean _higherVersionSeen;
    79     //private SessionKeyPersistenceHelper _sessionKeyPersistenceHelper;
    8082    private boolean _killVMOnEnd;
    8183    private int _gracefulExitCode;
     
    109111    private static final String PROP_IB_RANDOM_KEY = TunnelPoolSettings.PREFIX_INBOUND_EXPLORATORY + TunnelPoolSettings.PROP_RANDOM_KEY;
    110112    private static final String PROP_OB_RANDOM_KEY = TunnelPoolSettings.PREFIX_OUTBOUND_EXPLORATORY + TunnelPoolSettings.PROP_RANDOM_KEY;
    111     public final static String DNS_CACHE_TIME = "" + (5*60);
     113    private final static String DNS_CACHE_TIME = "" + (5*60);
    112114    private static final String EVENTLOG = "eventlog.txt";
    113115    private static final String PROP_JBIGI = "jbigi.loadedResource";
     
    142144     *  RouterContext is created but not initialized.
    143145     *  You must call runRouter() after any constructor to start things up.
     146     *
     147     *  Config file name is "router.config" unless router.configLocation set in system properties.
     148     *  @throws IllegalStateException since 0.9.19 if another router with this config is running
    144149     */
    145150    public Router() { this(null, null); }
     
    149154     *  RouterContext is created but not initialized.
    150155     *  You must call runRouter() after any constructor to start things up.
     156     *
     157     *  Config file name is "router.config" unless router.configLocation set in envProps or system properties.
     158     *
     159     *  @param envProps may be null
     160     *  @throws IllegalStateException since 0.9.19 if another router with this config is running
    151161     */
    152162    public Router(Properties envProps) { this(null, envProps); }
     
    156166     *  RouterContext is created but not initialized.
    157167     *  You must call runRouter() after any constructor to start things up.
     168     *
     169     *  @param configFilename may be null
     170     *  @throws IllegalStateException since 0.9.19 if another router with this config is running
    158171     */
    159172    public Router(String configFilename) { this(configFilename, null); }
     
    163176     *  RouterContext is created but not initialized.
    164177     *  You must call runRouter() after any constructor to start things up.
     178     *
     179     *  If configFilename is non-null, configuration is read in from there.
     180     *  Else if envProps is non-null, configuration is read in from the
     181     *  location given in the router.configLocation property.
     182     *  Else it's read in from the System property router.configLocation.
     183     *  Else from the file "router.config".
     184     *
     185     *  The most important properties are i2p.dir.base (the install directory, may be read-only)
     186     *  and i2p.dir.config (the user's configuration/data directory).
     187     *
     188     *  i2p.dir.base defaults to user.dir (CWD) but should almost always be set.
     189     *
     190     *  i2p.dir.config default depends on OS, user name (to detect if running as a service or not),
     191     *  and auto-detection of whether there appears to be previous data files in the base dir.
     192     *  See WorkingDir for details.
     193     *  If the config dir does not exist, it will be created, and files migrated from the base dir,
     194     *  in this constructor.
     195     *  If files in an existing config dir indicate that another router is already running
     196     *  with this directory, the constructor will delay for several seconds to be sure,
     197     *  and then call System.exit(-1).
     198     *
     199     *  @param configFilename may be null
     200     *  @param envProps may be null
     201     *  @throws IllegalStateException since 0.9.19 if another router with this config is running
    165202     */
    166203    public Router(String configFilename, Properties envProps) {
     
    274311                System.err.println("       a new one.  If you are positive that no other instance is running,");
    275312                System.err.println("       please delete the file " + getPingFile().getAbsolutePath());
    276                 System.exit(-1);
     313                //System.exit(-1);
     314                // throw exception instead, for embedded
     315                throw new IllegalStateException(
     316                                   "ERROR: There appears to be another router already running!" +
     317                                   " Please make sure to shut down old instances before starting up" +
     318                                   " a new one.  If you are positive that no other instance is running," +
     319                                   " please delete the file " + getPingFile().getAbsolutePath());
    277320            }
    278321        }
     
    339382        _log = _context.logManager().getLog(Router.class);
    340383        _log.info("New router created with config file " + _configFilename);
    341         //_sessionKeyPersistenceHelper = new SessionKeyPersistenceHelper(_context);
    342384        _oomListener = new OOMListener(_context);
    343385
     
    354396    }
    355397   
    356     /** @since 0.8.8 */
     398    /**
     399     *  Not for external use.
     400     *  @since 0.8.8
     401     */
    357402    public static final void clearCaches() {
    358403        ByteCache.clearAll();
     
    369414     * Configure the router to kill the JVM when the router shuts down, as well
    370415     * as whether to explicitly halt the JVM during the hard fail process.
     416     *
    371417     * Defaults to true. Set to false for embedded before calling runRouter()
    372418     */
     
    423469   
    424470    /**
    425      *  Warning, may be null if called very early
     471     *  Our current router info.
     472     *  Warning, may be null if called very early.
    426473     */
    427474    public RouterInfo getRouterInfo() { return _routerInfo; }
    428475
    429476    /**
    430      *  Caller must ensure info is valid - no validation done here
     477     *  Caller must ensure info is valid - no validation done here.
     478     *  Not for external use.
    431479     */
    432480    public void setRouterInfo(RouterInfo info) {
     
    452500    public void setHigherVersionSeen(boolean seen) { _higherVersionSeen = seen; }
    453501   
     502    /**
     503     * @deprecated unused
     504     */
    454505    public long getWhenStarted() { return _started; }
    455506
     
    460511    }
    461512   
     513    /**
     514     *  Non-null, but take care when accessing context items before runRouter() is called
     515     *  as the context will not be initialized.
     516     *
     517     *  @return non-null
     518     */
    462519    public RouterContext getContext() { return _context; }
    463520   
     
    509566        _context.simpleScheduler().addPeriodicEvent(new CoalesceStatsEvent(_context), COALESCE_TIME);
    510567        _context.jobQueue().addJob(new UpdateRoutingKeyModifierJob(_context));
    511         //_sessionKeyPersistenceHelper.startup();
    512568        //_context.adminManager().startup();
    513569        _context.blocklist().startup();
     
    542598     * the file will remain in the config.
    543599     *
    544      * This is synchronized with saveConfig()
     600     * This is synchronized with saveConfig().
     601     * Not for external use.
    545602     */
    546603    public void readConfig() {
     
    662719
    663720    /**
    664      *  Only for Restarter, after soft restart is complete
     721     *  Only for Restarter, after soft restart is complete.
     722     *  Not for external use.
    665723     *  @since 0.8.12
    666724     */
     
    670728
    671729    /**
    672      *  Only for NetDB, after RIs are loaded
     730     *  Only for NetDB, after RIs are loaded.
     731     *  Not for external use.
    673732     *  @since 0.9.18
    674733     */
     
    683742
    684743    /**
    685      *  Only for Tunnel Building, after we have non-zero-hop expl. tunnels
     744     *  Only for Tunnel Building, after we have non-zero-hop expl. tunnels.
     745     *  Not for external use.
    686746     *  @since 0.9.18
    687747     */
     
    727787     * Rebuild and republish our routerInfo since something significant
    728788     * has changed.
     789     * Not for external use.
    729790     */
    730791    public void rebuildRouterInfo() { rebuildRouterInfo(false); }
    731792
     793    /**
     794     * Rebuild and republish our routerInfo since something significant
     795     * has changed.
     796     * Not for external use.
     797     */
    732798    public void rebuildRouterInfo(boolean blockingRebuild) {
    733799        if (_log.shouldLog(Log.INFO))
     
    778844    /** @since 0.9.18 */
    779845    public static final char CAPABILITY_BW_UNLIMITED = 'X';
     846    /** for testing */
    780847    public static final String PROP_FORCE_BWCLASS = "router.forceBandwidthClass";
    781848   
    782849    public static final char CAPABILITY_REACHABLE = 'R';
    783850    public static final char CAPABILITY_UNREACHABLE = 'U';
     851    /** for testing */
    784852    public static final String PROP_FORCE_UNREACHABLE = "router.forceUnreachable";
    785853
     
    787855    public static final char CAPABILITY_NEW_TUNNEL = 'T';
    788856   
     857    /**
     858     *  For building our RI. Not for external use.
     859     */
    789860    public void addCapabilities(RouterInfo ri) {
    790861        int bwLim = Math.min(_context.bandwidthLimiter().getInboundKBytesPerSecond(),
     
    805876        } else if (bwLim <= 128) {
    806877            ri.addCapability(CAPABILITY_BW128);
    807         } else { // ok, more than 128KBps... aka "lots"
    808             // TODO 512, unlimited
     878        } else if (bwLim <= 256) {
     879            ri.addCapability(CAPABILITY_BW256);
     880        } else {
     881            // 512 supported as of 0.9.18;
     882            // Add 256 as well for compatibility
     883            // TODO uncomment
     884            //ri.addCapability(CAPABILITY_BW512);
    809885            ri.addCapability(CAPABILITY_BW256);
    810886        }
     
    872948    };
    873949
     950    /**
     951     *  Not for external use.
     952     */
    874953    public void killKeys() {
    875954        //new Exception("Clearing identity files").printStackTrace();
     
    900979     * files, then reboot the router.
    901980     *
     981     *  Not for external use.
    902982     */
    903983    public synchronized void rebuildNewIdentity() {
     
    9471027    }
    9481028   
     1029    /** shut down after all tunnels are gone */
    9491030    public static final int EXIT_GRACEFUL = 2;
     1031    /** shut down immediately */
    9501032    public static final int EXIT_HARD = 3;
     1033    /** shut down immediately */
    9511034    public static final int EXIT_OOM = 10;
     1035    /** shut down immediately, and tell the wrapper to restart */
    9521036    public static final int EXIT_HARD_RESTART = 4;
     1037    /** shut down after all tunnels are gone, and tell the wrapper to restart */
    9531038    public static final int EXIT_GRACEFUL_RESTART = 5;
    9541039   
    9551040    /**
    956      *  Shutdown with no chance of cancellation
     1041     *  Shutdown with no chance of cancellation.
     1042     *  Blocking, will call exit() and not return unless setKillVMOnExit(false) was previously called.
     1043     *  May take several seconds as it runs all the shutdown hooks.
    9571044     */
    9581045    public synchronized void shutdown(int exitCode) {
     
    11131200   
    11141201    /**
     1202     * Non-blocking shutdown.
     1203     *
    11151204     * Call this if we want the router to kill itself as soon as we aren't
    11161205     * participating in any more tunnels (etc).  This will not block and doesn't
     
    11201209     * {@link #cancelGracefulShutdown}.
    11211210     *
     1211     * Shutdown delay will be from zero to 11 minutes.
    11221212     */
    11231213    public void shutdownGracefully() {
     
    11261216
    11271217    /**
     1218     * Non-blocking shutdown.
     1219     *
    11281220     * Call this with EXIT_HARD or EXIT_HARD_RESTART for a non-blocking,
    11291221     * hard, non-graceful shutdown with a brief delay to allow a UI response
    11301222     *
    11311223     * Returns silently if a final shutdown is already in progress.
     1224     *
     1225     * @param exitCode VM exit code
    11321226     */
    11331227    public void shutdownGracefully(int exitCode) {
     
    11691263    public int scheduledGracefulExitCode() { return _gracefulExitCode; }
    11701264
    1171     /** How long until the graceful shutdown will kill us?  */
     1265    /**
     1266     *  How long until the graceful shutdown will kill us?
     1267     *  @return -1 if no shutdown in progress.
     1268     */
    11721269    public long getShutdownTimeRemaining() {
    11731270        if (_gracefulExitCode <= 0) return -1; // maybe Long.MAX_VALUE would be better?
     
    12061303   
    12071304    /**
    1208      * Updates the current config and then saves it.
     1305     * Updates the current config with the given key/value and then saves it.
    12091306     * Prevents a race in the interval between setConfigSetting() / removeConfigSetting() and saveConfig(),
    12101307     * Synchronized with getConfig() / saveConfig()
     
    12821379     *  As of 0.8.8, this returns immediately and does the actual restart in a separate thread.
    12831380     *  Poll isAlive() if you need to know when the restart is complete.
     1381     *
     1382     *  Not recommended for external use.
    12841383     */
    12851384    public synchronized void restart() {
     
    13021401     *  Instantiates Router(), and either installs updates and exits,
    13031402     *  or calls runRouter().
     1403     *
     1404     *  Not recommended for embedded use.
     1405     *  Applications bundling I2P should instantiate a Router and call runRouter().
    13041406     *
    13051407     *  @param args null ok
     
    13321434        System.out.println("Starting I2P " + RouterVersion.FULL_VERSION);
    13331435        //verifyWrapperConfig();
    1334         Router r = new Router();
     1436        Router r;
     1437        try {
     1438            r = new Router();
     1439        } catch (IllegalStateException ise) {
     1440            System.exit(-1);
     1441            return;
     1442        }
    13351443        if (rebuild) {
    13361444            r.rebuildNewIdentity();
     
    15611669    }
    15621670   
    1563     static final long LIVELINESS_DELAY = 60*1000;
     1671    private static final long LIVELINESS_DELAY = 60*1000;
    15641672   
    15651673    /**
     
    16201728    }
    16211729
     1730    /**
     1731     *  Max of inbound and outbound rate in bytes per second
     1732     */
    16221733    public int get1sRate() { return get1sRate(false); }
    16231734
     1735    /**
     1736     *  When outboundOnly is false, outbound rate in bytes per second.
     1737     *  When true, max of inbound and outbound rate in bytes per second.
     1738     */
    16241739    public int get1sRate(boolean outboundOnly) {
    16251740            FIFOBandwidthLimiter bw = _context.bandwidthLimiter();
     
    16301745    }
    16311746
     1747    /**
     1748     *  Inbound rate in bytes per second
     1749     */
    16321750    public int get1sRateIn() {
    16331751            FIFOBandwidthLimiter bw = _context.bandwidthLimiter();
     
    16351753    }
    16361754
     1755    /**
     1756     *  Max of inbound and outbound rate in bytes per second
     1757     */
    16371758    public int get15sRate() { return get15sRate(false); }
    16381759
     1760    /**
     1761     *  When outboundOnly is false, outbound rate in bytes per second.
     1762     *  When true, max of inbound and outbound rate in bytes per second.
     1763     */
    16391764    public int get15sRate(boolean outboundOnly) {
    16401765            FIFOBandwidthLimiter bw = _context.bandwidthLimiter();
     
    16451770    }
    16461771
     1772    /**
     1773     *  Inbound rate in bytes per second
     1774     */
    16471775    public int get15sRateIn() {
    16481776            FIFOBandwidthLimiter bw = _context.bandwidthLimiter();
     
    16501778    }
    16511779
     1780    /**
     1781     *  Max of inbound and outbound rate in bytes per second
     1782     */
    16521783    public int get1mRate() { return get1mRate(false); }
    16531784
     1785    /**
     1786     *  When outboundOnly is false, outbound rate in bytes per second.
     1787     *  When true, max of inbound and outbound rate in bytes per second.
     1788     */
    16541789    public int get1mRate(boolean outboundOnly) {
    16551790        int send = 0;
     
    16671802    }
    16681803
     1804    /**
     1805     *  Inbound rate in bytes per second
     1806     */
    16691807    public int get1mRateIn() {
    16701808        StatManager mgr = _context.statManager();
     
    16761814    }
    16771815
     1816    /**
     1817     *  Max of inbound and outbound rate in bytes per second
     1818     */
    16781819    public int get5mRate() { return get5mRate(false); }
    16791820
     1821    /**
     1822     *  When outboundOnly is false, outbound rate in bytes per second.
     1823     *  When true, max of inbound and outbound rate in bytes per second.
     1824     */
    16801825    public int get5mRate(boolean outboundOnly) {
    16811826        int send = 0;
Note: See TracChangeset for help on using the changeset viewer.