java.lang.Object
net.i2p.data.DataStructureImpl
net.i2p.data.router.RouterAddress
All Implemented Interfaces:
Serializable, DataStructure
public class RouterAddressextends DataStructureImpl
Defines a method of communicating with a router

For efficiency, the options methods and structures here are unsynchronized. Initialize the structure with readBytes(InputStream), or call the setOptions(). 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.

Expiration is accepted and returned, but the router MUST write all zeros: the field is ignored on readin and a non-zero value fails the signature check. Implementing expiration, or any other use of the field, requires several releases to propagate because it is backwards-incompatible.

See Also:

  • Field Summary

    Modifier and Type
    Field
    Description
    private short
    _cost
    Cost value (0-255).
    private long
    _expiration
    Expiration timestamp.
    private byte[]
    _ip
    Cached IP address.
    private final Properties
    _options
    Transport options.
    private int
    _port
    Cached port number.
    private String
    _transportStyle
    Transport style string.
    private static final int
    HTML_LABEL_WIDTH
    Labels are padded to this width so the colons and values line up in a monospace block.
    private static final Map<String,String>
    HTML_LABELS
    Human-readable names for the option keys, for toHtml().
    private static final String
    HTML_PAD
    Pool of spaces used to pad the rendered HTML
    private static final int
    LOG_WRAP
    Key-value pairs per line before the log form wraps.
    private static final byte[]
    NOT_LOOKED_UP
    Marker for a cost that has not been measured yet
    static final String
    PROP_HOST
    Property key for host.
    static final String
    PROP_PORT
    Property key for port.

  • Constructor Summary

    Constructors
    Constructor
    Description
    RouterAddress()
    Create an address with empty options.
    RouterAddress(String style, OrderedProperties options, int cost)
    Creates an address with a copy of the given options, so the caller may reuse or modify them after construction.

  • Method Summary

    Modifier and Type
    Method
    Description
    private static boolean
    _hiddenOption(String key)
    Options omitted from toString() as debugging detail.
    private static String
    _htmlLabel(String key)
    Human-readable name for an option key, or the capitalized key if it is unknown.
    private static void
    _htmlPair(StringBuilder buf, String label, String value)
    Appends one <span class=key>label</span> <span class=value>value</span> line, padding the label and escaping the value.
    private static String
    _label(String key)
    Display label for an option key: MTU uppercased, others capitalized.
    private static void
    _logSep(StringBuilder buf, int pairs)
    Separator before a pair in the log form: the plain " * " bullet, or that bullet at the start of a fresh line once LOG_WRAP pairs have been written.
    boolean
    deepEquals(RouterAddress addr)
    Everything, including Transport, host, port, options, and cost.
    boolean
    equals(Object object)
    Transport, host, and port only.
    int
    getCost()
    Retrieve the weighted cost of this address, relative to other methods of contacting this router.
    String
    getHost()
    Convenience, same as getOption("host").
    byte[]
    getIP()
    Caching version of InetAddress.getByName(getOption("host")).getAddress(), which is slow.
    String
    getOption(String opt)
    Transport option value for the given key.
    Map<Object,Object>
    getOptionsMap()
    Retrieve the transport specific options necessary for communication.
    int
    getPort()
    Caching version of Integer.parseInt(String, int)getOption("port")) Caches valid ports 1-65535 only.
    String
    getTransportStyle()
    Retrieve the type of transport that must be used to communicate on this address.
    int
    hashCode()
    Just use a few items for speed (expiration is always null).
    void
    readBytes(InputStream in)
    Restores the expiration field, which is accepted but must be all zeros: it is ignored on readin and a non-zero value fails the signature check.
    void
    setCost(int cost)
    Configure the weighted cost of using the address.
    String
    toHtml()
    HTML rendering for the console info page: one key-value pair per line, each side in its own span so the theme can style keys and values apart.
    String
    toString()
    Form for logs and peer pages: style, host:port, then the remaining options and cost, sorted by OrderedProperties, wrapped onto a continuation line every LOG_WRAP pairs.
    void
    writeBytes(OutputStream out)
    Write the cost, expiration, transport style, and options.

    Methods inherited from class DataStructureImpl

    calculateHash, fromBase64, fromByteArray, read, toBase64, toByteArray
    Modifier and Type
    Method
    Description
    Hash
    calculateHash()
    Calculate the SHA256 value of this object (useful for a few scenarios).
    void
    fromBase64(String data)
    Load the structure from the provided base64 string.
    void
    fromByteArray(byte[] data)
    Loads structure from the data provided
    protected int
    read(InputStream in, byte[] target)
    Repeated reads until buffer is full or IOException is thrown.
    String
    toBase64()
    Render the structure into modified base 64 notation.
    byte[]
    toByteArray()
    Convert the structure to a byte array.

    Methods inherited from class Object

    clone, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • _cost

      private volatile short _cost
      Cost value (0-255).

    • _expiration

      private long _expiration
      Expiration timestamp.

    • _transportStyle

      private String _transportStyle
      Transport style string.

    • _options

      private final Properties _options
      Transport options.

    • _ip

      private byte[] _ip
      Cached IP address.

    • _port

      private int _port
      Cached port number.

    • PROP_HOST

      public static final String PROP_HOST
      Property key for host.
      See Also:

    • PROP_PORT

      public static final String PROP_PORT
      Property key for port.
      See Also:

    • NOT_LOOKED_UP

      private static final byte[] NOT_LOOKED_UP
      Marker for a cost that has not been measured yet

    • LOG_WRAP

      private static final int LOG_WRAP
      Key-value pairs per line before the log form wraps. A full SSU2 address carries up to thirty options, and one unbroken line buries the values that matter.
      See Also:

    • HTML_LABELS

      private static final Map<String,String> HTML_LABELS
      Human-readable names for the option keys, for toHtml(). The introducer keys are prefixes that take a slot index, such as ih0, and are looked up without the index. These mirror the option-key constants in the transport packages, which this package cannot reference without a dependency cycle, so keep the two in step by hand.

      Names are deliberately kept to a similar length so the values line up in the console's monospace block.

    • HTML_LABEL_WIDTH

      private static final int HTML_LABEL_WIDTH
      Labels are padded to this width so the colons and values line up in a monospace block. A longer label is written out unchanged.
      See Also:

    • HTML_PAD

      private static final String HTML_PAD
      Pool of spaces used to pad the rendered HTML
      See Also:

  • Constructor Details

    • RouterAddress

      public RouterAddress()
      Create an address with empty options.

    • RouterAddress

      public RouterAddress(String style, OrderedProperties options, int cost)
      Creates an address with a copy of the given options, so the caller may reuse or modify them after construction.
      Parameters:
      style - transport style naming the protocol to use for this address
      options - may be null
      cost - 0-255

  • Method Details

    • getCost

      public int getCost()
      Retrieve the weighted cost of this address, relative to other methods of contacting this router. The value 0 means free and 255 means really expensive. No value above 255 is allowed.

      Unused before 0.7.12.

      Returns:
      0-255

    • setCost

      public void setCost(int cost)
      Configure the weighted cost of using the address. No value negative or above 255 is allowed.

      WARNING - do not change cost on a published address or it will break the RI sig. There is no check here. Rarely used, use 3-arg constructor.

      NTCP is set to 10 and SSU to 5 by default, unused before 0.7.12.

      Parameters:
      cost - 0-255, where 0 is free and 255 is most expensive

    • getTransportStyle

      public String getTransportStyle()
      Retrieve the type of transport that must be used to communicate on this address.
      Returns:
      the transport style

    • getOptionsMap

      public Map<Object,Object> getOptionsMap()
      Retrieve the transport specific options necessary for communication.
      Returns:
      an unmodifiable view, non-null, sorted

    • getOption

      public String getOption(String opt)
      Transport option value for the given key.
      Parameters:
      opt - the transport option name to look up, such as "host" or "port"
      Returns:
      the value of the named transport option, or null if no such option is present

    • getIP

      public byte[] getIP()
      Caching version of InetAddress.getByName(getOption("host")).getAddress(), which is slow. Caches numeric host names, and negative caches also.

      As of 0.9.32, this works for literal IP addresses only, and does NOT resolve host names. If a host name is specified in the options, this will return null. Use getHost() if you need the host name.

      Returns:
      IP or null

    • getHost

      public String getHost()
      Convenience, same as getOption("host"). Does no parsing, so faster than getIP().
      Returns:
      host string or null

    • getPort

      public int getPort()
      Caching version of Integer.parseInt(String, int)getOption("port")) Caches valid ports 1-65535 only.
      Returns:
      1-65535 or 0 if invalid

    • readBytes

      public void readBytes(InputStream in) throws DataFormatException, IOException
      Restores the expiration field, which is accepted but must be all zeros: it is ignored on readin and a non-zero value fails the signature check.
      Parameters:
      in - stream to read from
      Throws:
      IllegalStateException - if was already read in
      DataFormatException - if the data is improperly formatted
      IOException - if there was a problem reading the stream

    • writeBytes

      public void writeBytes(OutputStream out) throws DataFormatException, IOException
      Write the cost, expiration, transport style, and options. As of 0.9.3 the expiration MUST be all zeros, as it is ignored on readin and the signature will fail.
      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)
      Transport, host, and port only. Never look at cost or other properties.
      Overrides:
      equals in class Object

    • deepEquals

      public boolean deepEquals(RouterAddress addr)
      Everything, including Transport, host, port, options, and cost.
      Parameters:
      addr - may be null
      Returns:
      true only if every field of both addresses matches

    • hashCode

      public int hashCode()
      Just use a few items for speed (expiration is always null). Never look at cost or other properties.
      Overrides:
      hashCode in class Object
      Returns:
      whether h code is present

    • toString

      public String toString()
      Form for logs and peer pages: style, host:port, then the remaining options and cost, sorted by OrderedProperties, wrapped onto a continuation line every LOG_WRAP pairs. The " * " separator is kept on every pair so the console renders it as a bullet. Keys (i, s), version (v), capability bits (caps) and post-quantum flags (pq) are debugging detail and are omitted; use toHtml() where they are wanted.
      Overrides:
      toString in class Object

    • _logSep

      private static void _logSep(StringBuilder buf, int pairs)
      Separator before a pair in the log form: the plain " * " bullet, or that bullet at the start of a fresh line once LOG_WRAP pairs have been written.
      Parameters:
      buf - the builder the separator is appended to
      pairs - the number of pairs written so far, a line break comes every LOG_WRAP of them

    • toHtml

      public String toHtml()
      HTML rendering for the console info page: one key-value pair per line, each side in its own span so the theme can style keys and values apart. Unlike toString() this keeps the option keys the log form omits, names them readably, escapes the values, and orders the lines by the name the reader sees rather than by the option key. The transport style and its host:port stay leading.
      Returns:
      the address as HTML lines, each pair newline terminated

    • _htmlPair

      private static void _htmlPair(StringBuilder buf, String label, String value)
      Appends one <span class=key>label</span> <span class=value>value</span> line, padding the label and escaping the value. There is no punctuation between the two spans - the theme styles the key span, and that styling is what separates the label from the value.
      Parameters:
      buf - the builder the line is appended to
      label - the display name, right-padded to HTML_LABEL_WIDTH
      value - the text to HTML-escape and place in the value span

    • _htmlLabel

      private static String _htmlLabel(String key)
      Human-readable name for an option key, or the capitalized key if it is unknown. Introducer keys are a prefix plus a slot index, so ih0 reads as the ih name followed by the slot number.
      Parameters:
      key - the option key, possibly with a numeric slot suffix
      Returns:
      the human-readable name, with the slot number appended for suffixed keys, or the capitalized key if unknown

    • _label

      private static String _label(String key)
      Display label for an option key: MTU uppercased, others capitalized.
      Parameters:
      key - the option key to label
      Returns:
      "MTU" for the mtu key, otherwise the key with its first letter uppercased

    • _hiddenOption

      private static boolean _hiddenOption(String key)
      Options omitted from toString() as debugging detail.
      Parameters:
      key - the option key to test
      Returns:
      true for the host, port, i, s, v, caps and pq keys, which are hidden