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

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `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)` Get a naming service instance.
    `Map<String,String>` | `getBase64Entries(Properties options)` This may be more or less efficient than getEntries()
    `Properties` | `getConfiguration()`
    `Map<String,Destination>` | `getEntries()`
    `Map<String,Destination>` | `getEntries(Properties options)`
    `String` | `getName()`
    `Set<String>` | `getNames()`
    `Set<String>` | `getNames(Properties options)`
    `List<NamingService>` | `getNamingServices()`
    `NamingService` | `getParent()`
    `Destination` | `lookup(Hash hash, int timeout)` Same as lookupB32 but with the SHA256 Hash precalculated
    `Destination` | `lookup(String hostname)` Look up a host name.
    `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 B32 addresses is NamingService-specific.
    `Destination` | `lookupBase32(String hostname, int timeout)` Lookup a Base 32 address.
    `protected Destination` | `lookupBase64(String hostname)` Check if host name is valid Base64 encoded dest and return this dest in that case.
    `boolean` | `put(String hostname, Destination d)`
    `boolean` | `put(String hostname, Destination d, Properties options)`
    `boolean` | `putAll(Map<String,Destination> entries, Properties options)`
    `boolean` | `putIfAbsent(String hostname, Destination d)` Fails if entry previously exists
    `boolean` | `putIfAbsent(String hostname, Destination d, Properties options)` Fails if entry previously exists
    `void` | `registerListener(NamingServiceListener nsl)`
    `void` | `registerUpdater(NamingServiceUpdater nsu)`
    `boolean` | `remove(String hostname)`
    `boolean` | `remove(String hostname, Properties options)`
    `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 look up a destination
    `String` | `reverseLookup(Destination d, Properties options)` Same as reverseLookup(dest) but with options
    `String` | `reverseLookup(Hash h)` Deprecated. unused
    `boolean` | `setConfiguration(Properties p)`
    `void` | `shutdown()` Parent will call when removed.
    `int` | `size()`
    `int` | `size(Properties options)`
    `void` | `start()` Parent will call when added.
    `String` | `toString()`
    `void` | `unregisterListener(NamingServiceListener nsl)`
    `void` | `unregisterUpdater(NamingServiceUpdater nsu)`
    `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

    - #### _log

          protected final Log _log

    - #### _context

          protected final I2PAppContext _context

    - #### _listeners

          protected final Set<NamingServiceListener> _listeners

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

  - ### Method Detail

    - #### lookup

          public Destination lookup(String hostname)

      Look up a host name.
      Returns:
        the Destination for this host name, or `null` if name is unknown.

    - #### reverseLookup

          public String reverseLookup(Destination dest)

      Reverse look up a destination
      Returns:
        a host name 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)

      Deprecated. unused

    - #### lookupBase64

          protected Destination lookupBase64(String hostname)

      Check if host name is valid Base64 encoded dest and return this dest in that case. Useful as a "fallback" in custom naming implementations.

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`

    - #### getName

          public String getName()

      Returns:
        Class simple name by default
      Since:
        0.8.7

    - #### getConfiguration

          public Properties getConfiguration()

      Returns:
        NamingService-specific options or null
      Since:
        0.8.7

    - #### setConfiguration

          public boolean setConfiguration(Properties p)

      Returns:
        success
      Since:
        0.8.7

    - #### getNamingServices

          public List<NamingService> getNamingServices()

      Returns:
        chained naming services or null
      Since:
        0.8.7

    - #### getParent

          public NamingService getParent()

      Returns:
        parent naming service or null if this is the root
      Since:
        0.8.7

    - #### addNamingService

          public boolean addNamingService(NamingService ns)

      Only for chaining-capable NamingServices. Add to end of the list.
      Returns:
        success

    - #### addNamingService

          public boolean addNamingService(NamingService ns,
                                 boolean head)

      Only for chaining-capable NamingServices
      Parameters:
        `head` - or tail
      Returns:
        success

    - #### removeNamingService

          public boolean removeNamingService(NamingService ns)

      Only for chaining-capable NamingServices
      Returns:
        success
      Since:
        0.8.7

    - #### size

          public int size()

      Returns:
        number of entries or -1 if unknown
      Since:
        0.8.7

    - #### size

          public int size(Properties options)

      Parameters:
        `options` - NamingService-specific, can be null
      Returns:
        number of entries (matching the options if non-null) or -1 if unknown
      Since:
        0.8.7

    - #### getEntries

          public Map<String,Destination> getEntries()

      Returns:
        all mappings or empty Map if none; Returned Map is not necessarily sorted, implementation dependent
      Since:
        0.8.7

    - #### getEntries

          public Map<String,Destination> getEntries(Properties options)

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

    - #### getBase64Entries

          public Map<String,String> getBase64Entries(Properties options)

      This may be more or less efficient than getEntries()
      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
      Since:
        0.8.7

    - #### getNames

          public Set<String> getNames()

      Returns:
        all known host names or empty Set if none; Returned Set is not necessarily sorted, implementation dependent
      Since:
        0.8.7

    - #### getNames

          public Set<String> getNames(Properties options)

      Parameters:
        `options` - NamingService-specific, can be null
      Returns:
        all known host names (matching the options if non-null) or empty Set if none; Returned Set is not necessarily sorted, implementation dependent
      Since:
        0.8.7

    - #### put

          public boolean put(String hostname,
                    Destination d)

      Returns:
        success
      Since:
        0.8.7

    - #### put

          public boolean put(String hostname,
                    Destination d,
                    Properties options)

      Parameters:
        `options` - NamingService-specific, can be null
      Returns:
        success
      Since:
        0.8.7

    - #### putIfAbsent

          public boolean putIfAbsent(String hostname,
                            Destination d)

      Fails if entry previously exists
      Returns:
        success
      Since:
        0.8.7

    - #### putIfAbsent

          public boolean putIfAbsent(String hostname,
                            Destination d,
                            Properties options)

      Fails if entry previously exists
      Parameters:
        `options` - NamingService-specific, can be null
      Returns:
        success
      Since:
        0.8.7

    - #### putAll

          public boolean putAll(Map<String,Destination> entries,
                       Properties options)

      Parameters:
        `options` - NamingService-specific, can be null
      Returns:
        success
      Since:
        0.8.7

    - #### update

          public boolean update(String hostname,
                       Destination d,
                       Properties options)

      Fails if entry did not previously exist
      Parameters:
        `d` - may be null if only options are changing
        `options` - NamingService-specific, can be null
      Returns:
        success
      Since:
        0.8.7

    - #### remove

          public boolean remove(String hostname)

      Returns:
        success
      Since:
        0.8.7

    - #### remove

          public boolean remove(String hostname,
                       Properties options)

      Parameters:
        `options` - NamingService-specific, can be null
      Returns:
        success
      Since:
        0.8.7

    - #### requestUpdate

          public void requestUpdate(Properties options)

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

    - #### registerListener

          public void registerListener(NamingServiceListener nsl)

      Since:
        0.8.7

    - #### unregisterListener

          public void unregisterListener(NamingServiceListener nsl)

      Since:
        0.8.7

    - #### registerUpdater

          public void registerUpdater(NamingServiceUpdater nsu)

      Since:
        0.8.7

    - #### unregisterUpdater

          public void unregisterUpdater(NamingServiceUpdater nsu)

      Since:
        0.8.7

    - #### 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 B32 addresses is NamingService-specific.
      Parameters:
        `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
      Since:
        0.8.7

    - #### reverseLookup

          public String reverseLookup(Destination d,
                             Properties options)

      Same as reverseLookup(dest) but with options
      Parameters:
        `options` - NamingService-specific, can be null
      Returns:
        host name or null
      Since:
        0.8.7

    - #### 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.
      Parameters:
        `hostname` - must be {52 chars}.b32.i2p
        `timeout` - in seconds; <= 0 means use router default
      Returns:
        dest or null
      Since:
        0.8.7

    - #### lookup

          public Destination lookup(Hash hash,
                           int timeout)

      Same as lookupB32 but with the SHA256 Hash precalculated
      Parameters:
        `timeout` - in seconds; <= 0 means use router default
      Returns:
        dest or null
      Since:
        0.8.7

    - #### 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.
      Since:
        0.8.7

    - #### 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.
      Since:
        0.8.7

    - #### createInstance

          public static final NamingService createInstance(I2PAppContext context)

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