BloomFilter (bloom-filter 1.0 API)

All Superinterfaces:

java.lang.Cloneable, java.io.Serializable

All Known Subinterfaces:

CountingBloomFilter<T>

All Known Implementing Classes:

BloomFilterMemory, BloomFilterRedis, CountingBloomFilterMemory, CountingBloomFilterRedis
```
public interface BloomFilter<T>
extends java.lang.Cloneable, java.io.Serializable
```
Represents a Bloom filter and provides default methods for hashing.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`boolean`	`add(byte[] element)` Adds the passed value to the filter.
`default boolean`	`add(T element)` Adds the passed value to the filter.
`default java.util.List<java.lang.Boolean>`	`addAll(java.util.Collection<T> elements)` Performs a bulk add operation for a collection of elements.
`default java.lang.String`	`asString()` Prints the Bloom filter: metadata and data
`void`	`clear()` Removes all elements from the filter (i.e. resets all bits to zero).
`BloomFilter<T>`	`clone()` Constructs a deep copy of the Bloom filter
`default boolean`	`compatible(BloomFilter<T> bloomFilter, BloomFilter<T> other)` Checks if two Bloom filters are compatible, i.e. have compatible parameters (hash function, size, etc.)
`FilterBuilder`	`config()` Returns the configuration/builder of the Bloom filter.
`boolean`	`contains(byte[] element)` Tests whether an element is present in the filter (subject to the specified false positive rate).
`default java.util.List<java.lang.Boolean>`	`contains(java.util.Collection<T> elements)` Bulk-tests elements for existence in the filter.
`default boolean`	`contains(T element)` Tests whether an element is present in the filter (subject to the specified false positive rate).
`default boolean`	`containsAll(java.util.Collection<T> elements)` Bulk-tests elements for existence in the filter.
`java.util.BitSet`	`getBitSet()` Return the underyling bit vector of the Bloom filter.
`default double`	`getBitsPerElement(int n)` Calculates the numbers of Bits per element, based on the expected number of inserted elements expectedElements.
`default double`	`getBitZeroProbability(int n)` Returns the probability that a bit is zero.
`default double`	`getEstimatedFalsePositiveProbability()` Returns the probability of a false positive (approximated) using an estimation of how many elements are currently in the filter
`default java.lang.Double`	`getEstimatedPopulation()` Estimates the current population of the Bloom filter (see: http://en.wikipedia.org/wiki/Bloom_filter#Approximating_the_number_of_items_in_a_Bloom_filter )
`default int`	`getExpectedElements()` Returns the expected number of elements (called n in the literature)
`default double`	`getFalsePositiveProbability()` Returns the expected false positive probability for the expected amounts of elements.
`default double`	`getFalsePositiveProbability(double insertedElements)` Returns the probability of a false positive (approximated): `(1 - e^(-hashes * insertedElements / size)) ^ hashes`
`default int`	`getHashes()` Returns the number of hash functions (called k in the literature)
`default int`	`getSize()` Return the size of the Bloom filter, i.e. the number of positions in the underlyling bit vector (called m in the literature).
`default int[]`	`hash(byte[] bytes)` Returns the k hash values for an inputs element in byte array form
`default int[]`	`hash(java.lang.String value)` Dispatches the hash function for a string value
`boolean`	`intersect(BloomFilter<T> other)` Performs the intersection operation on two compatible bloom filters.
`boolean`	`isEmpty()` Returns `true` if the Bloom filter does not contain any elements
`static java.lang.Double`	`population(java.util.BitSet bitSet, FilterBuilder config)`
`default void`	`remove()` Destroys the Bloom filter by deleting its contents and metadata
`default byte[]`	`toBytes(T element)` Converts an element to the byte array representation used for hashing.
`boolean`	`union(BloomFilter<T> other)` Performs the union operation on two compatible bloom filters.

- Method Detail
  - add
```
boolean add(byte[] element)
```
    Adds the passed value to the filter.
    
    Parameters:
    
    element - value to add
    
    Returns:
    
    true if the value did not previously exist in the filter. Note, that a false positive may occur, thus the value may not have already been in the filter, but it hashed to a set of bits already in the filter.
  - add
```
default boolean add(T element)
```
    Adds the passed value to the filter.
    
    Parameters:
    
    element - value to add
    
    Returns:
    
    true if the value did not previously exist in the filter. Note, that a false positive may occur, thus the value may not have already been in the filter, but it hashed to a set of bits already in the filter.
  - addAll
```
default java.util.List<java.lang.Boolean> addAll(java.util.Collection<T> elements)
```
    Performs a bulk add operation for a collection of elements.
    
    Parameters:
    
    elements -
    
    Returns:
    
    a list of booleans indicating for each element, whether it was previously present in the filter
  - clear
```
void clear()
```
    Removes all elements from the filter (i.e. resets all bits to zero).
  - contains
```
boolean contains(byte[] element)
```
    Tests whether an element is present in the filter (subject to the specified false positive rate).
    
    Parameters:
    
    element -
    
    Returns:
    
    true if the element is contained
  - contains
```
default boolean contains(T element)
```
    Tests whether an element is present in the filter (subject to the specified false positive rate).
    
    Parameters:
    
    element -
    
    Returns:
    
    true if the element is contained
  - contains
```
default java.util.List<java.lang.Boolean> contains(java.util.Collection<T> elements)
```
    Bulk-tests elements for existence in the filter.
    
    Parameters:
    
    elements - a collection of elements to test
    
    Returns:
    
    a list of booleans indicating for each element, whether it is present in the filter
  - containsAll
```
default boolean containsAll(java.util.Collection<T> elements)
```
    Bulk-tests elements for existence in the filter.
    
    Parameters:
    
    elements - a collection of elements to test
    
    Returns:
    
    true if all elements are present in the filter
  - getBitSet
```
java.util.BitSet getBitSet()
```
    Return the underyling bit vector of the Bloom filter.
    
    Returns:
    
    the underyling bit vector of the Bloom filter.
  - config
```
FilterBuilder config()
```
    Returns the configuration/builder of the Bloom filter.
    
    Returns:
    
    the configuration/builder of the Bloom filter.
  - clone
```
BloomFilter<T> clone()
```
    Constructs a deep copy of the Bloom filter
    
    Returns:
    
    a cloned Bloom filter
  - getSize
```
default int getSize()
```
    Return the size of the Bloom filter, i.e. the number of positions in the underlyling bit vector (called m in the literature).
    
    Returns:
    
    the bit vector size
  - getExpectedElements
```
default int getExpectedElements()
```
    Returns the expected number of elements (called n in the literature)
    
    Returns:
    
    the expected number of elements
  - getHashes
```
default int getHashes()
```
    Returns the number of hash functions (called k in the literature)
    
    Returns:
    
    the number of hash functions
  - getFalsePositiveProbability
```
default double getFalsePositiveProbability()
```
    Returns the expected false positive probability for the expected amounts of elements. This is independent of the actual amount of elements in the filter. Use getFalsePositiveProbability(double) for that purpose.
    
    Returns:
    
    the static expected false positive probability
  - toBytes
```
default byte[] toBytes(T element)
```
    Converts an element to the byte array representation used for hashing.
    
    Parameters:
    
    element - the element to convert
    
    Returns:
    
    the elements byte array representation
  - compatible
```
default boolean compatible(BloomFilter<T> bloomFilter,
                           BloomFilter<T> other)
```
    Checks if two Bloom filters are compatible, i.e. have compatible parameters (hash function, size, etc.)
    
    Parameters:
    
    bloomFilter -
    
    other -
    
    Returns:
  - remove
```
default void remove()
```
    Destroys the Bloom filter by deleting its contents and metadata
  - hash
```
default int[] hash(byte[] bytes)
```
    Returns the k hash values for an inputs element in byte array form
    
    Parameters:
    
    bytes - input element
    
    Returns:
    
    hash values
  - hash
```
default int[] hash(java.lang.String value)
```
    Dispatches the hash function for a string value
    
    Parameters:
    
    value - the value to be hashed
    
    Returns:
    
    array with hashes integer hash positions in the range [0,size)
  - union
```
boolean union(BloomFilter<T> other)
```
    Performs the union operation on two compatible bloom filters. This is achieved through a bitwise OR operation on their bit vectors. This operations is lossless, i.e. no elements are lost and the bloom filter is the same that would have resulted if all elements wer directly inserted in just one bloom filter.
    
    Parameters:
    
    other - the other bloom filter
    
    Returns:
    
    true if this bloom filter could successfully be updated through the union with the provided bloom filter
  - intersect
```
boolean intersect(BloomFilter<T> other)
```
    Performs the intersection operation on two compatible bloom filters. This is achieved through a bitwise AND operation on their bit vectors. The operations doesn't introduce any false negatives but it does raise the false positive probability. The the false positive probability in the resulting Bloom filter is at most the false-positive probability in one of the constituent bloom filters
    
    Parameters:
    
    other - the other bloom filter
    
    Returns:
    
    true if this bloom filter could successfully be updated through the intersection with the provided bloom filter
  - isEmpty
```
boolean isEmpty()
```
    Returns true if the Bloom filter does not contain any elements
    
    Returns:
    
    true if the Bloom filter does not contain any elements
  - getFalsePositiveProbability
```
default double getFalsePositiveProbability(double insertedElements)
```
    Returns the probability of a false positive (approximated):
    (1 - e^(-hashes * insertedElements / size)) ^ hashes
    
    Parameters:
    
    insertedElements - The number of elements already inserted into the Bloomfilter
    
    Returns:
    
    probability of a false positive after expectedElements add(byte[]) operations
  - getEstimatedFalsePositiveProbability
```
default double getEstimatedFalsePositiveProbability()
```
    Returns the probability of a false positive (approximated) using an estimation of how many elements are currently in the filter
    
    Returns:
    
    probability of a false positive
  - getBitsPerElement
```
default double getBitsPerElement(int n)
```
    Calculates the numbers of Bits per element, based on the expected number of inserted elements expectedElements.
    
    Parameters:
    
    n - The number of elements already inserted into the Bloomfilter
    
    Returns:
    
    The numbers of bits per element
  - getBitZeroProbability
```
default double getBitZeroProbability(int n)
```
    Returns the probability that a bit is zero.
    
    Parameters:
    
    n - The number of elements already inserted into the Bloomfilter
    
    Returns:
    
    probability that a certain bit is zero after expectedElements add(byte[]) operations
  - getEstimatedPopulation
```
default java.lang.Double getEstimatedPopulation()
```
    Estimates the current population of the Bloom filter (see: http://en.wikipedia.org/wiki/Bloom_filter#Approximating_the_number_of_items_in_a_Bloom_filter )
    
    Returns:
    
    the estimated amount of elements in the filter
  - population
```
static java.lang.Double population(java.util.BitSet bitSet,
                                   FilterBuilder config)
```
  - asString
```
default java.lang.String asString()
```
    Prints the Bloom filter: metadata and data
    
    Returns:
    
    String representation of the Bloom filter

Interface BloomFilter<T>

Method Summary

Method Detail

add

add

addAll

clear

contains

contains

contains

containsAll

getBitSet

config

clone

getSize

getExpectedElements

getHashes

getFalsePositiveProbability

toBytes

compatible

remove

hash

hash

union

intersect

isEmpty

getFalsePositiveProbability

getEstimatedFalsePositiveProbability

getBitsPerElement

getBitZeroProbability

getEstimatedPopulation

population

asString