BloomFilter
Date: 2016-05-24

com.google.common.hash

## Class BloomFilter<T>

- java.lang.Object
- - com.google.common.hash.BloomFilter<T>

- Type Parameters:
    `T` - the type of instances that the `BloomFilter` accepts
  All Implemented Interfaces:
    Predicate<T>, java.io.Serializable

      @Beta
      public final class BloomFilter<T>
      extends java.lang.Object
      implements Predicate<T>, java.io.Serializable

  A Bloom filter for instances of `T`. A Bloom filter offers an approximate containment test with one-sided error: if it claims that an element is contained in it, this might be in error, but if it claims that an element is not contained in it, then this is definitely true.

  If you are unfamiliar with Bloom filters, this nice tutorial may help you understand how they work.

  The false positive probability (`FPP`) of a bloom filter is defined as the probability that mightContain(Object) will erroneously return `true` for an object that has not actually been put in the `BloomFilter`.

  Bloom filters are serializable. They also support a more compact serial representation via the `writeTo(java.io.OutputStream)` and `readFrom(java.io.InputStream, com.google.common.hash.Funnel<T>)` methods. Both serialized forms will continue to be supported by future versions of this library. However, serial forms generated by newer versions of the code may not be readable by older versions of the code (e.g., a serialized bloom filter generated today may not be readable by a binary that was compiled 6 months ago).

  Since:
    11.0
  See Also:
    Serialized Form

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `apply(T input)` Deprecated. Provided only to satisfy the `Predicate` interface; use `mightContain(T)` instead.
    `BloomFilter<T>` | `copy()` Creates a new `BloomFilter` that's a copy of this instance.
    `static <T> BloomFilter<T>` | `create(Funnel<? super T> funnel, int expectedInsertions)` Creates a `BloomFilter` with the expected number of insertions and a default expected false positive probability of 3%.
    `static <T> BloomFilter<T>` | `create(Funnel<? super T> funnel, int expectedInsertions, double fpp)` Creates a `BloomFilter` with the expected number of insertions and expected false positive probability.
    `static <T> BloomFilter<T>` | `create(Funnel<? super T> funnel, long expectedInsertions)` Creates a `BloomFilter` with the expected number of insertions and a default expected false positive probability of 3%.
    `static <T> BloomFilter<T>` | `create(Funnel<? super T> funnel, long expectedInsertions, double fpp)` Creates a `BloomFilter` with the expected number of insertions and expected false positive probability.
    `boolean` | `equals(java.lang.Object object)` Indicates whether another object is equal to this predicate.
    `double` | `expectedFpp()` Returns the probability that mightContain(Object) will erroneously return `true` for an object that has not actually been put in the `BloomFilter`.
    `int` | `hashCode()`
    `boolean` | `isCompatible(BloomFilter<T> that)` Determines whether a given bloom filter is compatible with this bloom filter.
    `boolean` | `mightContain(T object)` Returns `true` if the element might have been put in this Bloom filter, `false` if this is definitely not the case.
    `boolean` | `put(T object)` Puts an element into this `BloomFilter`.
    `void` | `putAll(BloomFilter<T> that)` Combines this bloom filter with another bloom filter by performing a bitwise OR of the underlying data.
    `static <T> BloomFilter<T>` | `readFrom(java.io.InputStream in, Funnel<T> funnel)` Reads a byte stream, which was written by writeTo(OutputStream), into a `BloomFilter<T>`.
    `void` | `writeTo(java.io.OutputStream out)` Writes this `BloomFilter` to an output stream, with a custom format (not Java serialization).

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### copy

          @CheckReturnValue
          public BloomFilter<T> copy()

      Creates a new `BloomFilter` that's a copy of this instance. The new instance is equal to this instance but shares no mutable state.
      Since:
        12.0

    - #### mightContain

          @CheckReturnValue
          public boolean mightContain(T object)

      Returns `true` if the element might have been put in this Bloom filter, `false` if this is definitely not the case.

    - #### apply

          @Deprecated
          @CheckReturnValue
          public boolean apply(T input)

      Deprecated. Provided only to satisfy the `Predicate` interface; use `mightContain(T)` instead.
      Description copied from interface: `Predicate`
      Returns the result of applying this predicate to `input`. This method is generally expected, but not absolutely required, to have the following properties:
      - Its execution does not cause any observable side effects.
      - The computation is consistent with equals; that is, `Objects.equal``(a, b)` implies that `predicate.apply(a) == predicate.apply(b))`.
      Specified by:
        `apply` in interface `Predicate<T>`

    - #### put

          public boolean put(T object)

      Puts an element into this `BloomFilter`. Ensures that subsequent invocations of `mightContain(Object)` with the same element will always return `true`.
      Returns:
        true if the bloom filter's bits changed as a result of this operation. If the bits changed, this is definitely the first time `object` has been added to the filter. If the bits haven't changed, this might be the first time `object` has been added to the filter. Note that `put(t)` always returns the opposite result to what `mightContain(t)` would have returned at the time it is called."
      Since:
        12.0 (present in 11.0 with `void` return type})

    - #### expectedFpp

          @CheckReturnValue
          public double expectedFpp()

      Returns the probability that mightContain(Object) will erroneously return `true` for an object that has not actually been put in the `BloomFilter`.

      Ideally, this number should be close to the `fpp` parameter passed in create(Funnel, int, double), or smaller. If it is significantly higher, it is usually the case that too many elements (more than expected) have been put in the `BloomFilter`, degenerating it.

      Since:
        14.0 (since 11.0 as expectedFalsePositiveProbability())

    - #### isCompatible

          @CheckReturnValue
          public boolean isCompatible(BloomFilter<T> that)

      Determines whether a given bloom filter is compatible with this bloom filter. For two bloom filters to be compatible, they must:
      - not be the same instance
      - have the same number of hash functions
      - have the same bit size
      - have the same strategy
      - have equal funnels
      Parameters:
        `that` - The bloom filter to check for compatibility.
      Since:
        15.0

    - #### putAll

          public void putAll(BloomFilter<T> that)

      Combines this bloom filter with another bloom filter by performing a bitwise OR of the underlying data. The mutations happen to this instance. Callers must ensure the bloom filters are appropriately sized to avoid saturating them.
      Parameters:
        `that` - The bloom filter to combine this bloom filter with. It is not mutated.
      Throws:
        `java.lang.IllegalArgumentException` - if `isCompatible(that) == false`
      Since:
        15.0

    - #### equals

          public boolean equals(@Nullable
                       java.lang.Object object)

      Description copied from interface: `Predicate`
      Indicates whether another object is equal to this predicate.

      Most implementations will have no reason to override the behavior of `Object.equals(java.lang.Object)`. However, an implementation may also choose to return `true` whenever `object` is a `Predicate` that it considers interchangeable with this one. "Interchangeable" typically means that `this.apply(t) == that.apply(t)` for all `t` of type `T`). Note that a `false` result from this method does not imply that the predicates are known not to be interchangeable.

      Specified by:
        `equals` in interface `Predicate<T>`
      Overrides:
        `equals` in class `java.lang.Object`

    - #### hashCode

          public int hashCode()

      Overrides:
        `hashCode` in class `java.lang.Object`

    - #### create

          @CheckReturnValue
          public static <T> BloomFilter<T> create(Funnel<? super T> funnel,
                                                   int expectedInsertions,
                                                   double fpp)

      Creates a `BloomFilter` with the expected number of insertions and expected false positive probability.

      Note that overflowing a `BloomFilter` with significantly more elements than specified, will result in its saturation, and a sharp deterioration of its false positive probability.

      The constructed `BloomFilter<T>` will be serializable if the provided `Funnel<T>` is.

      It is recommended that the funnel be implemented as a Java enum. This has the benefit of ensuring proper serialization and deserialization, which is important since `equals(java.lang.Object)` also relies on object identity of funnels.

      Parameters:
        `funnel` - the funnel of T's that the constructed `BloomFilter<T>` will use
        `expectedInsertions` - the number of expected insertions to the constructed `BloomFilter<T>`; must be positive
        `fpp` - the desired false positive probability (must be positive and less than 1.0)
      Returns:
        a `BloomFilter`

    - #### create

          @CheckReturnValue
          public static <T> BloomFilter<T> create(Funnel<? super T> funnel,
                                                   long expectedInsertions,
                                                   double fpp)

      Creates a `BloomFilter` with the expected number of insertions and expected false positive probability.

      Note that overflowing a `BloomFilter` with significantly more elements than specified, will result in its saturation, and a sharp deterioration of its false positive probability.

      The constructed `BloomFilter<T>` will be serializable if the provided `Funnel<T>` is.

      It is recommended that the funnel be implemented as a Java enum. This has the benefit of ensuring proper serialization and deserialization, which is important since `equals(java.lang.Object)` also relies on object identity of funnels.

      Parameters:
        `funnel` - the funnel of T's that the constructed `BloomFilter<T>` will use
        `expectedInsertions` - the number of expected insertions to the constructed `BloomFilter<T>`; must be positive
        `fpp` - the desired false positive probability (must be positive and less than 1.0)
      Returns:
        a `BloomFilter`
      Since:
        19.0

    - #### create

          @CheckReturnValue
          public static <T> BloomFilter<T> create(Funnel<? super T> funnel,
                                                   int expectedInsertions)

      Creates a `BloomFilter` with the expected number of insertions and a default expected false positive probability of 3%.

      Note that overflowing a `BloomFilter` with significantly more elements than specified, will result in its saturation, and a sharp deterioration of its false positive probability.

      The constructed `BloomFilter<T>` will be serializable if the provided `Funnel<T>` is.

      It is recommended that the funnel be implemented as a Java enum. This has the benefit of ensuring proper serialization and deserialization, which is important since `equals(java.lang.Object)` also relies on object identity of funnels.

      Parameters:
        `funnel` - the funnel of T's that the constructed `BloomFilter<T>` will use
        `expectedInsertions` - the number of expected insertions to the constructed `BloomFilter<T>`; must be positive
      Returns:
        a `BloomFilter`

    - #### create

          @CheckReturnValue
          public static <T> BloomFilter<T> create(Funnel<? super T> funnel,
                                                   long expectedInsertions)

      Creates a `BloomFilter` with the expected number of insertions and a default expected false positive probability of 3%.

      Note that overflowing a `BloomFilter` with significantly more elements than specified, will result in its saturation, and a sharp deterioration of its false positive probability.

      The constructed `BloomFilter<T>` will be serializable if the provided `Funnel<T>` is.

      It is recommended that the funnel be implemented as a Java enum. This has the benefit of ensuring proper serialization and deserialization, which is important since `equals(java.lang.Object)` also relies on object identity of funnels.

      Parameters:
        `funnel` - the funnel of T's that the constructed `BloomFilter<T>` will use
        `expectedInsertions` - the number of expected insertions to the constructed `BloomFilter<T>`; must be positive
      Returns:
        a `BloomFilter`
      Since:
        19.0

    - #### writeTo

          public void writeTo(java.io.OutputStream out)
                       throws java.io.IOException

      Writes this `BloomFilter` to an output stream, with a custom format (not Java serialization). This has been measured to save at least 400 bytes compared to regular serialization.

      Use readFrom(InputStream, Funnel) to reconstruct the written BloomFilter.

      Throws:
        `java.io.IOException`

    - #### readFrom

          @CheckReturnValue
          public static <T> BloomFilter<T> readFrom(java.io.InputStream in,
                                                     Funnel<T> funnel)
                                         throws java.io.IOException

      Reads a byte stream, which was written by writeTo(OutputStream), into a `BloomFilter<T>`. The `Funnel` to be used is not encoded in the stream, so it must be provided here. Warning: the funnel provided must behave identically to the one used to populate the original Bloom filter!
      Throws:
        `java.io.IOException` - if the InputStream throws an `IOException`, or if its data does not appear to be a BloomFilter serialized using the writeTo(OutputStream) method.