NamingService (Javadocs [I2P+ 2.13.0+]

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` context
`protected Set<NamingServiceListener>`	`_listeners` listeners
`protected Log`	`_log` logger
`protected Set<NamingServiceUpdater>`	`_updaters` 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.

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
```
    context
  - _listeners
```
protected final Set<NamingServiceListener> _listeners
```
    listeners
  - _log
```
protected final Log _log
```
    logger
  - _updaters
```
protected final Set<NamingServiceUpdater> _updaters
```
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    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
    d - may be null if only options are changing
    options - NamingService-specific, can be null
    Returns:
    success

Class NamingService

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

_context

_listeners

_log

_updaters

PROP_IMPL

Constructor Detail

NamingService

Method Detail

addDestination

addDestination

addNamingService

addNamingService

createInstance

export

export

getBase64Entries

getConfiguration

getEntries

getEntries

getName

getNames

getNames

getNamingServices

getParent

isB32Host

isBlindedHost

isI2PHost

lookup

lookup

lookup

lookupAll

lookupAll

lookupBase32

lookupBase64

put

put

putAll

putIfAbsent

putIfAbsent

registerListener

registerUpdater

remove

remove

remove

remove

removeNamingService

requestUpdate

reverseLookup

reverseLookup

reverseLookup

reverseLookupAll

reverseLookupAll

reverseLookupAll

setConfiguration

shutdown

size

size

start

toString

unregisterListener

unregisterUpdater

update