net.i2p.data.router

## Class RouterInfo

- java.lang.Object
- - net.i2p.data.DataStructureImpl
  - - net.i2p.data.DatabaseEntry
    - - net.i2p.data.router.RouterInfo

- All Implemented Interfaces:
    Serializable, DataStructure

      public class RouterInfo
      extends DatabaseEntry

  Defines the data that a router either publishes to the global routing table or provides to trusted peers. For efficiency, the methods and structures here are now unsynchronized. Initialize the RI with readBytes(), or call the setters and then sign() in a single thread. Don't change it after that. To ensure integrity of the RouterInfo, methods that change an element of the RouterInfo will throw an IllegalStateException after the RouterInfo is signed.
  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static String` | `BW_CAPABILITY_CHARS` Public string of chars which serve as bandwidth capacity markers NOTE: individual chars defined in Router.java
    `static char` | `CAPABILITY_HIDDEN`
    `static String` | `CONGESTION_CAPABILITY_CHARS` Public string of chars which serve as bandwidth congestion markers NOTE: individual chars defined in Router.java
    `static int` | `MAX_UNCOMPRESSED_SIZE` All legit RIs are currently under 2KB.
    `static String` | `PROP_CAPABILITIES`
    `static String` | `PROP_NETWORK_ID`

    - ### Fields inherited from class net.i2p.data.DatabaseEntry

      `_signature, KEY_TYPE_ENCRYPTED_LS2, KEY_TYPE_LEASESET, KEY_TYPE_LS2, KEY_TYPE_META_LS2, KEY_TYPE_ROUTERINFO, KEY_TYPE_SERVICE_LIST, KEY_TYPE_SERVICE_RECORD`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RouterInfo()`
    `RouterInfo(RouterInfo old)` Used only by Router and PublishLocalRouterInfoJob.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `equals(Object object)`
    `int` | `getAddressCount()` Return the number of router addresses.
    `Collection<RouterAddress>` | `getAddresses()` Retrieve the set of RouterAddress structures at which this router can be contacted.
    `String` | `getBandwidthTier()` Return a string representation of this node's bandwidth tier, or "Unknown"
    `protected byte[]` | `getBytes()` Write out the raw payload of the routerInfo, excluding the signature.
    `String` | `getCapabilities()` what special capabilities this router offers
    `String` | `getCongestionCap()` Return a string representation of this node's congestion cap, or "Unknown"
    `long` | `getDate()` A common interface to the timestamp of the two subclasses.
    `RouterIdentity` | `getIdentity()` Retrieve the identity of the router represented
    `KeysAndCert` | `getKeysAndCert()` Get the keys and the cert Identical to getDestination() in LeaseSet, and getIdentity() in RouterInfo.
    `int` | `getNetworkId()` which network is this routerInfo a part of.
    `String` | `getOption(String opt)`
    `Map<Object,Object>` | `getOptionsMap()` Retrieve a set of options or statistics that the router can expose.
    `long` | `getPublished()` Retrieve the timestamp on which the info was published, essentially a version number for the RouterInfo.
    `RouterAddress` | `getTargetAddress(String transportStyle)` Pull the first workable target address for the given transport.
    `List<RouterAddress>` | `getTargetAddresses(String transportStyle)` For multiple addresses per-transport (IPv4 or IPv6)
    `List<RouterAddress>` | `getTargetAddresses(String transportStyle1, String transportStyle2)` For multiple addresses per-transport (IPv4 or IPv6) Return addresses matching either of two styles
    `int` | `getType()` Get the type of the data structure.
    `String` | `getVersion()` For convenience, the same as getOption("router.version"), but returns "0" if unset.
    `int` | `hashCode()`
    `boolean` | `isCurrent(long maxAgeMs)` Determine whether the router was published recently (within the given age milliseconds).
    `boolean` | `isHidden()` Is this a hidden node?
    `boolean` | `isValid()` Determine whether this router info is authorized with a valid signature
    `static void` | `main(String[] args)` Print out routerinfos from files specified on the command line.
    `void` | `readBytes(InputStream in)` This does NOT validate the signature
    `void` | `readBytes(InputStream in, boolean verifySig)` If verifySig is true, this validates the signature while reading in, and throws a DataFormatException if the sig is invalid.
    `void` | `setAddresses(Collection<RouterAddress> addresses)` Specify a set of RouterAddress structures at which this router can be contacted.
    `void` | `setIdentity(RouterIdentity ident)` Configure the identity of the router represented
    `void` | `setOptions(Properties options)` Configure a set of options or statistics that the router can expose.
    `void` | `setPublished(long published)` Date on which it was published, in milliseconds since Midnight GMT on Jan 01, 1970
    `String` | `toString()`
    `boolean` | `verifySignature()` Same as isValid()
    `void` | `writeBytes(OutputStream out)` This does NOT validate the signature

    - ### Methods inherited from class net.i2p.data.DatabaseEntry

      `getHash, getReceivedAsPublished, getReceivedAsReply, getReceivedBy, getRoutingKey, getSignature, getSigningPublicKey, isLeaseSet, isLeaseSet, isRouterInfo, setReceivedAsPublished, setReceivedAsReply, setReceivedBy, setSignature, sign, validateRoutingKey`

    - ### Methods inherited from class net.i2p.data.DataStructureImpl

      `calculateHash, fromBase64, fromByteArray, read, toBase64, toByteArray`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### BW_CAPABILITY_CHARS

          public static final String BW_CAPABILITY_CHARS

      Public string of chars which serve as bandwidth capacity markers NOTE: individual chars defined in Router.java
      See Also:
        Constant Field Values

    - #### CAPABILITY_HIDDEN

          public static final char CAPABILITY_HIDDEN

      See Also:
        Constant Field Values

    - #### CONGESTION_CAPABILITY_CHARS

          public static final String CONGESTION_CAPABILITY_CHARS

      Public string of chars which serve as bandwidth congestion markers NOTE: individual chars defined in Router.java
      See Also:
        Constant Field Values

    - #### MAX_UNCOMPRESSED_SIZE

          public static final int MAX_UNCOMPRESSED_SIZE

      All legit RIs are currently under 2KB. May need to be adjusted if we add a huge new enctype or sigtype. Enforced in DatabaseStoreMessage, the transports, and reseed.
      See Also:
        Constant Field Values

    - #### PROP_CAPABILITIES

          public static final String PROP_CAPABILITIES

      See Also:
        Constant Field Values

    - #### PROP_NETWORK_ID

          public static final String PROP_NETWORK_ID

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### RouterInfo

          public RouterInfo()

    - #### RouterInfo

          public RouterInfo(RouterInfo old)

      Used only by Router and PublishLocalRouterInfoJob. Copies ONLY the identity and peers. Does not copy published, addresses, options, or signature.

  - ### Method Detail

    - #### equals

          public boolean equals(Object object)

      Overrides:
        `equals` in class `Object`

    - #### getAddressCount

          public int getAddressCount()

      Return the number of router addresses. More efficient than getAddresses().size()

    - #### getAddresses

          public Collection<RouterAddress> getAddresses()

      Retrieve the set of RouterAddress structures at which this router can be contacted.
      Returns:
        unmodifiable view, non-null

    - #### getBandwidthTier

          public String getBandwidthTier()

      Return a string representation of this node's bandwidth tier, or "Unknown"

    - #### getBytes

          protected byte[] getBytes()
                             throws DataFormatException

      Write out the raw payload of the routerInfo, excluding the signature. This caches the data in memory if possible.
      Specified by:
        `getBytes` in class `DatabaseEntry`
      Returns:
        the raw payload data, or null on error (for example, if this is a RouterInfo, a DataFormatException is thrown instead)
      Throws:
        `DataFormatException` - if the data is somehow b0rked (missing props, etc)

    - #### getCapabilities

          public String getCapabilities()

      what special capabilities this router offers
      Returns:
        non-null, empty string if none

    - #### getCongestionCap

          public String getCongestionCap()

      Return a string representation of this node's congestion cap, or "Unknown"

    - #### getDate

          public long getDate()

      Description copied from class: `DatabaseEntry`
      A common interface to the timestamp of the two subclasses. Identical to getEarliestLeaseDate() in LeaseSet, and getPublished() in RouterInfo. Note that for a LeaseSet this will be in the future, and for a RouterInfo it will be in the past. Either way, it's a timestamp.
      Specified by:
        `getDate` in class `DatabaseEntry`

    - #### getIdentity

          public RouterIdentity getIdentity()

      Retrieve the identity of the router represented

    - #### getKeysAndCert

          public KeysAndCert getKeysAndCert()

      Description copied from class: `DatabaseEntry`
      Get the keys and the cert Identical to getDestination() in LeaseSet, and getIdentity() in RouterInfo.
      Specified by:
        `getKeysAndCert` in class `DatabaseEntry`
      Returns:
        KAC or null

    - #### getNetworkId

          public int getNetworkId()

      which network is this routerInfo a part of. configured through the property PROP_NETWORK_ID
      Returns:
        -1 if unknown

    - #### getOption

          public String getOption(String opt)

    - #### getOptionsMap

          public Map<Object,Object> getOptionsMap()

      Retrieve a set of options or statistics that the router can expose.
      Returns:
        an unmodifiable view, non-null, sorted

    - #### getPublished

          public long getPublished()

      Retrieve the timestamp on which the info was published, essentially a version number for the RouterInfo. This should be used to expire old RouterInfo structures.

    - #### getTargetAddress

          public RouterAddress getTargetAddress(String transportStyle)

      Pull the first workable target address for the given transport. Use to check for any address. For all addresses, use getTargetAddresses(), which you probably want if you care about IPv6.

    - #### getTargetAddresses

          public List<RouterAddress> getTargetAddresses(String transportStyle)

      For multiple addresses per-transport (IPv4 or IPv6)
      Returns:
        non-null

    - #### getTargetAddresses

          public List<RouterAddress> getTargetAddresses(String transportStyle1,
                                                        String transportStyle2)

      For multiple addresses per-transport (IPv4 or IPv6) Return addresses matching either of two styles
      Returns:
        non-null

    - #### getType

          public int getType()

      Description copied from class: `DatabaseEntry`
      Get the type of the data structure. This should be faster than instanceof.
      Specified by:
        `getType` in class `DatabaseEntry`
      Returns:
        KEY_TYPE_ROUTERINFO or KEY_TYPE_LEASESET or LS2 types

    - #### getVersion

          public String getVersion()

      For convenience, the same as getOption("router.version"), but returns "0" if unset.
      Returns:
        non-null, "0" if unknown.

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `Object`

    - #### isCurrent

          public boolean isCurrent(long maxAgeMs)

      Determine whether the router was published recently (within the given age milliseconds). The age should be large enough to take into consideration any clock fudge factor, so values such as 1 or 2 hours are probably reasonable.
      Parameters:
        `maxAgeMs` - milliseconds between the current time and publish date to check
      Returns:
        true if it was published recently, false otherwise

    - #### isHidden

          public boolean isHidden()

      Is this a hidden node?
      Returns:
        true if either 'H' is in the capbilities, or router identity contains a hidden cert.

    - #### isValid

          public boolean isValid()

      Determine whether this router info is authorized with a valid signature

    - #### main

          public static void main(String[] args)

      Print out routerinfos from files specified on the command line. Exits 1 if any RI is invalid, fails signature, etc.

    - #### readBytes

          public void readBytes(InputStream in)
                         throws DataFormatException,
                                IOException

      This does NOT validate the signature
      Parameters:
        `in` - stream to read from
      Throws:
        `IllegalStateException` - if RouterInfo was already read in
        `DataFormatException` - if the data is improperly formatted
        `IOException` - if there was a problem reading the stream

    - #### readBytes

          public void readBytes(InputStream in,
                                boolean verifySig)
                         throws DataFormatException,
                                IOException

      If verifySig is true, this validates the signature while reading in, and throws a DataFormatException if the sig is invalid. This is faster than reserializing to validate later.
      Throws:
        `IllegalStateException` - if RouterInfo was already read in
        `DataFormatException`
        `IOException`

    - #### setAddresses

          public void setAddresses(Collection<RouterAddress> addresses)

      Specify a set of RouterAddress structures at which this router can be contacted.
      Parameters:
        `addresses` - may be null
      Throws:
        `IllegalStateException` - if RouterInfo is already signed or addresses previously set
        `IllegalArgumentException` - if too many addresses

    - #### setIdentity

          public void setIdentity(RouterIdentity ident)

      Configure the identity of the router represented
      Throws:
        `IllegalStateException` - if RouterInfo is already signed

    - #### setOptions

          public void setOptions(Properties options)

      Configure a set of options or statistics that the router can expose. Makes a copy. Warning, clears all capabilities.
      Parameters:
        `options` - if null, clears current options
      Throws:
        `IllegalStateException` - if RouterInfo is already signed

    - #### setPublished

          public void setPublished(long published)

      Date on which it was published, in milliseconds since Midnight GMT on Jan 01, 1970
      Throws:
        `IllegalStateException` - if RouterInfo is already signed

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### verifySignature

          public boolean verifySignature()

      Same as isValid()
      Overrides:
        `verifySignature` in class `DatabaseEntry`
      Returns:
        valid

    - #### writeBytes

          public void writeBytes(OutputStream out)
                          throws DataFormatException,
                                 IOException

      This does NOT validate the signature
      Parameters:
        `out` - stream to write to
      Throws:
        `DataFormatException` - if the data was incomplete or not yet ready to be written
        `IOException` - if there was a problem writing to the stream