Interface BloomFilter<T extends BloomFilter<T>>
- Type Parameters:
T- The BloomFilter type.
- All Superinterfaces:
BitMapExtractor,IndexExtractor
- All Known Subinterfaces:
CountingBloomFilter
- All Known Implementing Classes:
ArrayCountingBloomFilter,LayeredBloomFilter,SimpleBloomFilter,SparseBloomFilter,WrappedBloomFilter
See implementation notes for BitMapExtractor and IndexExtractor.
- Since:
- 4.5.0-M1
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intThe sparse characteristic used to determine the best method for matching: 1. -
Method Summary
Modifier and TypeMethodDescriptionintGets the cardinality (number of enabled bits) of this Bloom filter.intGets the characteristics of the filter.voidclear()Clears the filter to by resetting it to its initial, unpopulated state.default booleancontains(BitMapExtractor bitMapExtractor) Returnstrueif this filter contains the bits specified in the bit maps produced by the bitMapExtractor.default booleancontains(BloomFilter<?> other) Returnstrueif this filter contains the specified filter.default booleanReturnstrueif this filter contains the bits specified in the hasher.booleancontains(IndexExtractor indexExtractor) Returnstrueif this filter contains the indices specified IndexExtractor.copy()Creates a new instance of thisBloomFilterwith the same properties as the current one.default intestimateIntersection(BloomFilter<?> other) Estimates the number of items in the intersection of this Bloom filter with the other bloom filter.default intEstimates the number of items in the Bloom filter.default intestimateUnion(BloomFilter<?> other) Estimates the number of items in the union of this Bloom filter with the other bloom filter.getShape()Gets the shape that was used when the filter was built.default booleanisEmpty()Determines if all the bits are off.default booleanisFull()Determines if the bloom filter is "full".booleanmerge(BitMapExtractor bitMapExtractor) Merges the specified hasher into this Bloom filter.default booleanmerge(BloomFilter<?> other) Merges the specified Bloom filter into this Bloom filter.default booleanMerges the specified hasher into this Bloom filter.booleanmerge(IndexExtractor indexExtractor) Merges the specified IndexExtractor into this Bloom filter.default IndexExtractorMost Bloom filters create unique IndexExtractors.Methods inherited from interface org.apache.commons.collections4.bloomfilter.BitMapExtractor
asBitMapArray, processBitMapPairs, processBitMapsMethods inherited from interface org.apache.commons.collections4.bloomfilter.IndexExtractor
asIndexArray, processIndices
-
Field Details
-
SPARSE
The sparse characteristic used to determine the best method for matching: 1.For `sparse` implementations the
forEachIndex(IntConsumer consumer)method is more efficient. For non `sparse` implementations theforEachBitMap(LongConsumer consumer)is more efficient. Implementers should determine if it is easier.- See Also:
-
-
Method Details
-
cardinality
int cardinality()Gets the cardinality (number of enabled bits) of this Bloom filter.This is also known as the Hamming value or Hamming number.
- Returns:
- the cardinality of this filter
-
characteristics
int characteristics()Gets the characteristics of the filter.Characteristics are defined as bits within the characteristics integer.
- Returns:
- the characteristics for this bloom filter.
-
clear
void clear()Clears the filter to by resetting it to its initial, unpopulated state. -
contains
Returnstrueif this filter contains the bits specified in the bit maps produced by the bitMapExtractor.- Parameters:
bitMapExtractor- theBitMapExtractorto provide the bit maps.- Returns:
trueif this filter is enabled for all bits specified by the bit maps
-
contains
Returnstrueif this filter contains the specified filter.Specifically this returns
trueif this filter is enabled for all bits that are enabled in theotherfilter. Using the bit representations this is effectively(this AND other) == other.- Parameters:
other- the other Bloom filter- Returns:
- true if all enabled bits in the other filter are enabled in this filter.
-
contains
Returnstrueif this filter contains the bits specified in the hasher.Specifically this returns
trueif this filter is enabled for all bit indexes identified by thehasher. Using the bit map representations this is effectively(this AND hasher) == hasher.- Parameters:
hasher- the hasher to provide the indexes- Returns:
- true if this filter is enabled for all bits specified by the hasher
-
contains
Returnstrueif this filter contains the indices specified IndexExtractor.Specifically this returns
trueif this filter is enabled for all bit indexes identified by theIndexExtractor.- Parameters:
indexExtractor- the IndexExtractor to provide the indexes- Returns:
trueif this filter is enabled for all bits specified by the IndexExtractor
-
copy
Creates a new instance of thisBloomFilterwith the same properties as the current one.- Returns:
- a copy of this
BloomFilter.
-
estimateIntersection
Estimates the number of items in the intersection of this Bloom filter with the other bloom filter.This method produces estimate is roughly equivalent to the number of unique Hashers that have been merged into both of the filters by rounding the value from the calculation described in the
Shapeclass Javadoc.estimateIntersectionshould only be called with Bloom filters of the same Shape. If called on Bloom filters of differing shape this method is not symmetric. Ifotherhas more bits anIllegalArgumentExceptionmay be thrown.- Parameters:
other- The other Bloom filter- Returns:
- an estimate of the number of items in the intersection. If the calculated estimate is larger than Integer.MAX_VALUE then MAX_VALUE is returned.
- Throws:
IllegalArgumentException- if the estimated N for the union of the filters is infinite.- See Also:
-
estimateN
Estimates the number of items in the Bloom filter.By default this is the rounding of the
Shape.estimateN(cardinality)calculation for the shape and cardinality of this filter.This produces an estimate roughly equivalent to the number of Hashers that have been merged into the filter by rounding the value from the calculation described in the
Shapeclass Javadoc.Note:
- if cardinality == numberOfBits, then result is Integer.MAX_VALUE.
- if cardinality > numberOfBits, then an IllegalArgumentException is thrown.
- Returns:
- an estimate of the number of items in the bloom filter. Will return Integer.MAX_VALUE if the estimate is larger than Integer.MAX_VALUE.
- Throws:
IllegalArgumentException- if the cardinality is > numberOfBits as defined in Shape.- See Also:
-
estimateUnion
Estimates the number of items in the union of this Bloom filter with the other bloom filter.This produces an estimate roughly equivalent to the number of unique Hashers that have been merged into either of the filters by rounding the value from the calculation described in the
Shapeclass Javadoc.estimateUnionshould only be called with Bloom filters of the same Shape. If called on Bloom filters of differing shape this method is not symmetric. Ifotherhas more bits anIllegalArgumentExceptionmay be thrown.- Parameters:
other- The other Bloom filter- Returns:
- an estimate of the number of items in the union. Will return Integer.MAX_VALUE if the estimate is larger than Integer.MAX_VALUE.
- See Also:
-
getShape
-
isEmpty
Determines if all the bits are off. This is equivalent tocardinality() == 0.Note: This method is optimized for non-sparse filters. Implementers are encouraged to implement faster checks if possible.
- Returns:
trueif no bits are enabled,falseotherwise.
-
isFull
Determines if the bloom filter is "full".Full is defined as having no unset bits.
- Returns:
trueif the filter is full,falseotherwise.
-
merge
Merges the specified hasher into this Bloom filter. Specifically all bit indexes that are identified by thebitMapExtractorwill be enabled in this filter.Note: This method should return
trueeven if no additional bit indexes were enabled. Afalseresult indicates that this filter may or may not contain all the indexes enabled in thebitMapExtractor. This state may occur in complex Bloom filter implementations like counting Bloom filters.- Parameters:
bitMapExtractor- The BitMapExtractor to merge.- Returns:
- true if the merge was successful
- Throws:
IllegalArgumentException- if bitMapExtractor sends illegal value.
-
merge
Merges the specified Bloom filter into this Bloom filter.Specifically all bit indexes that are identified by the
otherwill be enabled in this filter.Note: This method should return
trueeven if no additional bit indexes were enabled. Afalseresult indicates that this filter may or may not contain theotherBloom filter. This state may occur in complex Bloom filter implementations like counting Bloom filters.- Parameters:
other- The bloom filter to merge into this one.- Returns:
- true if the merge was successful
-
merge
Merges the specified hasher into this Bloom filter. Specifically all bit indexes that are identified by thehasherwill be enabled in this filter.Note: This method should return
trueeven if no additional bit indexes were enabled. Afalseresult indicates that this filter may or may not contain thehashervalues. This state may occur in complex Bloom filter implementations like counting Bloom filters.- Parameters:
hasher- The hasher to merge.- Returns:
- true if the merge was successful
- Throws:
IllegalArgumentException- if hasher produces an illegal value.
-
merge
Merges the specified IndexExtractor into this Bloom filter. Specifically all bit indexes that are identified by theindexExtractorwill be enabled in this filter.Note: This method should return
trueeven if no additional bit indexes were enabled. Afalseresult indicates that this filter may or may not contain all the indexes of theindexExtractor. This state may occur in complex Bloom filter implementations like counting Bloom filters.- Parameters:
indexExtractor- The IndexExtractor to merge.- Returns:
- true if the merge was successful
- Throws:
IllegalArgumentException- if indexExtractor sends illegal value.
-
uniqueIndices
Most Bloom filters create unique IndexExtractors.- Specified by:
uniqueIndicesin interfaceIndexExtractor- Returns:
- the IndexExtractor of unique values.
-