net.i2p.client.naming

## Class NamingService

- java.lang.Object
- - net.i2p.client.naming.NamingService

- Direct Known Subclasses:
    DummyNamingService, SingleFileNamingService

      public abstract class NamingService
      extends Object

  Naming services create a subclass of this class.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected I2PAppContext` | `_context`
    `protected Set<NamingServiceListener>` | `_listeners`
    `protected Log` | `_log`
    `protected Set<NamingServiceUpdater>` | `_updaters`
    `static String` | `PROP_IMPL` what classname should be used as the naming service impl?

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `NamingService(I2PAppContext context)` The naming service should only be constructed and accessed through the application context.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addDestination(String hostname, Destination d)` Add a Destination to an existing hostname's entry in the addressbook.
    `boolean` | `addDestination(String hostname, Destination d, Properties options)` Add a Destination to an existing hostname's entry in the addressbook.
    `boolean` | `addNamingService(NamingService ns)` Only for chaining-capable NamingServices.
    `boolean` | `addNamingService(NamingService ns, boolean head)` Only for chaining-capable NamingServices.
    `static NamingService` | `createInstance(I2PAppContext context)` WARNING - for use by I2PAppContext only - others must use I2PAppContext.namingService() Get a naming service instance.
    `void` | `export(Writer out)` Export in a hosts.txt format.
    `void` | `export(Writer out, Properties options)` Export in a hosts.txt format.
    `Map<String,String>` | `getBase64Entries(Properties options)` This may be more or less efficient than getEntries(), depending on the implementation.
    `Properties` | `getConfiguration()` Warning - unimplemented in any subclass.
    `Map<String,Destination>` | `getEntries()` Warning - This obviously brings the whole database into memory, so use is discouraged.
    `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.
    `String` | `getName()` Get the name of this naming service.
    `Set<String>` | `getNames()` Get all known hostnames.
    `Set<String>` | `getNames(Properties options)` Get all known hostnames matching the specified options.
    `List<NamingService>` | `getNamingServices()` This implementation returns null.
    `NamingService` | `getParent()` This implementation returns null.
    `static boolean` | `isB32Host(String hostname)` Is this a b32 hostname? Does NOT validate the base32 part except for length.
    `static boolean` | `isBlindedHost(String hostname)` Is this a blinded ("b33") hostname? Does NOT validate the base32 part except for length.
    `static boolean` | `isI2PHost(String hostname)` Is this an i2p hostname? ref: https://www.rfc-editor.org/rfc/rfc9476.html
    `Destination` | `lookup(Hash hash, int timeout)` Same as lookupBase32() but with the SHA256 Hash precalculated This implementation returns null.
    `Destination` | `lookup(String hostname)` Look up a hostname.
    `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.
    `List<Destination>` | `lookupAll(String hostname)` For NamingServices that support multiple Destinations for a single hostname, return all of them.
    `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.
    `Destination` | `lookupBase32(String hostname, int timeout)` Lookup a Base 32 address.
    `protected Destination` | `lookupBase64(String hostname)` If the hostname is a valid Base64 encoded destination, return the decoded Destination.
    `boolean` | `put(String hostname, Destination d)` Add a hostname and Destination to the addressbook.
    `boolean` | `put(String hostname, Destination d, Properties options)` Add a hostname and Destination to the addressbook.
    `boolean` | `putAll(Map<String,Destination> entries, Properties options)` Put all the entries, each with the given options.
    `boolean` | `putIfAbsent(String hostname, Destination d)` Add a hostname and Destination to the addressbook.
    `boolean` | `putIfAbsent(String hostname, Destination d, Properties options)` Add a hostname and Destination to the addressbook.
    `void` | `registerListener(NamingServiceListener nsl)` Register a listener for naming service changes.
    `void` | `registerUpdater(NamingServiceUpdater nsu)` Register an updater for the naming service.
    `boolean` | `remove(String hostname)` Delete the entry.
    `boolean` | `remove(String hostname, Destination d)` Remove a hostname's entry only if it contains the Destination d.
    `boolean` | `remove(String hostname, Destination d, Properties options)` Remove a hostname's entry only if it contains the Destination d.
    `boolean` | `remove(String hostname, Properties options)` Delete the entry.
    `boolean` | `removeNamingService(NamingService ns)` Only for chaining-capable NamingServices.
    `void` | `requestUpdate(Properties options)` Ask any registered updaters to update now
    `String` | `reverseLookup(Destination dest)` Reverse lookup a destination.
    `String` | `reverseLookup(Destination d, Properties options)` Same as reverseLookup(dest) but with options This implementation returns null.
    `String` | `reverseLookup(Hash h)` Reverse lookup a hash.
    `List<String>` | `reverseLookupAll(Destination dest)` Reverse lookup a destination This implementation returns reverseLookupAll(dest, null).
    `List<String>` | `reverseLookupAll(Destination d, Properties options)` Same as reverseLookupAll(dest) but with options This implementation returns the result from reverseLookup, or null.
    `List<String>` | `reverseLookupAll(Hash h)` Reverse lookup a hash.
    `boolean` | `setConfiguration(Properties p)` Warning - unimplemented in any subclass.
    `void` | `shutdown()` Parent will call when removed.
    `int` | `size()` Get the number of entries in this naming service.
    `int` | `size(Properties options)` This implementation returns -1.
    `void` | `start()` Parent will call when added.
    `String` | `toString()` Returns a string representation of this naming service.
    `void` | `unregisterListener(NamingServiceListener nsl)` Unregister a listener for naming service changes.
    `void` | `unregisterUpdater(NamingServiceUpdater nsu)` Unregister an updater for the naming service.
    `boolean` | `update(String hostname, Destination d, Properties options)` Fails if entry did not previously exist.

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

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

- - ### Field Detail

    - #### _context

          protected final I2PAppContext _context

    - #### _listeners

          protected final Set<NamingServiceListener> _listeners

    - #### _log

          protected final Log _log

    - #### _updaters

          protected final Set<NamingServiceUpdater> _updaters

    - #### PROP_IMPL

          public static final String PROP_IMPL

      what classname should be used as the naming service impl?
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### 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 Detail

    - #### addDestination

          public boolean addDestination(String hostname,
                                        Destination d)

      Add a Destination to an existing hostname's entry in the addressbook.
      Parameters:
        `hostname` - the hostname to add the destination to
        `d` - the destination to add
      Returns:
        success

    - #### 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 hostname to add the destination to
        `d` - the destination to add
        `options` - NamingService-specific, may be null
      Returns:
        success

    - #### 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:
        success

    - #### 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` - or tail
      Returns:
        success

    - #### createInstance

          public static final NamingService createInstance(I2PAppContext context)

      WARNING - for use by I2PAppContext only - others must use I2PAppContext.namingService() Get a naming service instance. This method ensures that there will be only one naming service instance (singleton) as well as choose the implementation from the "i2p.naming.impl" system property. FIXME Actually, it doesn't ensure that. Only call this once!!!
      Parameters:
        `context` - the application context
      Returns:
        a NamingService instance
      Throws:
        `RuntimeException` - if the naming service cannot be loaded

    - #### 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(). 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

    - #### 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

    - #### getConfiguration

          public Properties getConfiguration()

      Warning - unimplemented in any subclass. Returns null always.
      Returns:
        NamingService-specific options or null

    - #### getEntries

          public Map<String,Destination> getEntries()

      Warning - This obviously brings the whole database into memory, so use is discouraged.
      Returns:
        all mappings 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

    - #### getName

          public String getName()

      Get the name of this naming service.
      Returns:
        Class simple name by default

    - #### getNames

          public Set<String> getNames()

      Get 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)

      Get 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

    - #### getNamingServices

          public List<NamingService> getNamingServices()

      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

    - #### 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() 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.

    - #### 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

    - #### lookup

          public Destination lookup(Hash hash,
                                    int timeout)

      Same as lookupBase32() 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

    - #### lookup

          public Destination lookup(String hostname)

      Look up a hostname.
      Parameters:
        `hostname` - the hostname to look up
      Returns:
        the Destination for this hostname, or `null` if name is unknown.

    - #### 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 hostname to look up
        `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

    - #### 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 hostname to look up
      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(). Subclasses implementing multiple destinations per hostname should override.
      Parameters:
        `hostname` - the hostname to look up
        `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

    - #### 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

    - #### 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

    - #### 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() and update().
      Parameters:
        `hostname` - the hostname to add
        `d` - the destination for the hostname
      Returns:
        success

    - #### 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().
      Parameters:
        `hostname` - the hostname to add
        `d` - the destination for the hostname
        `options` - NamingService-specific, can be null
      Returns:
        success

    - #### 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` - the entries to add
        `options` - NamingService-specific, can be null
      Returns:
        total success, or false if any put failed

    - #### 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 hostname to add
        `d` - the destination for the hostname
      Returns:
        success

    - #### 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 hostname to add
        `d` - the destination for the hostname
        `options` - NamingService-specific, can be null
      Returns:
        success

    - #### registerListener

          public void registerListener(NamingServiceListener nsl)

      Register a listener for naming service changes.
      Parameters:
        `nsl` - the listener to register

    - #### registerUpdater

          public void registerUpdater(NamingServiceUpdater nsu)

      Register an updater for the naming service.
      Parameters:
        `nsu` - the updater to register

    - #### remove

          public boolean remove(String hostname)

      Delete the entry.
      Parameters:
        `hostname` - the hostname to remove
      Returns:
        true if removed successfully, false on error or if it did not exist

    - #### 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 aditional Destinations remain, it only removes the specified Destination from the entry.
      Parameters:
        `hostname` - the hostname 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 aditional Destinations remain, it only removes the specified Destination from the entry. This implementation simply calls lookup() and remove(). Subclasses implementing multiple destinations per hostname, or with more efficient implementations, should override. Fails if entry previously exists.
      Parameters:
        `hostname` - the hostname to remove
        `d` - the destination that must be present
        `options` - NamingService-specific, may be null
      Returns:
        true if entry containing d was successfully removed.

    - #### remove

          public boolean remove(String hostname,
                                Properties options)

      Delete the entry.
      Parameters:
        `hostname` - the hostname to remove
        `options` - NamingService-specific, can be null
      Returns:
        true if removed successfully, false on error or if it did not exist

    - #### 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:
        success

    - #### requestUpdate

          public void requestUpdate(Properties options)

      Ask any registered updaters to update now
      Parameters:
        `options` - NamingService- or updater-specific, may be null

    - #### 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(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

    - #### 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.

    - #### 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`

    - #### 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.

    - #### setConfiguration

          public boolean setConfiguration(Properties p)

      Warning - unimplemented in any subclass. Returns true always.
      Parameters:
        `p` - the properties to set
      Returns:
        success

    - #### 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.

    - #### size

          public int size()

      Get 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

    - #### 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.

    - #### toString

          public String toString()

      Returns a string representation of this naming service.
      Overrides:
        `toString` in class `Object`
      Returns:
        the class simple name

    - #### unregisterListener

          public void unregisterListener(NamingServiceListener nsl)

      Unregister a listener for naming service changes.
      Parameters:
        `nsl` - the listener to unregister

    - #### unregisterUpdater

          public void unregisterUpdater(NamingServiceUpdater nsu)

      Unregister an updater for the naming service.
      Parameters:
        `nsu` - the updater to unregister

    - #### 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 hostname to update
        `d` - may be null if only options are changing
        `options` - NamingService-specific, can be null
      Returns:
        success