org.forgerock.bloomfilter

Class BloomFilterStatistics

java.lang.Object

org.forgerock.bloomfilter.BloomFilterStatistics

@Immutable
public final class BloomFilterStatistics
extends Object

Provides a snapshot of the current statistics and configuration of a Bloom Filter implementation.

Constructor Summary

Constructors

Constructor and Description
BloomFilterStatistics(double configuredFalsePositiveProbability, double expectedFalsePositiveProbability, long capacity, long bitSize, long expiryTime, long estimatedRemainingCapacity) Constructs a statistics object with the given parameters.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o)
long	getBitSize() The total memory size of the set, in bits.
long	getCapacity() The capacity of the set.
double	getConfiguredFalsePositiveProbability() The configured probability of false positives.
long	getEstimatedRemainingCapacity() Provides an estimate of the remaining capacity in this bloom filter before it would become saturated.
double	getExpectedFalsePositiveProbability() The expected probability of false positives given the current state of the set.
long	getExpiryTime() The time in milliseconds since the UTC epoch until the last element contained in this bloom filter expires.
int	hashCode()
boolean	isSaturated() Determines whether the bloom filter expected false positive probability has exceeded the configured false positive probability.
static long	optimumBitSize(long capacity, double falsePositiveProbability) Calculates the optimum size of a bloom filter (in bits) to achieve the given false positive probability and expected number of insertions (capacity).
static long	optimumRemainingCapacity(long bitSize, double expectedFalsePositiveProbability, long capacity) Estimates the remaining capacity in an optimum Bloom Filter.
String	toString()

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

BloomFilterStatistics

public BloomFilterStatistics(double configuredFalsePositiveProbability,
                             double expectedFalsePositiveProbability,
                             long capacity,
                             long bitSize,
                             long expiryTime,
                             long estimatedRemainingCapacity)

Constructs a statistics object with the given parameters.

Parameters:

configuredFalsePositiveProbability - the false positive probability that was configured for this set.

expectedFalsePositiveProbability - the expected false positive probability given the current state of the set.

capacity - the expected total number of insertions into the set before it becomes saturated (exceeds the configured false positive probability).

bitSize - the total memory size of the set in bits.

Method Detail

getConfiguredFalsePositiveProbability

public double getConfiguredFalsePositiveProbability()

The configured probability of false positives.

Returns:

the false positive probability (FPP) between 0 and 1.

getExpectedFalsePositiveProbability

public double getExpectedFalsePositiveProbability()

The expected probability of false positives given the current state of the set.

Returns:

the expected false positive probability (FPP) between 0 and 1.

getCapacity

public long getCapacity()

The capacity of the set. This is the expected total number of elements that can be inserted into the set before it exceeds the configured false positive probability.

Returns:

the expected capacity of the set.

getBitSize

public long getBitSize()

The total memory size of the set, in bits. This size is a guide to the memory used for storing the actual elements of the set, and may not reflect fixed-cost overheads such as the size of object headers, configuration options, etc.

Returns:

the total memory size of the set in bits.

optimumBitSize

public static long optimumBitSize(long capacity,
                                  double falsePositiveProbability)

Calculates the optimum size of a bloom filter (in bits) to achieve the given false positive probability and expected number of insertions (capacity).

Parameters:

capacity - the expected number of insertions into the bloom filter.

falsePositiveProbability - the desired probability of false positives.

Returns:

the optimum number of bits to use for the bloom filter.

getEstimatedRemainingCapacity

public long getEstimatedRemainingCapacity()

Provides an estimate of the remaining capacity in this bloom filter before it would become saturated.

optimumRemainingCapacity

public static long optimumRemainingCapacity(long bitSize,
                                            double expectedFalsePositiveProbability,
                                            long capacity)

Estimates the remaining capacity in an optimum Bloom Filter. This is assuming that the Bloom Filter is close to optimal in space efficiency for the configured false positive probability.

Parameters:

bitSize - the size of the Bloom Filter bit-vector in bits.

expectedFalsePositiveProbability - the expected current false positive probability of the bloom filter.

capacity - the overall expected capacity of the bloom filter.

Returns:

an estimate of the number of elements that could be inserted before the bloom filter becomes saturated.

getExpiryTime

public long getExpiryTime()

The time in milliseconds since the UTC epoch until the last element contained in this bloom filter expires. This statistic is only relevant to expiring or rolling bloom filter implementations.

Returns:

the latest expiry time in milliseconds from the UTC epoch.

isSaturated

public boolean isSaturated()

Determines whether the bloom filter expected false positive probability has exceeded the configured false positive probability. This happens roughly when half of the bits in the underlying bit vector have been set to 1. No more elements should be inserted into the Bloom Filter beyond this point to avoid exceeding the configured probability of false positives.

Returns:

true if the expected false positive probability is greater than the configured probability.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object