Package net.i2p.client.naming

Class NamingService

    • 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 hostname.
        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
        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
        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 address)
        If the address 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:
        address - 516+ character Base 64
        Returns:
        Destination or null on error

      • 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 hostnames 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 hostnames (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

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

      • lookupBase32

        public Destination lookupBase32​(String address,
                                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:
        address - 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 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.
        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 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:
        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 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.
        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 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.
        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 hostnames 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!!!