KBucketSet (Javadocs [I2P+ 2.13.0+]

java.lang.Object
- net.i2p.kademlia.KBucketSet<T>

Type Parameters:
T - type of SimpleDataStructure objects stored in buckets
```
public class KBucketSet<T extends SimpleDataStructure>
extends Object
```
In-memory storage of buckets sorted by XOR metric from base (us) passed in via constructor. This starts with one bucket covering the whole key space, and may eventually be split to a max of number of bits in data type (160 for SHA1Hash or 256 for Hash), times 2**(B-1) for Kademlia value B. Refactored from net.i2p.router.networkdb.kademlia

Constructor Summary

Constructors
Constructor and Description
`KBucketSet(I2PAppContext context, T us, int max, int b)` Use the default trim strategy, which removes a random entry.
`KBucketSet(I2PAppContext context, T us, int max, int b, KBucketTrimmer<T> trimmer)` Use the supplied trim strategy.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`add(T peer)` Add a peer to the appropriate bucket.
`void`	`clear()` Clear all buckets.
`(package private) T`	`generateRandomKey(KBucket<T> bucket)` Generate a random key to go within this bucket Package private for testing only.
`Set<T>`	`getAll()` Return all entries in all buckets.
`void`	`getAll(SelectionCollector<T> collector)` Add all entries in all buckets to the provided collector.
`Set<T>`	`getAll(Set<T> toIgnore)` Get all entries in all buckets, excluding the specified entries.
`(package private) List<KBucket<T>>`	`getBuckets()` Returned list is a copy of the bucket list, closest first, with the actual buckets (not a copy).
`List<T>`	`getClosest(int max)` The keys closest to us.
`List<T>`	`getClosest(int max, Collection<T> toIgnore)` The keys closest to us.
`List<T>`	`getClosest(T key, int max)` The keys closest to the key.
`List<T>`	`getClosest(T key, int max, Collection<T> toIgnore)` The keys closest to the key.
`List<T>`	`getExploreKeys(long age)` For every bucket that hasn't been updated in this long, or isn't close to full, generate a random key that would be a member of that bucket.
`(package private) int`	`getRange(T key)` The number of bits minus 1 (range number) for the xor of the key.
`boolean`	`remove(T entry)` Remove a peer from its bucket.
`int`	`size()` The current number of entries.
`String`	`toString()`

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

- Constructor Detail
  - KBucketSet
```
public KBucketSet(I2PAppContext context,
                  T us,
                  int max,
                  int b)
```
    Use the default trim strategy, which removes a random entry.
    Parameters:
    context - the router context
    us - the local identity (typically a SHA1Hash or Hash) The class must have a zero-argument constructor.
    max - the Kademlia value "k", the max per bucket, k >= 4
    b - the Kademlia value "b", split buckets an extra 2**(b-1) times, b > 0, use 1 for bittorrent, Kademlia paper recommends 5
  - KBucketSet
```
public KBucketSet(I2PAppContext context,
                  T us,
                  int max,
                  int b,
                  KBucketTrimmer<T> trimmer)
```
    Use the supplied trim strategy.
    Parameters:
    context - the router context
    us - the local identity
    max - the Kademlia value "k", the max per bucket
    b - the Kademlia value "b"
    trimmer - the trim strategy
- Method Detail
  - add
```
public boolean add(T peer)
```
    Add a peer to the appropriate bucket. Will split the bucket if necessary.
    Parameters:
    peer - the peer
    Returns:
    true if the peer is new to the bucket it goes in, or false if it was already in it. Always returns false on an attempt to add ourselves.
  - clear
```
public void clear()
```
    Clear all buckets. @since 0.8.8
  - generateRandomKey
```
T generateRandomKey(KBucket<T> bucket)
```
    Generate a random key to go within this bucket Package private for testing only. Others shouldn't need this.
    Parameters:
    bucket - the bucket
    Returns:
    a random key in the bucket's range
  - getAll
```
public Set<T> getAll()
```
    Return all entries in all buckets.
    Returns:
    a copy in a new set
  - getAll
```
public void getAll(SelectionCollector<T> collector)
```
    Add all entries in all buckets to the provided collector.
    Parameters:
    collector - the collector to add entries to
  - getAll
```
public Set<T> getAll(Set<T> toIgnore)
```
    Get all entries in all buckets, excluding the specified entries.
    Parameters:
    toIgnore - entries to exclude
    Returns:
    a copy in a new set
  - getBuckets
```
List<KBucket<T>> getBuckets()
```
    Returned list is a copy of the bucket list, closest first, with the actual buckets (not a copy). Primarily for testing. You shouldn't ever need to get all the buckets. Use getClosest() or getAll() instead to get the keys.
    Returns:
    non-null
  - getClosest
```
public List<T> getClosest(int max)
```
    The keys closest to us. Returned list will never contain us.
    Parameters:
    max - maximum number of keys to return
    Returns:
    non-null, closest first
  - getClosest
```
public List<T> getClosest(int max,
                          Collection<T> toIgnore)
```
    The keys closest to us. Returned list will never contain us.
    Parameters:
    max - maximum number of keys to return
    toIgnore - entries to exclude
    Returns:
    non-null, closest first
  - getClosest
```
public List<T> getClosest(T key,
                          int max)
```
    The keys closest to the key. Returned list will never contain us.
    Parameters:
    key - the target key
    max - maximum number of keys to return
    Returns:
    non-null, closest first
  - getClosest
```
public List<T> getClosest(T key,
                          int max,
                          Collection<T> toIgnore)
```
    The keys closest to the key. Returned list will never contain us.
    Parameters:
    key - the target key
    max - maximum number of keys to return
    toIgnore - entries to exclude
    Returns:
    non-null, closest first
  - getExploreKeys
```
public List<T> getExploreKeys(long age)
```
    For every bucket that hasn't been updated in this long, or isn't close to full, generate a random key that would be a member of that bucket. The returned keys may be searched for to "refresh" the buckets.
    Parameters:
    age - the maximum age in milliseconds
    Returns:
    non-null, closest first
  - getRange
```
int getRange(T key)
```
    The number of bits minus 1 (range number) for the xor of the key. Package private for testing only. Others shouldn't need this.
    Parameters:
    key - the key
    Returns:
    0 to max-1 or -1 for us
  - remove
```
public boolean remove(T entry)
```
    Remove a peer from its bucket.
    Parameters:
    entry - the peer to remove
    Returns:
    true if removed
  - size
```
public int size()
```
    The current number of entries.
    Returns:
    total number of entries across all buckets
  - toString
```
public String toString()
```
    Overrides:
    toString in class Object

Class KBucketSet<T extends SimpleDataStructure>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

KBucketSet

KBucketSet

Method Detail

add

clear

generateRandomKey

getAll

getAll

getAll

getBuckets

getClosest

getClosest

getClosest

getClosest

getExploreKeys

getRange

remove

size

toString