Guide to the Guava BiMap – 番石榴生物图指南

最后修改: 2017年 1月 18日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

In this tutorial, we’ll show how to use the Google Guava’s BiMap interface and its multiple implementations.

在本教程中，我们将展示如何使用Google Guava的BiMap接口及其多种实现。

A BiMap (or “bidirectional map”) is a special kind of a map that maintains an inverse view of the map while ensuring that no duplicate values are present and a value can always be used safely to get the key back.

BiMap（或 “双向地图”）是一种特殊的地图，它保持着地图的反向视图，同时确保没有重复的值，并且一个值总是可以被安全地用来取回键。

The basic implementation of BiMap is HashBiMap where internally it makes use of two Maps, one for the key to value mapping and the other for the value to key mapping.

BiMap的基本实现是HashBiMap，它在内部使用了两个Map，一个用于键到值的映射，另一个用于值到键的映射。

2. Google Guava’s BiMap

2.Google Guava的BiMap

Let’s have a look at how to use the BiMap class.

让我们看一下如何使用BiMap类。

We’ll start by adding the Google Guava library dependency in the pom.xml:

我们将首先在pom.xml中添加Google Guava库的依赖关系。

<dependency>
    <groupId>com.google.guava</groupId>
    <artifactId>guava</artifactId>
    <version>31.0.1-jre</version>
</dependency>

The latest version of the dependency can be checked here.

最新版本的依赖关系可以在这里查看。

3. Creating a BiMap

3.创建一个BiMap

You can create an instance of BiMap in multiple ways as follows:

您可以通过以下多种方式创建BiMap的实例。

  • If you are going to deal with a custom Java object, use the create method from the class HashBiMap:
BiMap<String, String> capitalCountryBiMap = HashBiMap.create();
  • If we already have an existing map, you may create an instance of a BiMap using an overloaded version of the create method from a class HashBiMap:
Map<String, String> capitalCountryBiMap = new HashMap<>();
//...
HashBiMap.create(capitalCountryBiMap);
  • If you are going to deal with a key of type Enum, use the create method from the class EnumHashBiMap:
BiMap<MyEnum, String> operationStringBiMap = EnumHashBiMap.create(MyEnum.class);
  • If you intend to create an immutable map, use the ImmutableBiMap class (which follows a builder pattern):
BiMap<String, String> capitalCountryBiMap
  = new ImmutableBiMap.Builder<>()
    .put("New Delhi", "India")
    .build();

4. Using the BiMap

4.使用生物地图

Let’s start with a simple example showing the usage of BiMap, where we can get a key based on a value and a value based on a key:

让我们从一个简单的例子开始，展示BiMap的用法，我们可以根据一个值得到一个键，根据一个键得到一个值。

@Test
public void givenBiMap_whenQueryByValue_shouldReturnKey() {
    BiMap<String, String> capitalCountryBiMap = HashBiMap.create();
    capitalCountryBiMap.put("New Delhi", "India");
    capitalCountryBiMap.put("Washington, D.C.", "USA");
    capitalCountryBiMap.put("Moscow", "Russia");

    String keyFromBiMap = capitalCountryBiMap.inverse().get("Russia");
    String valueFromBiMap = capitalCountryBiMap.get("Washington, D.C.");
 
    assertEquals("Moscow", keyFromBiMap);
    assertEquals("USA", valueFromBiMap);
}

Note: the inverse method above returns the inverse view of the BiMap, which maps each of the BiMap’s values to its associated keys.

注意：上面的inverse方法返回BiMap的反向视图，它将BiMap的每个值映射到其相关的键。

BiMap throws an IllegalArgumentException when we try to store a duplicate value twice.

BiMap当我们试图两次存储一个重复的值时，会抛出一个IllegalArgumentException。

Let’s see an example of the same:

让我们看一个同样的例子。

@Test(expected = IllegalArgumentException.class)
public void givenBiMap_whenSameValueIsPresent_shouldThrowException() {
    BiMap<String, String> capitalCountryBiMap = HashBiMap.create();
    capitalCountryBiMap.put("Mumbai", "India");
    capitalCountryBiMap.put("Washington, D.C.", "USA");
    capitalCountryBiMap.put("Moscow", "Russia");
    capitalCountryBiMap.put("New Delhi", "India");
}

If we wish to override the value already present in BiMap, we can make use of the forcePut method:

如果我们希望覆盖BiMap中已经存在的值，我们可以利用forcePut方法。

@Test
public void givenSameValueIsPresent_whenForcePut_completesSuccessfully() {
    BiMap<String, String> capitalCountryBiMap = HashBiMap.create();
    capitalCountryBiMap.put("Mumbai", "India");
    capitalCountryBiMap.put("Washington, D.C.", "USA");
    capitalCountryBiMap.put("Moscow", "Russia");
    capitalCountryBiMap.forcePut("New Delhi", "India");

    assertEquals("USA", capitalCountryBiMap.get("Washington, D.C."));
    assertEquals("Washington, D.C.", capitalCountryBiMap.inverse().get("USA"));
}

5. Conclusion

5.结论

In this concise tutorial, we illustrated examples of using the BiMap in the Guava library. It is predominantly used to get a key based on the value from the map.

在这个简洁的教程中，我们说明了Guava库中使用BiMap的例子。它主要是用来根据地图的值来获得一个键。

The implementation of these examples can be found in the GitHub project – this is a Maven-based project, so it should be easy to import and run as-is.

这些例子的实现可以在GitHub项目中找到–这是一个基于Maven的项目，所以应该很容易导入并按原样运行。