Changeset e9cf4c2


Ignore:
Timestamp:
Apr 19, 2016 3:11:37 PM (4 years ago)
Author:
zzz <zzz@…>
Branches:
master
Children:
1a8847d
Parents:
25bce10
Message:

NamingService?: Add new API methods for multiple Destinations per hostname
Improve javadocs

File:
1 edited

Legend:

Unmodified
Added
Removed
  • core/java/src/net/i2p/client/naming/NamingService.java

    r25bce10 re9cf4c2  
    6565    /**
    6666     * Reverse lookup a destination
     67     * This implementation returns reverseLookup(dest, null).
     68     *
    6769     * @param dest non-null
    6870     * @return a host name for this Destination, or <code>null</code>
     
    7577
    7678    /**
    77      * Reverse lookup a hash
     79     * Reverse lookup a hash.
     80     * This implementation returns null.
     81     * Subclasses implementing reverse lookups should override.
     82     *
    7883     * @param h non-null
    7984     * @return a host name for this hash, or <code>null</code>
     
    8489
    8590    /**
    86      * Check if host name is valid Base64 encoded dest and return this
    87      * dest in that case. Useful as a "fallback" in custom naming
     91     * If the host name is a valid Base64 encoded destination, return the
     92     * decoded Destination. Useful as a "fallback" in custom naming
    8893     * implementations.
    8994     * This is misnamed as it isn't a "lookup" at all, but
     
    121126    /**
    122127     *  Warning - unimplemented in any subclass.
     128     *  Returns null always.
    123129     *
    124130     *  @return NamingService-specific options or null
     
    131137    /**
    132138     *  Warning - unimplemented in any subclass.
     139     *  Returns true always.
    133140     *
    134141     *  @return success
     
    142149
    143150    /**
     151     *  This implementation returns null.
     152     *  Subclasses implementing chaining should override.
     153     *
    144154     *  @return chained naming services or null
    145155     *  @since 0.8.7
     
    150160
    151161    /**
     162     *  This implementation returns null.
     163     *  Subclasses implementing chaining should override.
     164     *
    152165     *  @return parent naming service or null if this is the root
    153166     *  @since 0.8.7
     
    168181
    169182    /**
    170      * Only for chaining-capable NamingServices
     183     * Only for chaining-capable NamingServices.
     184     * This implementation returns false.
     185     * Subclasses implementing chaining should override.
     186     *
    171187     * @param head or tail
    172188     * @return success
     
    178194
    179195    /**
    180      *  Only for chaining-capable NamingServices
     196     * Only for chaining-capable NamingServices.
     197     * This implementation returns false.
     198     * Subclasses implementing chaining should override.
     199     *
    181200     *  @return success
    182201     *  @since 0.8.7
     
    199218
    200219    /**
     220     *  This implementation returns -1.
     221     *  Most subclasses should override.
     222     *
    201223     *  @param options NamingService-specific, can be null
    202224     *  @return number of entries (matching the options if non-null) or -1 if unknown
     
    341363
    342364    /**
     365     *  Add a hostname and Destination to the addressbook.
     366     *  Overwrites old entry if it exists.
     367     *  See also putIfAbsent() and update().
     368     *
    343369     *  @return success
    344370     *  @since 0.8.7
     
    349375
    350376    /**
     377     *  Add a hostname and Destination to the addressbook.
     378     *  Overwrites old entry if it exists.
     379     *  See also putIfAbsent() and update().
     380     *
    351381     *  @param options NamingService-specific, can be null
    352382     *  @return success
     
    358388
    359389    /**
    360      *  Fails if entry previously exists
     390     *  Add a hostname and Destination to the addressbook.
     391     *  Fails if entry previously exists.
     392     *  See also put() and update().
     393     *
    361394     *  @return success
    362395     *  @since 0.8.7
     
    367400
    368401    /**
    369      *  Fails if entry previously exists
     402     *  Add a hostname and Destination to the addressbook.
     403     *  Fails if entry previously exists.
     404     *  See also put() and update().
     405     *
    370406     *  @param options NamingService-specific, can be null
    371407     *  @return success
     
    377413
    378414    /**
    379      *  @param options NamingService-specific, can be null
    380      *  @return success
     415     *  Put all the entries, each with the given options.
     416     *  This implementation calls put() for each entry.
     417     *  Subclasses may override if a more efficient implementation is available.
     418     *
     419     *  @param options NamingService-specific, can be null
     420     *  @return total success, or false if any put failed
    381421     *  @since 0.8.7
    382422     */
     
    393433     *  Fails if entry did not previously exist.
    394434     *  Warning - unimplemented in any subclass.
     435     *  This implementation returns false.
    395436     *
    396437     *  @param d may be null if only options are changing
     
    404445
    405446    /**
    406      *  @return success
     447     *  Delete the entry.
     448     *  @return true if removed successfully, false on error or if it did not exist
    407449     *  @since 0.8.7
    408450     */
    409451    public boolean remove(String hostname) {
    410         return remove(hostname, null);
    411     }
    412 
    413     /**
    414      *  @param options NamingService-specific, can be null
    415      *  @return success
     452        return remove(hostname, (Properties) null);
     453    }
     454
     455    /**
     456     *  Delete the entry.
     457     *  @param options NamingService-specific, can be null
     458     *  @return true if removed successfully, false on error or if it did not exist
    416459     *  @since 0.8.7
    417460     */
     
    461504    /**
    462505     *  Same as lookup(hostname) but with in and out options
    463      *  Note that whether this (and lookup(hostname)) resolve B32 addresses is
    464      *  NamingService-specific.
     506     *  Note that whether this (and lookup(hostname)) resolve Base 32 addresses
     507     *  in the form {52 chars}.b32.i2p is NamingService-specific.
     508     *
    465509     *  @param lookupOptions input parameter, NamingService-specific, can be null
    466510     *  @param storedOptions output parameter, NamingService-specific, any stored properties will be added if non-null
     
    472516    /**
    473517     *  Same as reverseLookup(dest) but with options
     518     *  This implementation returns null.
     519     *  Subclasses implementing reverse lookups should override.
     520     *
    474521     *  @param d non-null
    475522     *  @param options NamingService-specific, can be null
     
    484531     *  Lookup a Base 32 address. This may require the router to fetch the LeaseSet,
    485532     *  which may take quite a while.
     533     *  This implementation returns null.
     534     *  See also lookup(Hash, int).
     535     *
    486536     *  @param hostname must be {52 chars}.b32.i2p
    487537     *  @param timeout in seconds; <= 0 means use router default
     
    494544
    495545    /**
    496      *  Same as lookupB32 but with the SHA256 Hash precalculated
     546     *  Same as lookupBase32() but with the SHA256 Hash precalculated
     547     *  This implementation returns null.
     548     *
    497549     *  @param timeout in seconds; <= 0 means use router default
    498550     *  @return dest or null
     
    520572
    521573    //// End New API
     574
     575    //// Begin new API for multiple Destinations
     576
     577    /**
     578     *  For NamingServices that support multiple Destinations for a single host name,
     579     *  return all of them.
     580     *
     581     *  It is recommended that the returned list is in order of priority, highest-first,
     582     *  but this is NamingService-specific.
     583     *
     584     *  Not recommended for resolving Base 32 addresses;
     585     *  whether this does resolve Base 32 addresses
     586     *  in the form {52 chars}.b32.i2p is NamingService-specific.
     587     *
     588     *  @return non-empty List of Destinations, or null if nothing found
     589     *  @since 0.9.26
     590     */
     591    public List<Destination> lookupAll(String hostname) {
     592        return lookupAll(hostname, null, null);
     593    }
     594
     595    /**
     596     *  For NamingServices that support multiple Destinations and Properties for a single host name,
     597     *  return all of them.
     598     *
     599     *  It is recommended that the returned list is in order of priority, highest-first,
     600     *  but this is NamingService-specific.
     601     *
     602     *  If storedOptions is non-null, it must be a List that supports null entries.
     603     *  If the returned value (the List of Destinations) is non-null,
     604     *  the same number of Properties objects will be added to storedOptions.
     605     *  If no properties were found for a given Destination, the corresponding
     606     *  entry in the storedOptions list will be null.
     607     *
     608     *  Not recommended for resolving Base 32 addresses;
     609     *  whether this does resolve Base 32 addresses
     610     *  in the form {52 chars}.b32.i2p is NamingService-specific.
     611     *
     612     *  This implementation simply calls lookup().
     613     *  Subclasses implementing multiple destinations per hostname should override.
     614     *
     615     *  @param lookupOptions input parameter, NamingService-specific, may be null
     616     *  @param storedOptions output parameter, NamingService-specific, any stored properties will be added if non-null
     617     *  @return non-empty List of Destinations, or null if nothing found
     618     *  @since 0.9.26
     619     */
     620    public List<Destination> lookupAll(String hostname, Properties lookupOptions, List<Properties> storedOptions) {
     621        Properties props = storedOptions != null ? new Properties() : null;
     622        Destination d = lookup(hostname, lookupOptions, props);
     623        List<Destination> rv;
     624        if (d != null) {
     625            rv = Collections.singletonList(d);
     626            if (storedOptions != null)
     627                storedOptions.add(props.isEmpty() ? null : props);
     628        } else {
     629            rv = null;
     630        }
     631        return rv;
     632    }
     633
     634    /**
     635     *  Add a Destination to an existing hostname's entry in the addressbook.
     636     *
     637     *  @return success
     638     *  @since 0.9.26
     639     */
     640    public boolean addDestination(String hostname, Destination d) {
     641        return addDestination(hostname, d, null);
     642    }
     643
     644    /**
     645     *  Add a Destination to an existing hostname's entry in the addressbook.
     646     *  This implementation simply calls putIfAbsent().
     647     *  Subclasses implementing multiple destinations per hostname should override.
     648     *
     649     *  @param options NamingService-specific, may be null
     650     *  @return success
     651     *  @since 0.9.26
     652     */
     653    public boolean addDestination(String hostname, Destination d, Properties options) {
     654        return putIfAbsent(hostname, d, options);
     655    }
     656
     657    /**
     658     *  Remove a hostname's entry only if it contains the Destination d.
     659     *  If the NamingService supports multiple Destinations per hostname,
     660     *  and this is the only Destination, removes the entire entry.
     661     *  If aditional Destinations remain, it only removes the
     662     *  specified Destination from the entry.
     663     *
     664     *  @return true if entry containing d was successfully removed.
     665     *  @since 0.9.26
     666     */
     667    public boolean remove(String hostname, Destination d) {
     668        return remove(hostname, d, null);
     669    }
     670
     671    /**
     672     *  Remove a hostname's entry only if it contains the Destination d.
     673     *  If the NamingService supports multiple Destinations per hostname,
     674     *  and this is the only Destination, removes the entire entry.
     675     *  If aditional Destinations remain, it only removes the
     676     *  specified Destination from the entry.
     677     *
     678     *  This implementation simply calls lookup() and remove().
     679     *  Subclasses implementing multiple destinations per hostname,
     680     *  or with more efficient implementations, should override.
     681     *  Fails if entry previously exists.
     682     *
     683     *  @param options NamingService-specific, may be null
     684     *  @return true if entry containing d was successfully removed.
     685     *  @since 0.9.26
     686     */
     687    public boolean remove(String hostname, Destination d, Properties options) {
     688        Destination old = lookup(hostname, options, null);
     689        if (!d.equals(old))
     690            return false;
     691        return remove(hostname, options);
     692    }
     693
     694    //// End new API for multiple Destinations
    522695
    523696    /**
Note: See TracChangeset for help on using the changeset viewer.