net.tomp2p.rpc

Class SimpleBloomFilter<E>

java.lang.Object

net.tomp2p.rpc.SimpleBloomFilter<E>

Type Parameters:

E - The type of object the BloomFilter should contain

All Implemented Interfaces:

Serializable, Iterable<E>, Collection<E>, Set<E>

public class SimpleBloomFilter<E>
extends Object
implements Set<E>, Serializable

A simple Bloom Filter (see http://en.wikipedia.org/wiki/Bloom_filter) that uses java.util.Random as a primitive hash function, and which implements Java's Set interface for convenience. Only the add(), addAll(), contains(), and containsAll() methods are implemented. Calling any other method will yield an UnsupportedOperationException. This code may be used, modified, and redistributed provided that the author tag below remains intact.

Author:

Ian Clarke , Thomas Bocek Added methods to get and create a SimpleBloomFilter from existing data. The data can be either a BitSet or a bye[].

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
SimpleBloomFilter(byte[] rawBitArray) Constructs a SimpleBloomFilter out of existing data.
SimpleBloomFilter(byte[] rawBitArray, int offset, int length) Constructs a SimpleBloomFilter out of existing data.
SimpleBloomFilter(int bitArraySize, int expectedElements) Construct an empty SimpleBloomFilter.
SimpleBloomFilter(int bitArraySize, int expectedElements, BitSet bitSet) Constructs a SimpleBloomFilter out of existing data.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	add(E o)
boolean	addAll(Collection<? extends E> c)
static int	byteArrayToInt(byte[] me, int offset)
void	clear() Clear the Bloom Filter
boolean	contains(Object o)
boolean	containsAll(Collection<?> c)
double	expectedFalsePositiveProbability() Calculates the approximate probability of the contains() method returning true for an object that had not previously been inserted into the bloom filter.
BitSet	getBitSet() Returns the bitset that backs the bloom filter
int	getExpectedElements() Returns the expected elements that was provided by the user.
static byte[]	intToByteArray(int value1, int value2, byte[] me)
boolean	isEmpty() Not implemented
Iterator<E>	iterator() Not implemented
SimpleBloomFilter<E>	merge(SimpleBloomFilter<E> toMerge)
boolean	remove(Object o) Not implemented
boolean	removeAll(Collection<?> c) Not implemented
boolean	retainAll(Collection<?> c) Not implemented
int	size() Not implemented
Object[]	toArray() Not implemented
<T> T[]	toArray(T[] a) Not implemented
byte[]	toByteArray() Returns a byte array of at least length 5.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface java.util.Set

equals, hashCode

Constructor Detail

SimpleBloomFilter

public SimpleBloomFilter(int bitArraySize,
                 int expectedElements)

Construct an empty SimpleBloomFilter. You must specify the number of bits in the Bloom Filter, and also you should specify the number of items you expect to add. The latter is used to choose some optimal internal values to minimize the false-positive rate (which can be estimated with expectedFalsePositiveRate()).

Parameters:

bitArraySize - The number of bits in the bit array (often called 'm' in the context of bloom filters).

expectedElements - The typical number of items you expect to be added to the SimpleBloomFilter (often called 'n').

SimpleBloomFilter

public SimpleBloomFilter(byte[] rawBitArray)

Constructs a SimpleBloomFilter out of existing data. You must specify the number of bits in the Bloom Filter, and also you should specify the number of items you expect to add. The latter is used to choose some optimal internal values to minimize the false-positive rate (which can be estimated with expectedFalsePositiveRate()).

Parameters:

bitArraySize - The number of bits in the bit array (often called 'm' in the context of bloom filters).

expectedElements - The typical number of items you expect to be added to the SimpleBloomFilter (often called 'n').

rawBitArray - The data that will be used in the backing BitSet

SimpleBloomFilter

public SimpleBloomFilter(byte[] rawBitArray,
                 int offset,
                 int length)

Constructs a SimpleBloomFilter out of existing data. You must specify the number of bits in the Bloom Filter, and also you should specify the number of items you expect to add. The latter is used to choose some optimal internal values to minimize the false-positive rate (which can be estimated with expectedFalsePositiveRate()).

Parameters:

bitArraySize - The number of bits in the bit array (often called 'm' in the context of bloom filters).

expectedElements - The typical number of items you expect to be added to the SimpleBloomFilter (often called 'n').

rawBitArray - The data that will be used in the backing BitSet

offset - The offset of the array

length - The length of the array

SimpleBloomFilter

public SimpleBloomFilter(int bitArraySize,
                 int expectedElements,
                 BitSet bitSet)

Constructs a SimpleBloomFilter out of existing data. You must specify the number of bits in the Bloom Filter, and also you should specify the number of items you expect to add. The latter is used to choose some optimal internal values to minimize the false-positive rate (which can be estimated with expectedFalsePositiveRate()).

Parameters:

bitArraySize - The number of bits in the bit array (often called 'm' in the context of bloom filters).

expectedElements - he typical number of items you expect to be added to the SimpleBloomFilter (often called 'n').

bitSet - The data that will be used in the backing BitSet

Throws:

RuntimeException - If bitArraySize is not a multiple of eight.

Method Detail

expectedFalsePositiveProbability

public double expectedFalsePositiveProbability()

Calculates the approximate probability of the contains() method returning true for an object that had not previously been inserted into the bloom filter. This is known as the "false positive probability".

Returns:

The estimated false positive rate

getExpectedElements

public int getExpectedElements()

Returns the expected elements that was provided by the user.

Returns:

The expected elements that was provided by the user

add

public boolean add(E o)

Specified by:

add in interface Collection<E>

Specified by:

add in interface Set<E>

addAll

public boolean addAll(Collection<? extends E> c)

Specified by:

addAll in interface Collection<E>

Specified by:

addAll in interface Set<E>

Returns:

This method will always return false

clear

public void clear()

Clear the Bloom Filter

Specified by:

clear in interface Collection<E>

Specified by:

clear in interface Set<E>

contains

public boolean contains(Object o)

Specified by:

contains in interface Collection<E>

Specified by:

contains in interface Set<E>

Returns:

False indicates that o was definitely not added to this Bloom Filter, true indicates that it probably was. The probability can be estimated using the expectedFalsePositiveProbability() method.

containsAll

public boolean containsAll(Collection<?> c)

Specified by:

containsAll in interface Collection<E>

Specified by:

containsAll in interface Set<E>

isEmpty

public boolean isEmpty()

Not implemented

Specified by:

isEmpty in interface Collection<E>

Specified by:

isEmpty in interface Set<E>

iterator

public Iterator<E> iterator()

Not implemented

Specified by:

iterator in interface Iterable<E>

Specified by:

iterator in interface Collection<E>

Specified by:

iterator in interface Set<E>

remove

public boolean remove(Object o)

Not implemented

Specified by:

remove in interface Collection<E>

Specified by:

remove in interface Set<E>

removeAll

public boolean removeAll(Collection<?> c)

Not implemented

Specified by:

removeAll in interface Collection<E>

Specified by:

removeAll in interface Set<E>

retainAll

public boolean retainAll(Collection<?> c)

Not implemented

Specified by:

retainAll in interface Collection<E>

Specified by:

retainAll in interface Set<E>

size

public int size()

Not implemented

Specified by:

size in interface Collection<E>

Specified by:

size in interface Set<E>

toArray

public Object[] toArray()

Not implemented

Specified by:

toArray in interface Collection<E>

Specified by:

toArray in interface Set<E>

toArray

public <T> T[] toArray(T[] a)

Not implemented

Specified by:

toArray in interface Collection<E>

Specified by:

toArray in interface Set<E>

getBitSet

public BitSet getBitSet()

Returns the bitset that backs the bloom filter

Returns:

bloom filter as a bitset

toByteArray

public byte[] toByteArray()

Returns a byte array of at least length 5. The most significant bit in the result is guaranteed not to be a 1 (since BitSet does not support sign extension). The byte-ordering of the result is big-endian which means the most significant bit is in element 0. The bit at index 0 of the bit set is assumed to be the least significant bit.

Returns:

a byte array representation of the bitset and the expected elements

intToByteArray

public static final byte[] intToByteArray(int value1,
                    int value2,
                    byte[] me)

byteArrayToInt

public static final int byteArrayToInt(byte[] me,
                 int offset)

merge

public SimpleBloomFilter<E> merge(SimpleBloomFilter<E> toMerge)