1 /*
2 * Copyright (C) 2011 The Guava Authors
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14
15 package com.google.common.hash;
16
17 import static com.google.common.base.Preconditions.checkArgument;
18 import static com.google.common.base.Preconditions.checkNotNull;
19
20 import com.google.common.annotations.Beta;
21 import com.google.common.annotations.VisibleForTesting;
22 import com.google.common.base.Objects;
23 import com.google.common.base.Predicate;
24 import com.google.common.hash.BloomFilterStrategies.LockFreeBitArray;
25 import com.google.common.math.DoubleMath;
26 import com.google.common.primitives.SignedBytes;
27 import com.google.common.primitives.UnsignedBytes;
28 import com.google.errorprone.annotations.CanIgnoreReturnValue;
29 import java.io.DataInputStream;
30 import java.io.DataOutputStream;
31 import java.io.IOException;
32 import java.io.InputStream;
33 import java.io.OutputStream;
34 import java.io.Serializable;
35 import java.math.RoundingMode;
36 import java.util.stream.Collector;
37 import javax.annotation.CheckForNull;
38 import org.checkerframework.checker.nullness.qual.Nullable;
39
40 /**
41 * A Bloom filter for instances of {@code T}. A Bloom filter offers an approximate containment test
42 * with one-sided error: if it claims that an element is contained in it, this might be in error,
43 * but if it claims that an element is <i>not</i> contained in it, then this is definitely true.
44 *
45 * <p>If you are unfamiliar with Bloom filters, this nice <a
46 * href="http://llimllib.github.com/bloomfilter-tutorial/">tutorial</a> may help you understand how
47 * they work.
48 *
49 * <p>The false positive probability ({@code FPP}) of a Bloom filter is defined as the probability
50 * that {@linkplain #mightContain(Object)} will erroneously return {@code true} for an object that
51 * has not actually been put in the {@code BloomFilter}.
52 *
53 * <p>Bloom filters are serializable. They also support a more compact serial representation via the
54 * {@link #writeTo} and {@link #readFrom} methods. Both serialized forms will continue to be
55 * supported by future versions of this library. However, serial forms generated by newer versions
56 * of the code may not be readable by older versions of the code (e.g., a serialized Bloom filter
57 * generated today may <i>not</i> be readable by a binary that was compiled 6 months ago).
58 *
59 * <p>As of Guava 23.0, this class is thread-safe and lock-free. It internally uses atomics and
60 * compare-and-swap to ensure correctness when multiple threads are used to access it.
61 *
62 * @param <T> the type of instances that the {@code BloomFilter} accepts
63 * @author Dimitris Andreou
64 * @author Kevin Bourrillion
65 * @since 11.0 (thread-safe since 23.0)
66 */
67 @Beta
68 @ElementTypesAreNonnullByDefault
69 public final class BloomFilter<T extends @Nullable Object> implements Predicate<T>, Serializable {
70 /**
71 * A strategy to translate T instances, to {@code numHashFunctions} bit indexes.
72 *
73 * <p>Implementations should be collections of pure functions (i.e. stateless).
74 */
75 interface Strategy extends java.io.Serializable {
76
77 /**
78 * Sets {@code numHashFunctions} bits of the given bit array, by hashing a user element.
79 *
80 * <p>Returns whether any bits changed as a result of this operation.
81 */
82 <T extends @Nullable Object> boolean put(
83 @ParametricNullness T object,
84 Funnel<? super T> funnel,
85 int numHashFunctions,
86 LockFreeBitArray bits);
87
88 /**
89 * Queries {@code numHashFunctions} bits of the given bit array, by hashing a user element;
90 * returns {@code true} if and only if all selected bits are set.
91 */
92 <T extends @Nullable Object> boolean mightContain(
93 @ParametricNullness T object,
94 Funnel<? super T> funnel,
95 int numHashFunctions,
96 LockFreeBitArray bits);
97
98 /**
99 * Identifier used to encode this strategy, when marshalled as part of a BloomFilter. Only
100 * values in the [-128, 127] range are valid for the compact serial form. Non-negative values
101 * are reserved for enums defined in BloomFilterStrategies; negative values are reserved for any
102 * custom, stateful strategy we may define (e.g. any kind of strategy that would depend on user
103 * input).
104 */
105 int ordinal();
106 }
107
108 /** The bit set of the BloomFilter (not necessarily power of 2!) */
109 private final LockFreeBitArray bits;
110
111 /** Number of hashes per element */
112 private final int numHashFunctions;
113
114 /** The funnel to translate Ts to bytes */
115 private final Funnel<? super T> funnel;
116
117 /** The strategy we employ to map an element T to {@code numHashFunctions} bit indexes. */
118 private final Strategy strategy;
119
120 /** Creates a BloomFilter. */
121 private BloomFilter(
122 LockFreeBitArray bits, int numHashFunctions, Funnel<? super T> funnel, Strategy strategy) {
123 checkArgument(numHashFunctions > 0, "numHashFunctions (%s) must be > 0", numHashFunctions);
124 checkArgument(
125 numHashFunctions <= 255, "numHashFunctions (%s) must be <= 255", numHashFunctions);
126 this.bits = checkNotNull(bits);
127 this.numHashFunctions = numHashFunctions;
128 this.funnel = checkNotNull(funnel);
129 this.strategy = checkNotNull(strategy);
130 }
131
132 /**
133 * Creates a new {@code BloomFilter} that's a copy of this instance. The new instance is equal to
134 * this instance but shares no mutable state.
135 *
136 * @since 12.0
137 */
138 public BloomFilter<T> copy() {
139 return new BloomFilter<T>(bits.copy(), numHashFunctions, funnel, strategy);
140 }
141
142 /**
143 * Returns {@code true} if the element <i>might</i> have been put in this Bloom filter, {@code
144 * false} if this is <i>definitely</i> not the case.
145 */
146 public boolean mightContain(@ParametricNullness T object) {
147 return strategy.mightContain(object, funnel, numHashFunctions, bits);
148 }
149
150 /**
151 * @deprecated Provided only to satisfy the {@link Predicate} interface; use {@link #mightContain}
152 * instead.
153 */
154 @Deprecated
155 @Override
156 public boolean apply(@ParametricNullness T input) {
157 return mightContain(input);
158 }
159
160 /**
161 * Puts an element into this {@code BloomFilter}. Ensures that subsequent invocations of {@link
162 * #mightContain(Object)} with the same element will always return {@code true}.
163 *
164 * @return true if the Bloom filter's bits changed as a result of this operation. If the bits
165 * changed, this is <i>definitely</i> the first time {@code object} has been added to the
166 * filter. If the bits haven't changed, this <i>might</i> be the first time {@code object} has
167 * been added to the filter. Note that {@code put(t)} always returns the <i>opposite</i>
168 * result to what {@code mightContain(t)} would have returned at the time it is called.
169 * @since 12.0 (present in 11.0 with {@code void} return type})
170 */
171 @CanIgnoreReturnValue
172 public boolean put(@ParametricNullness T object) {
173 return strategy.put(object, funnel, numHashFunctions, bits);
174 }
175
176 /**
177 * Returns the probability that {@linkplain #mightContain(Object)} will erroneously return {@code
178 * true} for an object that has not actually been put in the {@code BloomFilter}.
179 *
180 * <p>Ideally, this number should be close to the {@code fpp} parameter passed in {@linkplain
181 * #create(Funnel, int, double)}, or smaller. If it is significantly higher, it is usually the
182 * case that too many elements (more than expected) have been put in the {@code BloomFilter},
183 * degenerating it.
184 *
185 * @since 14.0 (since 11.0 as expectedFalsePositiveProbability())
186 */
187 public double expectedFpp() {
188 return Math.pow((double) bits.bitCount() / bitSize(), numHashFunctions);
189 }
190
191 /**
192 * Returns an estimate for the total number of distinct elements that have been added to this
193 * Bloom filter. This approximation is reasonably accurate if it does not exceed the value of
194 * {@code expectedInsertions} that was used when constructing the filter.
195 *
196 * @since 22.0
197 */
198 public long approximateElementCount() {
199 long bitSize = bits.bitSize();
200 long bitCount = bits.bitCount();
201
202 /**
203 * Each insertion is expected to reduce the # of clear bits by a factor of
204 * `numHashFunctions/bitSize`. So, after n insertions, expected bitCount is `bitSize * (1 - (1 -
205 * numHashFunctions/bitSize)^n)`. Solving that for n, and approximating `ln x` as `x - 1` when x
206 * is close to 1 (why?), gives the following formula.
207 */
208 double fractionOfBitsSet = (double) bitCount / bitSize;
209 return DoubleMath.roundToLong(
210 -Math.log1p(-fractionOfBitsSet) * bitSize / numHashFunctions, RoundingMode.HALF_UP);
211 }
212
213 /** Returns the number of bits in the underlying bit array. */
214 @VisibleForTesting
215 long bitSize() {
216 return bits.bitSize();
217 }
218
219 /**
220 * Determines whether a given Bloom filter is compatible with this Bloom filter. For two Bloom
221 * filters to be compatible, they must:
222 *
223 * <ul>
224 * <li>not be the same instance
225 * <li>have the same number of hash functions
226 * <li>have the same bit size
227 * <li>have the same strategy
228 * <li>have equal funnels
229 * </ul>
230 *
231 * @param that The Bloom filter to check for compatibility.
232 * @since 15.0
233 */
234 public boolean isCompatible(BloomFilter<T> that) {
235 checkNotNull(that);
236 return this != that
237 && this.numHashFunctions == that.numHashFunctions
238 && this.bitSize() == that.bitSize()
239 && this.strategy.equals(that.strategy)
240 && this.funnel.equals(that.funnel);
241 }
242
243 /**
244 * Combines this Bloom filter with another Bloom filter by performing a bitwise OR of the
245 * underlying data. The mutations happen to <b>this</b> instance. Callers must ensure the Bloom
246 * filters are appropriately sized to avoid saturating them.
247 *
248 * @param that The Bloom filter to combine this Bloom filter with. It is not mutated.
249 * @throws IllegalArgumentException if {@code isCompatible(that) == false}
250 * @since 15.0
251 */
252 public void putAll(BloomFilter<T> that) {
253 checkNotNull(that);
254 checkArgument(this != that, "Cannot combine a BloomFilter with itself.");
255 checkArgument(
256 this.numHashFunctions == that.numHashFunctions,
257 "BloomFilters must have the same number of hash functions (%s != %s)",
258 this.numHashFunctions,
259 that.numHashFunctions);
260 checkArgument(
261 this.bitSize() == that.bitSize(),
262 "BloomFilters must have the same size underlying bit arrays (%s != %s)",
263 this.bitSize(),
264 that.bitSize());
265 checkArgument(
266 this.strategy.equals(that.strategy),
267 "BloomFilters must have equal strategies (%s != %s)",
268 this.strategy,
269 that.strategy);
270 checkArgument(
271 this.funnel.equals(that.funnel),
272 "BloomFilters must have equal funnels (%s != %s)",
273 this.funnel,
274 that.funnel);
275 this.bits.putAll(that.bits);
276 }
277
278 @Override
279 public boolean equals(@CheckForNull Object object) {
280 if (object == this) {
281 return true;
282 }
283 if (object instanceof BloomFilter) {
284 BloomFilter<?> that = (BloomFilter<?>) object;
285 return this.numHashFunctions == that.numHashFunctions
286 && this.funnel.equals(that.funnel)
287 && this.bits.equals(that.bits)
288 && this.strategy.equals(that.strategy);
289 }
290 return false;
291 }
292
293 @Override
294 public int hashCode() {
295 return Objects.hashCode(numHashFunctions, funnel, strategy, bits);
296 }
297
298 /**
299 * Returns a {@code Collector} expecting the specified number of insertions, and yielding a {@link
300 * BloomFilter} with false positive probability 3%.
301 *
302 * <p>Note that if the {@code Collector} receives significantly more elements than specified, the
303 * resulting {@code BloomFilter} will suffer a sharp deterioration of its false positive
304 * probability.
305 *
306 * <p>The constructed {@code BloomFilter} will be serializable if the provided {@code Funnel<T>}
307 * is.
308 *
309 * <p>It is recommended that the funnel be implemented as a Java enum. This has the benefit of
310 * ensuring proper serialization and deserialization, which is important since {@link #equals}
311 * also relies on object identity of funnels.
312 *
313 * @param funnel the funnel of T's that the constructed {@code BloomFilter} will use
314 * @param expectedInsertions the number of expected insertions to the constructed {@code
315 * BloomFilter}; must be positive
316 * @return a {@code Collector} generating a {@code BloomFilter} of the received elements
317 * @since 23.0
318 */
319 public static <T extends @Nullable Object> Collector<T, ?, BloomFilter<T>> toBloomFilter(
320 Funnel<? super T> funnel, long expectedInsertions) {
321 return toBloomFilter(funnel, expectedInsertions, 0.03);
322 }
323
324 /**
325 * Returns a {@code Collector} expecting the specified number of insertions, and yielding a {@link
326 * BloomFilter} with the specified expected false positive probability.
327 *
328 * <p>Note that if the {@code Collector} receives significantly more elements than specified, the
329 * resulting {@code BloomFilter} will suffer a sharp deterioration of its false positive
330 * probability.
331 *
332 * <p>The constructed {@code BloomFilter} will be serializable if the provided {@code Funnel<T>}
333 * is.
334 *
335 * <p>It is recommended that the funnel be implemented as a Java enum. This has the benefit of
336 * ensuring proper serialization and deserialization, which is important since {@link #equals}
337 * also relies on object identity of funnels.
338 *
339 * @param funnel the funnel of T's that the constructed {@code BloomFilter} will use
340 * @param expectedInsertions the number of expected insertions to the constructed {@code
341 * BloomFilter}; must be positive
342 * @param fpp the desired false positive probability (must be positive and less than 1.0)
343 * @return a {@code Collector} generating a {@code BloomFilter} of the received elements
344 * @since 23.0
345 */
346 public static <T extends @Nullable Object> Collector<T, ?, BloomFilter<T>> toBloomFilter(
347 Funnel<? super T> funnel, long expectedInsertions, double fpp) {
348 checkNotNull(funnel);
349 checkArgument(
350 expectedInsertions >= 0, "Expected insertions (%s) must be >= 0", expectedInsertions);
351 checkArgument(fpp > 0.0, "False positive probability (%s) must be > 0.0", fpp);
352 checkArgument(fpp < 1.0, "False positive probability (%s) must be < 1.0", fpp);
353 return Collector.of(
354 () -> BloomFilter.create(funnel, expectedInsertions, fpp),
355 BloomFilter::put,
356 (bf1, bf2) -> {
357 bf1.putAll(bf2);
358 return bf1;
359 },
360 Collector.Characteristics.UNORDERED,
361 Collector.Characteristics.CONCURRENT);
362 }
363
364 /**
365 * Creates a {@link BloomFilter} with the expected number of insertions and expected false
366 * positive probability.
367 *
368 * <p>Note that overflowing a {@code BloomFilter} with significantly more elements than specified,
369 * will result in its saturation, and a sharp deterioration of its false positive probability.
370 *
371 * <p>The constructed {@code BloomFilter} will be serializable if the provided {@code Funnel<T>}
372 * is.
373 *
374 * <p>It is recommended that the funnel be implemented as a Java enum. This has the benefit of
375 * ensuring proper serialization and deserialization, which is important since {@link #equals}
376 * also relies on object identity of funnels.
377 *
378 * @param funnel the funnel of T's that the constructed {@code BloomFilter} will use
379 * @param expectedInsertions the number of expected insertions to the constructed {@code
380 * BloomFilter}; must be positive
381 * @param fpp the desired false positive probability (must be positive and less than 1.0)
382 * @return a {@code BloomFilter}
383 */
384 public static <T extends @Nullable Object> BloomFilter<T> create(
385 Funnel<? super T> funnel, int expectedInsertions, double fpp) {
386 return create(funnel, (long) expectedInsertions, fpp);
387 }
388
389 /**
390 * Creates a {@link BloomFilter} with the expected number of insertions and expected false
391 * positive probability.
392 *
393 * <p>Note that overflowing a {@code BloomFilter} with significantly more elements than specified,
394 * will result in its saturation, and a sharp deterioration of its false positive probability.
395 *
396 * <p>The constructed {@code BloomFilter} will be serializable if the provided {@code Funnel<T>}
397 * is.
398 *
399 * <p>It is recommended that the funnel be implemented as a Java enum. This has the benefit of
400 * ensuring proper serialization and deserialization, which is important since {@link #equals}
401 * also relies on object identity of funnels.
402 *
403 * @param funnel the funnel of T's that the constructed {@code BloomFilter} will use
404 * @param expectedInsertions the number of expected insertions to the constructed {@code
405 * BloomFilter}; must be positive
406 * @param fpp the desired false positive probability (must be positive and less than 1.0)
407 * @return a {@code BloomFilter}
408 * @since 19.0
409 */
410 public static <T extends @Nullable Object> BloomFilter<T> create(
411 Funnel<? super T> funnel, long expectedInsertions, double fpp) {
412 return create(funnel, expectedInsertions, fpp, BloomFilterStrategies.MURMUR128_MITZ_64);
413 }
414
415 @VisibleForTesting
416 static <T extends @Nullable Object> BloomFilter<T> create(
417 Funnel<? super T> funnel, long expectedInsertions, double fpp, Strategy strategy) {
418 checkNotNull(funnel);
419 checkArgument(
420 expectedInsertions >= 0, "Expected insertions (%s) must be >= 0", expectedInsertions);
421 checkArgument(fpp > 0.0, "False positive probability (%s) must be > 0.0", fpp);
422 checkArgument(fpp < 1.0, "False positive probability (%s) must be < 1.0", fpp);
423 checkNotNull(strategy);
424
425 if (expectedInsertions == 0) {
426 expectedInsertions = 1;
427 }
428 /*
429 * TODO(user): Put a warning in the javadoc about tiny fpp values, since the resulting size
430 * is proportional to -log(p), but there is not much of a point after all, e.g.
431 * optimalM(1000, 0.0000000000000001) = 76680 which is less than 10kb. Who cares!
432 */
433 long numBits = optimalNumOfBits(expectedInsertions, fpp);
434 int numHashFunctions = optimalNumOfHashFunctions(expectedInsertions, numBits);
435 try {
436 return new BloomFilter<T>(new LockFreeBitArray(numBits), numHashFunctions, funnel, strategy);
437 } catch (IllegalArgumentException e) {
438 throw new IllegalArgumentException("Could not create BloomFilter of " + numBits + " bits", e);
439 }
440 }
441
442 /**
443 * Creates a {@link BloomFilter} with the expected number of insertions and a default expected
444 * false positive probability of 3%.
445 *
446 * <p>Note that overflowing a {@code BloomFilter} with significantly more elements than specified,
447 * will result in its saturation, and a sharp deterioration of its false positive probability.
448 *
449 * <p>The constructed {@code BloomFilter} will be serializable if the provided {@code Funnel<T>}
450 * is.
451 *
452 * <p>It is recommended that the funnel be implemented as a Java enum. This has the benefit of
453 * ensuring proper serialization and deserialization, which is important since {@link #equals}
454 * also relies on object identity of funnels.
455 *
456 * @param funnel the funnel of T's that the constructed {@code BloomFilter} will use
457 * @param expectedInsertions the number of expected insertions to the constructed {@code
458 * BloomFilter}; must be positive
459 * @return a {@code BloomFilter}
460 */
461 public static <T extends @Nullable Object> BloomFilter<T> create(
462 Funnel<? super T> funnel, int expectedInsertions) {
463 return create(funnel, (long) expectedInsertions);
464 }
465
466 /**
467 * Creates a {@link BloomFilter} with the expected number of insertions and a default expected
468 * false positive probability of 3%.
469 *
470 * <p>Note that overflowing a {@code BloomFilter} with significantly more elements than specified,
471 * will result in its saturation, and a sharp deterioration of its false positive probability.
472 *
473 * <p>The constructed {@code BloomFilter} will be serializable if the provided {@code Funnel<T>}
474 * is.
475 *
476 * <p>It is recommended that the funnel be implemented as a Java enum. This has the benefit of
477 * ensuring proper serialization and deserialization, which is important since {@link #equals}
478 * also relies on object identity of funnels.
479 *
480 * @param funnel the funnel of T's that the constructed {@code BloomFilter} will use
481 * @param expectedInsertions the number of expected insertions to the constructed {@code
482 * BloomFilter}; must be positive
483 * @return a {@code BloomFilter}
484 * @since 19.0
485 */
486 public static <T extends @Nullable Object> BloomFilter<T> create(
487 Funnel<? super T> funnel, long expectedInsertions) {
488 return create(funnel, expectedInsertions, 0.03); // FYI, for 3%, we always get 5 hash functions
489 }
490
491 // Cheat sheet:
492 //
493 // m: total bits
494 // n: expected insertions
495 // b: m/n, bits per insertion
496 // p: expected false positive probability
497 //
498 // 1) Optimal k = b * ln2
499 // 2) p = (1 - e ^ (-kn/m))^k
500 // 3) For optimal k: p = 2 ^ (-k) ~= 0.6185^b
501 // 4) For optimal k: m = -nlnp / ((ln2) ^ 2)
502
503 /**
504 * Computes the optimal k (number of hashes per element inserted in Bloom filter), given the
505 * expected insertions and total number of bits in the Bloom filter.
506 *
507 * <p>See http://en.wikipedia.org/wiki/File:Bloom_filter_fp_probability.svg for the formula.
508 *
509 * @param n expected insertions (must be positive)
510 * @param m total number of bits in Bloom filter (must be positive)
511 */
512 @VisibleForTesting
513 static int optimalNumOfHashFunctions(long n, long m) {
514 // (m / n) * log(2), but avoid truncation due to division!
515 return Math.max(1, (int) Math.round((double) m / n * Math.log(2)));
516 }
517
518 /**
519 * Computes m (total bits of Bloom filter) which is expected to achieve, for the specified
520 * expected insertions, the required false positive probability.
521 *
522 * <p>See http://en.wikipedia.org/wiki/Bloom_filter#Probability_of_false_positives for the
523 * formula.
524 *
525 * @param n expected insertions (must be positive)
526 * @param p false positive rate (must be 0 < p < 1)
527 */
528 @VisibleForTesting
529 static long optimalNumOfBits(long n, double p) {
530 if (p == 0) {
531 p = Double.MIN_VALUE;
532 }
533 return (long) (-n * Math.log(p) / (Math.log(2) * Math.log(2)));
534 }
535
536 private Object writeReplace() {
537 return new SerialForm<T>(this);
538 }
539
540 private static class SerialForm<T extends @Nullable Object> implements Serializable {
541 final long[] data;
542 final int numHashFunctions;
543 final Funnel<? super T> funnel;
544 final Strategy strategy;
545
546 SerialForm(BloomFilter<T> bf) {
547 this.data = LockFreeBitArray.toPlainArray(bf.bits.data);
548 this.numHashFunctions = bf.numHashFunctions;
549 this.funnel = bf.funnel;
550 this.strategy = bf.strategy;
551 }
552
553 Object readResolve() {
554 return new BloomFilter<T>(new LockFreeBitArray(data), numHashFunctions, funnel, strategy);
555 }
556
557 private static final long serialVersionUID = 1;
558 }
559
560 /**
561 * Writes this {@code BloomFilter} to an output stream, with a custom format (not Java
562 * serialization). This has been measured to save at least 400 bytes compared to regular
563 * serialization.
564 *
565 * <p>Use {@linkplain #readFrom(InputStream, Funnel)} to reconstruct the written BloomFilter.
566 */
567 public void writeTo(OutputStream out) throws IOException {
568 // Serial form:
569 // 1 signed byte for the strategy
570 // 1 unsigned byte for the number of hash functions
571 // 1 big endian int, the number of longs in our bitset
572 // N big endian longs of our bitset
573 DataOutputStream dout = new DataOutputStream(out);
574 dout.writeByte(SignedBytes.checkedCast(strategy.ordinal()));
575 dout.writeByte(UnsignedBytes.checkedCast(numHashFunctions)); // note: checked at the c'tor
576 dout.writeInt(bits.data.length());
577 for (int i = 0; i < bits.data.length(); i++) {
578 dout.writeLong(bits.data.get(i));
579 }
580 }
581
582 /**
583 * Reads a byte stream, which was written by {@linkplain #writeTo(OutputStream)}, into a {@code
584 * BloomFilter}.
585 *
586 * <p>The {@code Funnel} to be used is not encoded in the stream, so it must be provided here.
587 * <b>Warning:</b> the funnel provided <b>must</b> behave identically to the one used to populate
588 * the original Bloom filter!
589 *
590 * @throws IOException if the InputStream throws an {@code IOException}, or if its data does not
591 * appear to be a BloomFilter serialized using the {@linkplain #writeTo(OutputStream)} method.
592 */
593 public static <T extends @Nullable Object> BloomFilter<T> readFrom(
594 InputStream in, Funnel<? super T> funnel) throws IOException {
595 checkNotNull(in, "InputStream");
596 checkNotNull(funnel, "Funnel");
597 int strategyOrdinal = -1;
598 int numHashFunctions = -1;
599 int dataLength = -1;
600 try {
601 DataInputStream din = new DataInputStream(in);
602 // currently this assumes there is no negative ordinal; will have to be updated if we
603 // add non-stateless strategies (for which we've reserved negative ordinals; see
604 // Strategy.ordinal()).
605 strategyOrdinal = din.readByte();
606 numHashFunctions = UnsignedBytes.toInt(din.readByte());
607 dataLength = din.readInt();
608
609 Strategy strategy = BloomFilterStrategies.values()[strategyOrdinal];
610 long[] data = new long[dataLength];
611 for (int i = 0; i < data.length; i++) {
612 data[i] = din.readLong();
613 }
614 return new BloomFilter<T>(new LockFreeBitArray(data), numHashFunctions, funnel, strategy);
615 } catch (RuntimeException e) {
616 String message =
617 "Unable to deserialize BloomFilter from InputStream."
618 + " strategyOrdinal: "
619 + strategyOrdinal
620 + " numHashFunctions: "
621 + numHashFunctions
622 + " dataLength: "
623 + dataLength;
624 throw new IOException(message, e);
625 }
626 }
627 }