Java Bloom Filter 技术文档

1. 安装指南

1.1 通过 JAR 文件安装

1. 从 GitHub 下载最新版本的 java-bloomfilter 项目。
2. 使用 ant 命令编译项目：

   ant
   

3. 编译完成后，将生成的 dist/java-bloomfilter.jar 文件添加到你的项目中。

1.2 通过源码集成

1. 从 GitHub 下载 BloomFilter.java 文件。
2. 将 BloomFilter.java 文件直接复制到你的项目中。
3. 确保保留文件中的 LGPL 许可证注释，并引用 java-bloomfilter 的网页。

2. 项目的使用说明

2.1 创建 Bloom Filter

要创建一个空的 Bloom Filter，可以使用以下代码：

double falsePositiveProbability = 0.1;
int expectedNumberOfElements = 100;

BloomFilter<String> bloomFilter = new BloomFilter<String>(falsePositiveProbability, expectedNumberOfElements);

构造函数会根据给定的误判概率和预期元素数量，自动选择合适的长度和哈希函数数量。

2.2 添加元素

使用 add() 方法向 Bloom Filter 中添加元素：

bloomFilter.add("foo");

2.3 检查元素

使用 contains() 方法检查元素是否存在于 Bloom Filter 中：

bloomFilter.contains("foo"); // 返回 true

注意，contains() 方法可能会返回误判结果（false positive），但不会出现漏判（false negative）。

2.4 完整示例

以下是一个完整的示例代码：

double falsePositiveProbability = 0.1;
int expectedSize = 100;

BloomFilter<String> bloomFilter = new BloomFilter<String>(falsePositiveProbability, expectedSize);

bloomFilter.add("foo");

if (bloomFilter.contains("foo")) { // 总是返回 true
    System.out.println("BloomFilter contains foo!"); 
    System.out.println("Probability of a false positive: " + bloomFilter.expectedFalsePositiveProbability());
}

if (bloomFilter.contains("bar")) { // 应该返回 false，但可能会返回 true
    System.out.println("There was a false positive.");
}

3. 项目 API 使用文档

3.1 构造函数

• BloomFilter(double falsePositiveProbability, int expectedNumberOfElements)

  • 根据误判概率和预期元素数量创建 Bloom Filter。

• BloomFilter(int bitSetSize, int expectedNumberOfElements)

  • 根据位集大小和预期元素数量创建 Bloom Filter。

• BloomFilter(int bitSetSize, int expectedNumberOfElements, int numberOfHashFunctions)

  • 根据位集大小、预期元素数量和哈希函数数量创建 Bloom Filter。

3.2 方法

• void add(T element)

  • 向 Bloom Filter 中添加元素。

• boolean contains(T element)

  • 检查元素是否存在于 Bloom Filter 中。

• double expectedFalsePositiveProbability()

  • 返回预期的误判概率。

• int getExpectedBitsPerElement()

  • 返回预期的每元素位数。

• int getBitsPerElement()

  • 返回实际的每元素位数。

4. 项目安装方式

4.1 通过 JAR 文件安装

1. 下载并编译项目。
2. 将生成的 dist/java-bloomfilter.jar 文件添加到你的项目中。

4.2 通过源码集成

1. 下载 BloomFilter.java 文件。
2. 将文件直接复制到你的项目中，并保留 LGPL 许可证注释。