net.i2p.router.naming

## Class BlockfileNamingService

- 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)` 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.
    `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)` Same as reverseLookup(dest) but with options This implementation returns null.
    `String` | `reverseLookup(Hash h)` Reverse lookup a hash.
    `List<String>` | `reverseLookupAll(Destination d, Properties options)` Same as reverseLookupAll(dest) but with options This implementation returns the result from reverseLookup, or null.
    `List<String>` | `reverseLookupAll(Hash h)` Reverse lookup a hash.
    `void` | `shutdown()` Parent will call when removed.
    `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 multple 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 to add the destination to
        `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:
        all mappings (matching the options if non-null) or empty Map if none; Returned Map is not necessarily sorted, implementation dependent

    - #### 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:
        all mappings (matching the options if non-null) or empty Map if none; Returned Map is not necessarily sorted, implementation dependent

    - #### 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:
        all known hostnames (matching the options if non-null) or empty Set if none; Returned Set is not necessarily sorted, implementation dependent

    - #### lookup

          public Destination lookup(String hostname,
                                    Properties lookupOptions,
                                    Properties storedOptions)

      Description copied from class: `NamingService`
      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.
      Overrides:
        `lookup` in class `DummyNamingService`
      Parameters:
        `hostname` - mixed case as it could be a key
        `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

    - #### 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 to look up
      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 to add
        `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 to add
        `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 to remove
        `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 to remove
      Returns:
        true if removed successfully, false on error or if it did not exist

    - #### reverseLookup

          public String reverseLookup(Destination d,
                                      Properties options)

      Description copied from class: `NamingService`
      Same as reverseLookup(dest) but with options This implementation returns null. Subclasses implementing reverse lookups should override.
      Overrides:
        `reverseLookup` in class `NamingService`
      Parameters:
        `options` - ignored
        `d` - non-null destination to look up
      Returns:
        hostname or null

    - #### reverseLookup

          public String reverseLookup(Hash h)

      Description copied from class: `NamingService`
      Reverse lookup a hash. This implementation returns null. Subclasses implementing reverse lookups should override.
      Overrides:
        `reverseLookup` in class `NamingService`
      Parameters:
        `h` - non-null hash to look up
      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.

    - #### reverseLookupAll

          public List<String> reverseLookupAll(Destination d,
                                               Properties options)

      Description copied from class: `NamingService`
      Same as reverseLookupAll(dest) but with options This implementation returns the result from reverseLookup, or null. Subclasses implementing reverse lookups should override.
      Overrides:
        `reverseLookupAll` in class `NamingService`
      Parameters:
        `options` - ignored
        `d` - non-null
      Returns:
        a non-empty list of hostnames for this Destination, or `null`

    - #### reverseLookupAll

          public List<String> reverseLookupAll(Hash h)

      Description copied from class: `NamingService`
      Reverse lookup a hash. This implementation returns the result from reverseLookup, or null. Subclasses implementing reverse lookups should override.
      Overrides:
        `reverseLookupAll` in class `NamingService`
      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.

    - #### shutdown

          public void shutdown()

      Description copied from class: `NamingService`
      Parent will call when removed. If this is the root naming service, the core will stop it. Should not be called by others.
      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