BlockfileNamingService (Javadocs [I2P+ 2.13.0+]

java.lang.Object
- net.i2p.client.naming.NamingService
- - net.i2p.client.naming.DummyNamingService
  - - net.i2p.router.naming.BlockfileNamingService

public class BlockfileNamingService
extends DummyNamingService

A naming service using the net.metanotion BlockFile database. This database contains the following skiplists:


 "%%__INFO__%%" is the master database skiplist, containing one entry:
     "info": a Properties, serialized with DataHelper functions:
             "version": "4"
             "created": Java long time (ms)
             "upgraded": Java long time (ms) (as of database version 2)
             "lists":   Comma-separated list of host databases, to be
                        searched in-order for lookups

 "%%__REVERSE__%%" is the reverse lookup skiplist
     (as of database version 2):
     The skiplist keys are Integers, the first 4 bytes of the hash of the dest.
     The skiplist values are Properties.
         There may be multiple entries in the properties, each one is a reverse mapping,
            as there may be more than one hostname for a given destination,
            or there could be collisions with the same first 4 bytes of the hash.
         Each property key is a hostname.
         Each property value is the empty string.

 For each host database, there is a skiplist containing
 the hosts for that database.
 The keys/values in these skiplists are as follows:
      key: a UTF-8 String
      value: a DestEntry, which is:
             a one-byte count of the Properties/Destination pairs to follow
               (as of database version 4, otherwise one)
             that many pairs of:
               Properties (serialized with DataHelper)
               Destination (serialized as usual).


 The DestEntry Properties typically contains:
             "a":   The time added (Java long time in ms)
             "s":   The original source of the entry (typically a file name or subscription URL)
             others TBD

All host names are converted to lower case.

Field Summary
- Fields inherited from class net.i2p.client.naming.DummyNamingService
  BASE32_HASH_LENGTH, CACHE_MAX_SIZE, DEST_SIZE, PROP_B32
- Fields inherited from class net.i2p.client.naming.NamingService
  _context, _listeners, _log, _updaters, PROP_IMPL

Constructor Summary

Constructors
Constructor and Description
`BlockfileNamingService(I2PAppContext context)` Opens the database at hostsdb.blockfile or creates a new one and imports entries from hosts.txt, userhosts.txt, and privatehosts.txt.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`addDestination(String hostname, Destination d, Properties options)` Add a Destination to an existing hostname's entry in the addressbook.
`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.
`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.
`Set<String>`	`getNames(Properties options)` Broken prior to 0.9.62, would only return one name.
`Destination`	`lookup(String hostname, Properties lookupOptions, Properties storedOptions)` Lookup a hostname.
`List<Destination>`	`lookupAll(String hostname, Properties lookupOptions, List<Properties> storedOptions)` Return all of the entries found in the first list found, or in the list specified in lookupOptions.
`static void`	`main(String[] args)` BlockfileNamingService [force] force = force writable
`boolean`	`put(String hostname, Destination d, Properties options)` Add a hostname and Destination to the addressbook.
`boolean`	`putIfAbsent(String hostname, Destination d, Properties options)` Add a hostname and Destination to the addressbook.
`static Properties`	`readProperties(ByteArrayInputStream in)` Same as DataHelper.readProperties, UTF-8, unsorted, except that values may up to 4K bytes.
`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.
`String`	`reverseLookup(Destination d, Properties options)` Look up a hostname from a Destination's hash.
`String`	`reverseLookup(Hash h)` Look up a hostname from a hash.
`List<String>`	`reverseLookupAll(Destination d, Properties options)` Return all hostnames registered for this Destination's hash.
`List<String>`	`reverseLookupAll(Hash h)` Return all hostnames registered for this hash.
`void`	`shutdown()` Shut down the naming service and close the backing store.
`int`	`size(Properties options)` This implementation returns -1.

Methods inherited from class net.i2p.client.naming.DummyNamingService
clearCache, getCache, putCache, removeCache

Methods inherited from class net.i2p.client.naming.NamingService
addDestination, addNamingService, addNamingService, createInstance, export, getConfiguration, getEntries, getName, getNames, getNamingServices, getParent, isB32Host, isBlindedHost, isI2PHost, lookup, lookup, lookupAll, lookupBase32, lookupBase64, put, putAll, putIfAbsent, registerListener, registerUpdater, remove, remove, removeNamingService, requestUpdate, reverseLookup, reverseLookupAll, setConfiguration, size, start, toString, unregisterListener, unregisterUpdater, update

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - BlockfileNamingService
```
public BlockfileNamingService(I2PAppContext context)
```
    Opens the database at hostsdb.blockfile or creates a new one and imports entries from hosts.txt, userhosts.txt, and privatehosts.txt. If not in router context, the database will be opened read-only unless the property i2p.naming.blockfile.writeInAppContext is true. Not designed for multiple instantiations or simultaneous use by multiple JVMs.
    Throws:
    RuntimeException - on fatal error
- Method Detail
  - addDestination
```
public boolean addDestination(String hostname,
                              Destination d,
                              Properties options)
```
    Add a Destination to an existing hostname's entry in the addressbook. This does not prevent adding b32. Caller must check.
    Overrides:
    addDestination in class NamingService
    Parameters:
    options - NamingService-specific, may be null
    hostname - the hostname
    d - the destination to add
    Returns:
    success
  - export
```
public void export(Writer out,
                   Properties options)
            throws IOException
```
    Export in a hosts.txt format. Output is sorted. Caller must close writer.
    Overrides:
    export in class NamingService
    Parameters:
    options - If non-null and contains the key "list", get from that list (default "hosts.txt", NOT all lists) Key "search": return only those matching substring Key "startsWith": return only those starting with ("[0-9]" allowed) Key "beginWith": start here in the iteration
    out - the writer to export to
    Throws:
    IOException - if an I/O error occurs
  - getBase64Entries
```
public Map<String,String> getBase64Entries(Properties options)
```
    Description copied from class: NamingService
    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.
    Overrides:
    getBase64Entries in class NamingService
    Parameters:
    options - If non-null and contains the key "list", get from that list (default "hosts.txt", NOT all lists) Key "skip": skip that many entries Key "limit": max number to return Key "search": return only those matching substring Key "startsWith": return only those starting with ("[0-9]" allowed) Key "beginWith": start here in the iteration Don't use both startsWith and beginWith. Search, startsWith, and beginWith values must be lower case.
    Returns:
    the base64 entries
  - getEntries
```
public Map<String,Destination> getEntries(Properties options)
```
    Description copied from class: NamingService
    Warning - This will bring the whole database into memory if options is null, empty, or unsupported, use with caution.
    Overrides:
    getEntries in class NamingService
    Parameters:
    options - If non-null and contains the key "list", get from that list (default "hosts.txt", NOT all lists) Key "skip": skip that many entries Key "limit": max number to return Key "search": return only those matching substring Key "startsWith": return only those starting with ("[0-9]" allowed) Key "beginWith": start here in the iteration Don't use both startsWith and beginWith. Search, startsWith, and beginWith values must be lower case.
    Returns:
    the entries
  - getNames
```
public Set<String> getNames(Properties options)
```
    Broken prior to 0.9.62, would only return one name.
    Overrides:
    getNames in class NamingService
    Parameters:
    options - If non-null and contains the key "list", get from that list (default "hosts.txt", NOT all lists) Key "skip": skip that many entries Key "limit": max number to return Key "search": return only those matching substring Key "startsWith": return only those starting with ("[0-9]" allowed) Key "beginWith": start here in the iteration Don't use both startsWith and beginWith. Search, startsWith, and beginWith values must be lower case.
    Returns:
    the names
  - lookup
```
public Destination lookup(String hostname,
                          Properties lookupOptions,
                          Properties storedOptions)
```
    Lookup a hostname. Will strip a "www." prefix and retry if lookup fails.
    Overrides:
    lookup in class DummyNamingService
    Parameters:
    hostname - upper/lower case ok
    lookupOptions - If non-null and contains the key "list", lookup in that list only, otherwise all lists
    storedOptions - options for persisting the result (unused)
    Returns:
    the destination, or null if not found
  - lookupAll
```
public List<Destination> lookupAll(String hostname,
                                   Properties lookupOptions,
                                   List<Properties> storedOptions)
```
    Return all of the entries found in the first list found, or in the list specified in lookupOptions. Does not aggregate all destinations found in all lists. 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.
    Overrides:
    lookupAll in class NamingService
    Parameters:
    lookupOptions - input parameter, NamingService-specific, may be null
    storedOptions - output parameter, NamingService-specific, any stored properties will be added if non-null
    hostname - the hostname
    Returns:
    non-empty List of Destinations, or null if nothing found
  - main
```
public static void main(String[] args)
```
    BlockfileNamingService [force] force = force writable
  - put
```
public boolean put(String hostname,
                   Destination d,
                   Properties options)
```
    Description copied from class: NamingService
    Add a hostname and Destination to the addressbook. Overwrites old entry if it exists. See also putIfAbsent() and update().
    Overrides:
    put in class NamingService
    Parameters:
    options - If non-null and contains the key "list", add to that list (default "hosts.txt") Use the key "s" for the source
    hostname - the hostname
    d - the destination for the hostname
    Returns:
    success
  - putIfAbsent
```
public boolean putIfAbsent(String hostname,
                           Destination d,
                           Properties options)
```
    Description copied from class: NamingService
    Add a hostname and Destination to the addressbook. Fails if entry previously exists. See also put() and update().
    Overrides:
    putIfAbsent in class NamingService
    Parameters:
    options - If non-null and contains the key "list", add to that list (default "hosts.txt") Use the key "s" for the source. Key "a" will be added with the current time, unless "a" is present in options.
    hostname - the hostname
    d - the destination for the hostname
    Returns:
    success
  - readProperties
```
public static Properties readProperties(ByteArrayInputStream in)
                                 throws DataFormatException,
                                        IOException
```
    Same as DataHelper.readProperties, UTF-8, unsorted, except that values may up to 4K bytes. Throws DataFormatException on duplicate key
    Parameters:
    in - stream to read the mapping from
    Returns:
    a Properties
    Throws:
    DataFormatException - if the format is invalid
    IOException - if there is a problem reading the data
  - 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.
    Overrides:
    remove in class NamingService
    Parameters:
    options - NamingService-specific, may be null
    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,
                      Properties options)
```
    Description copied from class: NamingService
    Delete the entry.
    Overrides:
    remove in class NamingService
    Parameters:
    options - If non-null and contains the key "list", remove from that list (default "hosts.txt", NOT all lists)
    hostname - the hostname
    Returns:
    true if removed successfully, false on error or if it did not exist
  - reverseLookup
```
public String reverseLookup(Destination d,
                            Properties options)
```
    Look up a hostname from a Destination's hash. Returns the first name found, or null.
    Overrides:
    reverseLookup in class NamingService
    Parameters:
    options - to configure lookup behavior (unused)
    d - non-null destination to look up
    Returns:
    hostname or null
  - reverseLookup
```
public String reverseLookup(Hash h)
```
    Look up a hostname from a hash. Returns the first name found, or null.
    Overrides:
    reverseLookup in class NamingService
    Parameters:
    h - the hash to look up
    Returns:
    the first hostname, or null if none
  - reverseLookupAll
```
public List<String> reverseLookupAll(Destination d,
                                     Properties options)
```
    Return all hostnames registered for this Destination's hash.
    Overrides:
    reverseLookupAll in class NamingService
    Parameters:
    options - to configure lookup behavior (unused)
    d - non-null
    Returns:
    a non-empty list of hostnames for this Destination, or null
  - reverseLookupAll
```
public List<String> reverseLookupAll(Hash h)
```
    Return all hostnames registered for this hash.
    Overrides:
    reverseLookupAll in class NamingService
    Parameters:
    h - the hash to look up
    Returns:
    the list of hostnames, or null if none
  - shutdown
```
public void shutdown()
```
    Shut down the naming service and close the backing store.
    Overrides:
    shutdown in class NamingService
  - size
```
public int size(Properties options)
```
    Description copied from class: NamingService
    This implementation returns -1. Most subclasses should override.
    Overrides:
    size in class NamingService
    Parameters:
    options - If non-null and contains the key "list", return the size of that list (default "hosts.txt", NOT all lists)
    Returns:
    number of entries (matching the options if non-null) or -1 if unknown

Class BlockfileNamingService

Field Summary

Fields inherited from class net.i2p.client.naming.DummyNamingService

Fields inherited from class net.i2p.client.naming.NamingService

Constructor Summary

Method Summary

Methods inherited from class net.i2p.client.naming.DummyNamingService

Methods inherited from class net.i2p.client.naming.NamingService

Methods inherited from class java.lang.Object

Constructor Detail

BlockfileNamingService

Method Detail

addDestination

export

getBase64Entries

getEntries

getNames

lookup

lookupAll

main

put

putIfAbsent

readProperties

remove

remove

reverseLookup

reverseLookup

reverseLookupAll

reverseLookupAll

shutdown

size