Package net.i2p.client.naming
Class NamingService
java.lang.Object
net.i2p.client.naming.NamingService
- Direct Known Subclasses:
DummyNamingService
,SingleFileNamingService
Naming services create a subclass of this class.
-
Field Summary
Modifier and TypeFieldDescriptionprotected final I2PAppContext
protected final Set<NamingServiceListener>
protected final Log
protected final Set<NamingServiceUpdater>
static final String
what classname should be used as the naming service impl? -
Constructor Summary
ModifierConstructorDescriptionprotected
NamingService
(I2PAppContext context) The naming service should only be constructed and accessed through the application context. -
Method Summary
Modifier and TypeMethodDescriptionboolean
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
Only for chaining-capable NamingServices.boolean
addNamingService
(NamingService ns, boolean head) Only for chaining-capable NamingServices.static final NamingService
createInstance
(I2PAppContext context) WARNING - for use by I2PAppContext only - others must use I2PAppContext.namingService() Get a naming service instance.void
Export in a hosts.txt format.void
export
(Writer out, Properties options) Export in a hosts.txt format.getBase64Entries
(Properties options) This may be more or less efficient than getEntries(), depending on the implementation.Warning - unimplemented in any subclass.Warning - This obviously brings the whole database into memory, so use is discouraged.getEntries
(Properties options) Warning - This will bring the whole database into memory if options is null, empty, or unsupported, use with caution.getName()
getNames()
getNames
(Properties options) This implementation returns null.This implementation returns null.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.Same as lookupBase32() but with the SHA256 Hash precalculated This implementation returns null.For NamingServices that support multiple Destinations for a single hostname, return all of them.lookupAll
(String hostname, Properties lookupOptions, List<Properties> storedOptions) For NamingServices that support multiple Destinations and Properties for a single hostname, return all of them.lookupBase32
(String address, int timeout) Lookup a Base 32 address.protected Destination
lookupBase64
(String address) If the address 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
void
boolean
Delete the entry.boolean
remove
(String hostname, Properties options) 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
Only for chaining-capable NamingServices.void
requestUpdate
(Properties options) Ask any registered updaters to update nowreverseLookup
(Destination dest) Reverse lookup a destination This implementation returns reverseLookup(dest, null).reverseLookup
(Destination d, Properties options) Same as reverseLookup(dest) but with options This implementation returns null.Reverse lookup a hash.reverseLookupAll
(Destination dest) Reverse lookup a destination This implementation returns reverseLookupAll(dest, null).reverseLookupAll
(Destination d, Properties options) Same as reverseLookupAll(dest) but with options This implementation returns the result from reverseLookup, or null.Reverse lookup a hash.boolean
Warning - unimplemented in any subclass.void
shutdown()
Parent will call when removed.int
size()
int
size
(Properties options) This implementation returns -1.void
start()
Parent will call when added.toString()
void
void
boolean
update
(String hostname, Destination d, Properties options) Fails if entry did not previously exist.
-
Field Details
-
_log
-
_context
-
_listeners
-
_updaters
-
PROP_IMPL
what classname should be used as the naming service impl?- See Also:
-
-
Constructor Details
-
NamingService
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
Look up a hostname.- Returns:
- the Destination for this hostname, or
null
if name is unknown.
-
reverseLookup
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 returnnull
if no reverse lookup is possible.
-
reverseLookup
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 returnnull
if no reverse lookup is possible.
-
lookupBase64
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
-
toString
-
getName
- Returns:
- Class simple name by default
- Since:
- 0.8.7
-
getConfiguration
Warning - unimplemented in any subclass. Returns null always.- Returns:
- NamingService-specific options or null
- Since:
- 0.8.7
-
setConfiguration
Warning - unimplemented in any subclass. Returns true always.- Returns:
- success
- Since:
- 0.8.7
-
getNamingServices
This implementation returns null. Subclasses implementing chaining should override.- Returns:
- chained naming services or null
- Since:
- 0.8.7
-
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
Only for chaining-capable NamingServices. Add to end of the list.- Returns:
- success
- Since:
- 0.8.7
-
addNamingService
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
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
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
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
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
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
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
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
- Returns:
- all known hostnames or empty Set if none; Returned Set is not necessarily sorted, implementation dependent
- Since:
- 0.8.7
-
getNames
- 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
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
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
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
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
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
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 changingoptions
- NamingService-specific, can be null- Returns:
- success
- Since:
- 0.8.7
-
remove
Delete the entry.- Returns:
- true if removed successfully, false on error or if it did not exist
- Since:
- 0.8.7
-
remove
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
Ask any registered updaters to update now- Parameters:
options
- NamingService- or updater-specific, may be null- Since:
- 0.8.7
-
registerListener
- Since:
- 0.8.7
-
unregisterListener
- Since:
- 0.8.7
-
registerUpdater
- Since:
- 0.8.7
-
unregisterUpdater
- 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 nullstoredOptions
- output parameter, NamingService-specific, any stored properties will be added if non-null- Returns:
- dest or null
- Since:
- 0.8.7
-
reverseLookup
Same as reverseLookup(dest) but with options This implementation returns null. Subclasses implementing reverse lookups should override.- Parameters:
d
- non-nulloptions
- NamingService-specific, can be null- Returns:
- hostname or null
- Since:
- 0.8.7
-
lookupBase32
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.i2ptimeout
- in seconds; <= 0 means use router default- Returns:
- dest or null
- Since:
- 0.8.7
-
lookup
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
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 nullstoredOptions
- 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
Add a Destination to an existing hostname's entry in the addressbook.- Returns:
- success
- Since:
- 0.9.26
-
addDestination
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
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
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
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 returnnull
if no reverse lookup is possible. - Since:
- 0.9.26
-
reverseLookupAll
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 returnnull
if no reverse lookup is possible. - Since:
- 0.9.26
-
reverseLookupAll
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-nulloptions
- NamingService-specific, can be null- Returns:
- a non-empty list of hostnames for this Destination, or
null
- Since:
- 0.9.26
-
createInstance
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!!!
-