java.lang.Object
net.i2p.client.naming.NamingService
Direct Known Subclasses:
DummyNamingService, SingleFileNamingService
public abstract class NamingServiceextends Object
Naming services create a subclass of this class.

  • Field Details

  • Constructor Details

    • NamingService

      protected NamingService(I2PAppContext context)
      The naming service should only be constructed and accessed through the application context. This constructor should only be used by the appropriate application context itself.
      Parameters:
      context - the application context

  • Method Details

    • lookup

      public Destination lookup(String hostname)
      Look up a hostname.
      Parameters:
      hostname - the host name to resolve, which may be a hostname, an IPv4 address, or a Base 32 address
      Returns:
      the Destination for this hostname, or null if name is unknown.

    • reverseLookup

      public String reverseLookup(Destination dest)
      Reverse lookup a destination. This implementation returns reverseLookup(dest, null).
      Parameters:
      dest - non-null destination to look up
      Returns:
      a hostname for this Destination, or null if none is known. It is safe for subclasses to always return null if no reverse lookup is possible.

    • reverseLookup

      public String reverseLookup(Hash h)
      Reverse lookup a hash. This implementation returns null. Subclasses implementing reverse lookups should override.
      Parameters:
      h - non-null hash to look up
      Returns:
      a hostname for this hash, or null if none is known. It is safe for subclasses to always return null if no reverse lookup is possible.

    • lookupBase64

      protected Destination lookupBase64(String hostname)
      If the hostname is a valid Base64 encoded destination, return the decoded Destination. Useful as a "fallback" in custom naming implementations. This is misnamed as it isn't a "lookup" at all, but a simple conversion from a Base64 string to a Destination.
      Parameters:
      hostname - 516+ character Base 64
      Returns:
      Destination or null on error

    • toString

      public String toString()
      Returns a string representation of this naming service.
      Overrides:
      toString in class Object
      Returns:
      the class simple name

    • getName

      public String getName()
      The name of this naming service.
      Returns:
      Class simple name by default

    • getConfiguration

      public Properties getConfiguration()
      Warning - unimplemented in any subclass. Returns null always.
      Returns:
      NamingService-specific options or null

    • setConfiguration

      public boolean setConfiguration(Properties p)
      Warning - unimplemented in any subclass. Returns true always.
      Parameters:
      p - the properties to set
      Returns:
      always true; the properties are ignored

    • getNamingServices

      public List<NamingService> getNamingServices()
      For daisy chaining (MetaNamingService). This implementation returns null. Subclasses implementing chaining should override.
      Returns:
      chained naming services or null

    • getParent

      public NamingService getParent()
      This implementation returns null. Subclasses implementing chaining should override.
      Returns:
      parent naming service or null if this is the root

    • addNamingService

      public boolean addNamingService(NamingService ns)
      Only for chaining-capable NamingServices. Add to end of the list.
      Parameters:
      ns - the naming service to add
      Returns:
      as addNamingService(NamingService, boolean) with head false

    • addNamingService

      public boolean addNamingService(NamingService ns, boolean head)
      Only for chaining-capable NamingServices. This implementation returns false. Subclasses implementing chaining should override.
      Parameters:
      ns - the naming service to add
      head - true to prepend to the chain, false to append
      Returns:
      true if ns was chained in; this base implementation always returns false

    • removeNamingService

      public boolean removeNamingService(NamingService ns)
      Only for chaining-capable NamingServices. This implementation returns false. Subclasses implementing chaining should override.
      Parameters:
      ns - the naming service to remove
      Returns:
      true if ns was chained out; this base implementation always returns false

    • size

      public int size()
      The number of entries in this naming service.
      Returns:
      number of entries or -1 if unknown

    • size

      public int size(Properties options)
      This implementation returns -1. Most subclasses should override.
      Parameters:
      options - NamingService-specific, can be null
      Returns:
      number of entries (matching the options if non-null) or -1 if unknown

    • getEntries

      public Map<String, Destination> getEntries()
      Warning - This obviously brings the whole database into memory, so use is discouraged.
      Returns:
      every stored hostname mapped to its Destination or empty Map if none; Returned Map is not necessarily sorted, implementation dependent

    • getEntries

      public Map<String, Destination> getEntries(Properties options)
      Warning - This will bring the whole database into memory if options is null, empty, or unsupported, use with caution.
      Parameters:
      options - NamingService-specific, can be null
      Returns:
      all mappings (matching the options if non-null) or empty Map if none; Returned Map is not necessarily sorted, implementation dependent

    • getBase64Entries

      public Map<String,String> getBase64Entries(Properties options)
      This may be more or less efficient than getEntries(), depending on the implementation. Warning - This will bring the whole database into memory if options is null, empty, or unsupported, use with caution.

      This implementation calls getEntries(options) and returns a SortedMap. Subclasses should override if they store base64 natively.

      Parameters:
      options - NamingService-specific, can be null
      Returns:
      all mappings (matching the options if non-null) or empty Map if none; Returned Map is not necessarily sorted, implementation dependent

    • export

      public void export(Writer out) throws IOException
      Export in a hosts.txt format. Output is not necessarily sorted, implementation dependent. Output may or may not contain comment lines, implementation dependent. Caller must close writer.

      This implementation calls getBase64Entries(Properties). Subclasses should override if they store in a hosts.txt format natively.

      Parameters:
      out - the writer to export to
      Throws:
      IOException - if an I/O error occurs

    • export

      public void export(Writer out, Properties options) throws IOException
      Export in a hosts.txt format. Output is not necessarily sorted, implementation dependent. Output may or may not contain comment lines, implementation dependent. Caller must close writer.

      This implementation calls getBase64Entries(options). Subclasses should override if they store in a hosts.txt format natively.

      Parameters:
      out - the writer to export to
      options - NamingService-specific, can be null
      Throws:
      IOException - if an I/O error occurs

    • getNames

      public Set<String> getNames()
      All known hostnames.
      Returns:
      all known hostnames or empty Set if none; Returned Set is not necessarily sorted, implementation dependent

    • getNames

      public Set<String> getNames(Properties options)
      All known hostnames matching the specified options.
      Parameters:
      options - NamingService-specific, can be null
      Returns:
      all known hostnames (matching the options if non-null) or empty Set if none; Returned Set is not necessarily sorted, implementation dependent

    • put

      public boolean put(String hostname, Destination d)
      Add a hostname and Destination to the addressbook. Overwrites old entry if it exists. See also putIfAbsent(String, Destination) and update().
      Parameters:
      hostname - the host name to map to the destination, overwriting any existing entry
      d - the destination for the hostname
      Returns:
      true if the entry was stored

    • put

      public boolean put(String hostname, Destination d, Properties options)
      Add a hostname and Destination to the addressbook. Overwrites old entry if it exists. See also putIfAbsent() and update(String, Destination, Properties).
      Parameters:
      hostname - the host name to map to the destination, overwriting any existing entry
      d - the destination for the hostname
      options - NamingService-specific, can be null
      Returns:
      true if the entry was stored; this base implementation always returns false

    • putIfAbsent

      public boolean putIfAbsent(String hostname, Destination d)
      Add a hostname and Destination to the addressbook. Fails if entry previously exists. See also put() and update().
      Parameters:
      hostname - the host name to map to the destination, which must not already be present
      d - the destination for the hostname
      Returns:
      true if no entry existed and the new one was stored

    • putIfAbsent

      public boolean putIfAbsent(String hostname, Destination d, Properties options)
      Add a hostname and Destination to the addressbook. Fails if entry previously exists. See also put() and update().
      Parameters:
      hostname - the host name to map to the destination, which must not already be present
      d - the destination for the hostname
      options - NamingService-specific, can be null
      Returns:
      true if no entry existed and the new one was stored; this base implementation always returns false

    • putAll

      public boolean putAll(Map<String, Destination> entries, Properties options)
      Put all the entries, each with the given options. This implementation calls put() for each entry. Subclasses may override if a more efficient implementation is available.
      Parameters:
      entries - host name to Destination mappings to add, one put() per entry
      options - NamingService-specific, can be null
      Returns:
      total success, or false if any put failed

    • update

      public boolean update(String hostname, Destination d, Properties options)
      Fails if entry did not previously exist. Warning - unimplemented in any subclass. This implementation returns false.
      Parameters:
      hostname - the host name whose existing entry is to be updated
      d - may be null if only options are changing
      options - NamingService-specific, can be null
      Returns:
      true if an existing entry was updated; this base implementation always returns false

    • remove

      public boolean remove(String hostname)
      Delete the entry.
      Parameters:
      hostname - the host name whose entry is to be deleted
      Returns:
      true if removed successfully, false on error or if it did not exist

    • remove

      public boolean remove(String hostname, Properties options)
      Delete the entry.
      Parameters:
      hostname - the host name whose entry is to be deleted
      options - NamingService-specific, can be null
      Returns:
      true if removed successfully, false on error or if it did not exist

    • requestUpdate

      public void requestUpdate(Properties options)
      Ask any registered updaters to update now.
      Parameters:
      options - NamingService- or updater-specific, may be null

    • registerListener

      public void registerListener(NamingServiceListener nsl)
      Register a listener for naming service changes.
      Parameters:
      nsl - the listener to register

    • unregisterListener

      public void unregisterListener(NamingServiceListener nsl)
      Unregister a listener for naming service changes.
      Parameters:
      nsl - the listener to unregister

    • registerUpdater

      public void registerUpdater(NamingServiceUpdater nsu)
      Register an updater for the naming service.
      Parameters:
      nsu - the updater to register

    • unregisterUpdater

      public void unregisterUpdater(NamingServiceUpdater nsu)
      Unregister an updater for the naming service.
      Parameters:
      nsu - the updater to unregister

    • lookup

      public abstract Destination lookup(String hostname, Properties lookupOptions, Properties storedOptions)
      Same as lookup(hostname) but with in and out options Note that whether this (and lookup(hostname)) resolve Base 32 addresses in the form {52 chars}.b32.i2p is NamingService-specific.
      Parameters:
      hostname - the host name to resolve, which may be a hostname, an IPv4 address, or a Base 32 address
      lookupOptions - input parameter, NamingService-specific, can be null
      storedOptions - output parameter, NamingService-specific, any stored properties will be added if non-null
      Returns:
      dest or null

    • reverseLookup

      public String reverseLookup(Destination d, Properties options)
      Same as reverseLookup(dest) but with options This implementation returns null. Subclasses implementing reverse lookups should override.
      Parameters:
      d - non-null destination to look up
      options - NamingService-specific, can be null
      Returns:
      hostname or null

    • lookupBase32

      public Destination lookupBase32(String hostname, int timeout)
      Lookup a Base 32 address. This may require the router to fetch the LeaseSet, which may take quite a while. This implementation returns null. See also lookup(Hash, int).
      Parameters:
      hostname - must be {52 chars}.b32.i2p
      timeout - in seconds; <= 0 means use router default
      Returns:
      dest or null

    • lookup

      public Destination lookup(Hash hash, int timeout)
      Same as lookupBase32(String, int) but with the SHA256 Hash precalculated This implementation returns null.
      Parameters:
      hash - the hash to look up
      timeout - in seconds; <= 0 means use router default
      Returns:
      dest or null

    • start

      public void start()
      Parent will call when added. If this is the root naming service, the core will start it. Should not be called by others.

    • shutdown

      public void shutdown()
      Parent will call when removed. If this is the root naming service, the core will stop it. Should not be called by others.

    • lookupAll

      public List<Destination> lookupAll(String hostname)
      For NamingServices that support multiple Destinations for a single hostname, return all of them.

      It is recommended that the returned list is in order of priority, highest-first, but this is NamingService-specific.

      Not recommended for resolving Base 32 addresses; whether this does resolve Base 32 addresses in the form {52 chars}.b32.i2p is NamingService-specific.

      Parameters:
      hostname - the host name to resolve, for which every known destination is returned
      Returns:
      non-empty List of Destinations, or null if nothing found

    • lookupAll

      public List<Destination> lookupAll(String hostname, Properties lookupOptions, List<Properties> storedOptions)
      For NamingServices that support multiple Destinations and Properties for a single hostname, return all of them.

      It is recommended that the returned list is in order of priority, highest-first, but this is NamingService-specific.

      If storedOptions is non-null, it must be a List that supports null entries. If the returned value (the List of Destinations) is non-null, the same number of Properties objects will be added to storedOptions. If no properties were found for a given Destination, the corresponding entry in the storedOptions list will be null.

      Not recommended for resolving Base 32 addresses; whether this does resolve Base 32 addresses in the form {52 chars}.b32.i2p is NamingService-specific.

      This implementation simply calls lookup(String). Subclasses implementing multiple destinations per hostname should override.

      Parameters:
      hostname - the host name to resolve, for which every known destination is returned
      lookupOptions - input parameter, NamingService-specific, may be null
      storedOptions - output parameter, NamingService-specific, any stored properties will be added if non-null
      Returns:
      non-empty List of Destinations, or null if nothing found

    • addDestination

      public boolean addDestination(String hostname, Destination d)
      Add a Destination to an existing hostname's entry in the addressbook.
      Parameters:
      hostname - the host name whose existing entry is to be extended
      d - the destination to add
      Returns:
      true if d was added to the hostname's entry

    • addDestination

      public boolean addDestination(String hostname, Destination d, Properties options)
      Add a Destination to an existing hostname's entry in the addressbook. This implementation simply calls putIfAbsent(). Subclasses implementing multiple destinations per hostname should override.
      Parameters:
      hostname - the host name whose existing entry is to be extended
      d - the destination to add
      options - NamingService-specific, may be null
      Returns:
      as putIfAbsent(), so d is added only when the hostname has no entry yet

    • remove

      public boolean remove(String hostname, Destination d)
      Remove a hostname's entry only if it contains the Destination d. If the NamingService supports multiple Destinations per hostname, and this is the only Destination, removes the entire entry. If additional Destinations remain, it only removes the specified Destination from the entry.
      Parameters:
      hostname - the host name whose entry holds the destination to remove
      d - the destination that must be present
      Returns:
      true if entry containing d was successfully removed.

    • remove

      public boolean remove(String hostname, Destination d, Properties options)
      Remove a hostname's entry only if it contains the Destination d. If the NamingService supports multiple Destinations per hostname, and this is the only Destination, removes the entire entry. If additional Destinations remain, it only removes the specified Destination from the entry.

      This implementation simply calls lookup() and remove(String). Subclasses implementing multiple destinations per hostname, or with more efficient implementations, should override. Fails if entry previously exists.

      Parameters:
      hostname - the host name whose entry holds the destination to remove
      d - the destination that must be present
      options - NamingService-specific, may be null
      Returns:
      true if entry containing d was successfully removed.

    • reverseLookupAll

      public List<String> reverseLookupAll(Hash h)
      Reverse lookup a hash. This implementation returns the result from reverseLookup, or null. Subclasses implementing reverse lookups should override.
      Parameters:
      h - non-null
      Returns:
      a non-empty list of hostnames for this hash, or null if none is known. It is safe for subclasses to always return null if no reverse lookup is possible.

    • reverseLookupAll

      public List<String> reverseLookupAll(Destination dest)
      Reverse lookup a destination This implementation returns reverseLookupAll(dest, null).
      Parameters:
      dest - non-null destination to look up
      Returns:
      a non-empty list of hostnames for this Destination, or null if none is known. It is safe for subclasses to always return null if no reverse lookup is possible.

    • reverseLookupAll

      public List<String> reverseLookupAll(Destination d, Properties options)
      Same as reverseLookupAll(dest) but with options This implementation returns the result from reverseLookup, or null. Subclasses implementing reverse lookups should override.
      Parameters:
      d - non-null
      options - NamingService-specific, can be null
      Returns:
      a non-empty list of hostnames for this Destination, or null

    • isI2PHost

      public static boolean isI2PHost(String hostname)
      Is this an i2p hostname?

      ref: https://www.rfc-editor.org/rfc/rfc9476.html

      Parameters:
      hostname - non-null
      Returns:
      true if hostname (case insensitive) ends with .i2p or .i2p.alt

    • isB32Host

      public static boolean isB32Host(String hostname)
      Is this a b32 hostname? Does NOT validate the base32 part except for length.

      ref: https://www.rfc-editor.org/rfc/rfc9476.html

      Parameters:
      hostname - non-null
      Returns:
      true if hostname (case insensitive) ends with .b32.i2p or .b32.i2p.alt and is long enough. May or may not be blinded.

    • isBlindedHost

      public static boolean isBlindedHost(String hostname)
      Is this a blinded ("b33") hostname? Does NOT validate the base32 part except for length. See Blinding.decode(I2PAppContext, String) for full validation.

      ref: https://www.rfc-editor.org/rfc/rfc9476.html

      Parameters:
      hostname - non-null
      Returns:
      true if hostname (case insensitive) ends with .b32.i2p or .b32.i2p.alt and is long enough.

    • createInstance

      public static final NamingService createInstance(I2PAppContext context)
      WARNING - for use by I2PAppContext only - others must use I2PAppContext.namingService().

      Create a naming service instance, choosing the implementation from the "i2p.naming.impl" system property (defaulting to the router or client implementation according to the context type). This is a factory, not a cache: every call constructs and returns a new instance, and no deduplication happens here. I2PAppContext.namingService() owns the single instance per context, so call this at most once per context.

      Parameters:
      context - the application context
      Returns:
      a new NamingService instance
      Throws:
      RuntimeException - if the naming service cannot be loaded