net.i2p.data
Class RouterInfo

java.lang.Object
  extended by net.i2p.data.DataStructureImpl
      extended by net.i2p.data.DatabaseEntry
          extended by net.i2p.data.RouterInfo
All Implemented Interfaces:
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.

Author:
jrandom

Field Summary
static String BW_CAPABILITY_CHARS
           
static char CAPABILITY_HIDDEN
           
static String PROP_CAPABILITIES
           
static String PROP_NETWORK_ID
           
 
Fields inherited from class net.i2p.data.DatabaseEntry
_currentRoutingKey, _routingKeyGenMod, _signature, KEY_TYPE_LEASESET, KEY_TYPE_ROUTERINFO
 
Constructor Summary
RouterInfo()
           
RouterInfo(RouterInfo old)
          Used only by Router and PublishLocalRouterInfoJob.
 
Method Summary
 void addCapability(char cap)
           
 void delCapability(char cap)
           
 boolean equals(Object object)
           
 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
 long getDate()
          A common interface to the timestamp of the two subclasses.
 RouterIdentity getIdentity()
          Retrieve the identity of the router represented
protected  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)
           
 Properties getOptions()
          Deprecated. use getOptionsMap()
 Map getOptionsMap()
          Retrieve a set of options or statistics that the router can expose.
 Set<Hash> getPeers()
          Deprecated. Implemented here but unused elsewhere
 long getPublished()
          Retrieve the approximate date on which the info was published (essentially a version number for the routerInfo structure, except that it also contains freshness information - whether or not the router is currently publishing its information).
 RouterAddress getTargetAddress(String transportStyle)
          Pull the first workable target address for the given transport
 List<RouterAddress> getTargetAddresses(String transportStyle)
          For future multiple addresses per-transport (IPV6), currently unused
 int getType()
          Get the type of the data structure.
 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 setPeers(Set<Hash> peers)
          Deprecated. Implemented here but unused elsewhere
 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, getRoutingKey, getSignature, getSigningPublicKey, setRoutingKey, 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

PROP_NETWORK_ID

public static final String PROP_NETWORK_ID
See Also:
Constant Field Values

PROP_CAPABILITIES

public static final String PROP_CAPABILITIES
See Also:
Constant Field Values

CAPABILITY_HIDDEN

public static final char CAPABILITY_HIDDEN
See Also:
Constant Field Values

BW_CAPABILITY_CHARS

public static final String BW_CAPABILITY_CHARS
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

getDate

public long getDate()
Description copied from class: DatabaseEntry
A common interface to the timestamp of the two subclasses. Identical to getEarliestLeaseData() 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

getKeysAndCert

protected 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

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

getIdentity

public RouterIdentity getIdentity()
Retrieve the identity of the router represented


setIdentity

public void setIdentity(RouterIdentity ident)
Configure the identity of the router represented

Throws:
IllegalStateException - if RouterInfo is already signed

getPublished

public long getPublished()
Retrieve the approximate date on which the info was published (essentially a version number for the routerInfo structure, except that it also contains freshness information - whether or not the router is currently publishing its information). This should be used to help expire old routerInfo structures


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

getAddresses

public Collection<RouterAddress> getAddresses()
Retrieve the set of RouterAddress structures at which this router can be contacted.

Returns:
unmodifiable view, non-null

setAddresses

public void setAddresses(Collection<RouterAddress> addresses)
Specify a set of RouterAddress structures at which this router can be contacted. Warning - Sorts the addresses here. Do not modify any address after calling this, as the sort order is based on the hash of the entire address structure.

Parameters:
addresses - may be null
Throws:
IllegalStateException - if RouterInfo is already signed or addresses previously set

getPeers

public Set<Hash> getPeers()
Deprecated. Implemented here but unused elsewhere

Retrieve a set of SHA-256 hashes of RouterIdentities from routers this router can be reached through.


setPeers

public void setPeers(Set<Hash> peers)
Deprecated. Implemented here but unused elsewhere

Specify a set of SHA-256 hashes of RouterIdentities from routers this router can be reached through.

Throws:
IllegalStateException - if RouterInfo is already signed

getOptions

public Properties getOptions()
Deprecated. use getOptionsMap()

Retrieve a set of options or statistics that the router can expose.

Returns:
sorted, non-null, NOT a copy, do not modify!!!

getOptionsMap

public Map getOptionsMap()
Retrieve a set of options or statistics that the router can expose.

Returns:
an unmodifiable view, non-null, sorted
Since:
0.8.13

getOption

public String getOption(String opt)

setOptions

public void setOptions(Properties options)
Configure a set of options or statistics that the router can expose. Makes a copy.

Parameters:
options - if null, clears current options
Throws:
IllegalStateException - if RouterInfo is already signed

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:
null on error ???????????????????????
Throws:
DataFormatException - if the data is somehow b0rked (missing props, etc)

isValid

public boolean isValid()
Determine whether this router info is authorized with a valid signature


verifySignature

public boolean verifySignature()
Same as isValid()

Overrides:
verifySignature in class DatabaseEntry
Returns:
valid
Since:
0.9

getNetworkId

public int getNetworkId()
which network is this routerInfo a part of. configured through the property PROP_NETWORK_ID

Returns:
-1 if unknown

getCapabilities

public String getCapabilities()
what special capabilities this router offers

Returns:
non-null, empty string if none

isHidden

public boolean isHidden()
Is this a hidden node?


getBandwidthTier

public String getBandwidthTier()
Return a string representation of this node's bandwidth tier, or "Unknown"


addCapability

public void addCapability(char cap)
Throws:
IllegalStateException - if RouterInfo is already signed

delCapability

public void delCapability(char cap)
Throws:
IllegalStateException - if RouterInfo is already signed

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

getTargetAddress

public RouterAddress getTargetAddress(String transportStyle)
Pull the first workable target address for the given transport


getTargetAddresses

public List<RouterAddress> getTargetAddresses(String transportStyle)
For future multiple addresses per-transport (IPV6), currently unused

Since:
0.7.11

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
Since:
0.9

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

equals

public boolean equals(Object object)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

toString

public String toString()
Overrides:
toString in class Object

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.

Since:
0.8