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

  • Method Details

    • 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 lookup a destination This implementation returns reverseLookup(dest, null).
      Parameters:
      dest - non-null
      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)
      Reverse lookup a hash. This implementation returns null. Subclasses implementing reverse lookups should override.
      Parameters:
      h - non-null
      Returns:
      a host name 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 host name 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()
      Overrides:
      toString in class Object

    • getName

      public String getName()
      Returns:
      Class simple name by default
      Since:
      0.8.7

    • getConfiguration

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

    • setConfiguration

      public boolean setConfiguration​(Properties p)
      Warning - unimplemented in any subclass. Returns true always.
      Returns:
      success
      Since:
      0.8.7

    • getNamingServices

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

    • getParent

      public NamingService getParent()
      This implementation returns null. Subclasses implementing chaining should override.
      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
      Since:
      0.8.7

    • addNamingService

      public boolean addNamingService​(NamingService ns, boolean head)
      Only for chaining-capable NamingServices. This implementation returns false. Subclasses implementing chaining should override.
      Parameters:
      head - or tail
      Returns:
      success
      Since:
      0.8.7

    • removeNamingService

      public boolean removeNamingService​(NamingService ns)
      Only for chaining-capable NamingServices. This implementation returns false. Subclasses implementing chaining should override.
      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)
      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
      Since:
      0.8.7

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

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

    • 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
      Since:
      0.8.7, implemented in 0.9.20

    • 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.
      Throws:
      IOException
      Since:
      0.9.20

    • 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:
      options - NamingService-specific, can be null
      Throws:
      IOException
      Since:
      0.9.20

    • 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)
      Add a hostname and Destination to the addressbook. Overwrites old entry if it exists. See also putIfAbsent() and update().
      Returns:
      success
      Since:
      0.8.7

    • 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:
      options - NamingService-specific, can be null
      Returns:
      success
      Since:
      0.8.7

    • 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().
      Returns:
      success
      Since:
      0.8.7

    • 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:
      options - NamingService-specific, can be null
      Returns:
      success
      Since:
      0.8.7

    • 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:
      options - NamingService-specific, can be null
      Returns:
      total success, or false if any put failed
      Since:
      0.8.7

    • 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:
      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)
      Delete the entry.
      Returns:
      true if removed successfully, false on error or if it did not exist
      Since:
      0.8.7

    • remove

      public boolean remove​(String hostname, Properties options)
      Delete the entry.
      Parameters:
      options - NamingService-specific, can be null
      Returns:
      true if removed successfully, false on error or if it did not exist
      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 Base 32 addresses in the form {52 chars}.b32.i2p 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 This implementation returns null. Subclasses implementing reverse lookups should override.
      Parameters:
      d - non-null
      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. 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
      Since:
      0.8.7

    • lookup

      public Destination lookup​(Hash hash, int timeout)
      Same as lookupBase32() but with the SHA256 Hash precalculated This implementation returns null.
      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

    • lookupAll

      public List<Destination> lookupAll​(String hostname)
      For NamingServices that support multiple Destinations for a single host name, 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.
      Returns:
      non-empty List of Destinations, or null if nothing found
      Since:
      0.9.26

    • lookupAll

      public List<Destination> lookupAll​(String hostname, Properties lookupOptions, List<Properties> storedOptions)
      For NamingServices that support multiple Destinations and Properties for a single host name, 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:
      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
      Since:
      0.9.26

    • addDestination

      public boolean addDestination​(String hostname, Destination d)
      Add a Destination to an existing hostname's entry in the addressbook.
      Returns:
      success
      Since:
      0.9.26

    • 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:
      options - NamingService-specific, may be null
      Returns:
      success
      Since:
      0.9.26

    • 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.
      Returns:
      true if entry containing d was successfully removed.
      Since:
      0.9.26

    • 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:
      options - NamingService-specific, may be null
      Returns:
      true if entry containing d was successfully removed.
      Since:
      0.9.26

    • 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 host names for this hash, or null if none is known. It is safe for subclasses to always return null if no reverse lookup is possible.
      Since:
      0.9.26

    • reverseLookupAll

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

    • 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 host names for this Destination, or null
      Since:
      0.9.26

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