（翻译）Google Guava Cache

翻译自Google Guava Cache

This Post is a continuation of my series on Google Guava, this time covering Guava Cache. Guava Cache offers more flexibility and power than either a HashMap or ConcurrentHashMap, but is not as heavy as using EHCache or Memcached (or robust for that matter, as Guava Cache operates solely in memory). The Cache interface has methods you would expect to see like ‘get’, and ‘invalidate’. A method you won’t find is ‘put’, because Guava Cache is ‘self-populating’, values that aren’t present when requested are fetched or calculated, then stored. This means a ‘get’ call will never return null. In all fairness, the previous statement is not %100 accurate. There is another method ‘asMap’ that exposes the entries in the cache as a thread safe map. Using ‘asMap’ will result in not having any of the self loading operations performed, so calls to ‘get’ will return null if the value is not present (What fun is that?). Although this is a post about Guava Cache, I am going to spend the bulk of the time talking about CacheLoader and CacheBuilder. CacheLoader specifies how to load values, and CacheBuilder is used to set the desired features and actually build the cache.

 

这篇文章是个人Google Guava系列文章的延续，此次的主题是Guava Cache。Guava Cahce比HashMap和ConcurrentHashMap更灵活也更强大，可是又不像使用EHCache或者Memcached(所以也不像它们这么健壮，由于Guava Cache只在内存中操做)那么重量级。Guava Cache有你期待的接口，像是'get'，以及'invalide'。一个你不会发现的方法是'put', 由于Guava Cache是“自填充”的，在请求时没有出现的值会被抓取或者计算，而后储存起来。因此'get'方法永远不会返回null。公平地说，上边一句并非100%准确的。还有一个方法叫作‘asMap'，把cache中的条目做为一个线程安全的map暴露出来。使用'asMap'并不会执行任何自填充操做，所以，若是值不存在的话，调用'get'会返回null（这么作有啥意义呢？）尽管这篇blog是关于Guava Cache的，我也会花不少时间讲CacheLoader和CacheBuilder。CacheLoader用来指明怎么样加载值，而CacheBuilder用于设置你想要的特性，而且实际用来建立cache。

CacheLoader

CacheLoader is an abstract class that specifies how to calculate or load values, if not present. There are two ways to create an instance of a CacheLoader:

1. Extend the CacheLoader<K,V> class

2. Use the static factory method CacheLoader.from

CacheLoader是一个抽象类，用来指明怎么样计算或者加载值，若是没有发现的话(译注：若是没有在缓存里)。有两种方法来创建一个CacheLoader的实例:

1. 扩展CacheLoader<K,V>类
2. 使用静态工程方法CacheLoader.from

If you extend CacheLoader you need to override the V load(K key) method, instructing how to generate the value for a given key. Using the static CacheLoader.from method you build a CacheLoader either by supplying a Function or Supplier interface. When supplying a Function object, the Function is applied to the key to calculate or retrieve the results. Using a Supplier interface the value is obtained independent of the key.

若是你扩展CacheLoader，你须要覆盖V load(K key）方法，来讲明怎么样从一个指定的key生成value。使用静态的CacheLoader.from方法来构造CacheLoader时，你或者提供一个Function接口或者Supplier接口(译注：应该是说“实现了Function或者Supplier接口的对象")。当提供一个Function对象时，这个Function被用于根据key来计算或者获取结果。使用一个Supplier接口时，value的获取和key没有关系。

CacheBuilder

The CacheBuilder is used to construct cache instances. It uses the fluent style of building and gives you the option of setting the following properties on the cache:

• Cache Size limit (removals use a LRU algorithm)

• Wrapping keys in WeakReferences (Strong references used by default for keys)

• Wrapping values in either WeakReferences or SoftReferences (Strong references used by default)

• Time to expire entires after last access

• Time based expiration of entries after being written or updated

• Setting a RemovalListener that can recieve events once an entry is removed from the cache

• Concurrency Level of the cache (defaults to 4)

CacheBuilder被用来建立cache实例(译注：是指被cache的实例)。它使用fluent style(译注：就是.xx().xx().xx()的模式)来建立，使你能够指定cache的下列的属性： 

• Cache大小限制('移除'是使用LRU算法)
• 是否把keys包装成WeakReference(默认对于key是使用strong reference（译注：Java的弱引用和强引用）)
• 把值包装成WeakReference或者SoftReference（默认使用strong reference）
• 在最后访问一个条目(译注：entry，就是cache里的kv对)后多长时间过这个条目过时(expire)
• 在写入或者更新之后多长时间这个条目过时
• 设置一个RemovalListener，在一个条目过时之后，这个RemovalListener用来接收事件(译注：指'哪一个条目'过时了，这个事件)
• cache的并发度(默认为4)

The concurrency level option is used to partition the table internally such that updates can occur without contention. The ideal setting would be the maximum number of threads that could potentially access the cache at one time. Here is an example of a possible usage scenario for Guava Cache.

并发度选择用来在给内部的表作分区(译注：指cache实现时，在内部存储条目用的表)，使得更新能够无竞争的进行。最理想的设置是有可能同时访问这个cache的线程的数目。下面是一个可能使用Guava Cache的场景

public class PersonSearchServiceImpl implements SearchService<List<Person>> {

public PersonSearchServiceImpl(SampleLuceneSearcher luceneSearcher, SampleDBService dbService) {
        this.luceneSearcher = luceneSearcher;
        this.dbService = dbService;
        buildCache();
    }

    @Override
    public List<Person> search(String query) throws Exception {
        return cache.get(query);
    }

    private void buildCache() {
        cache = CacheBuilder.newBuilder().expireAfterWrite(10, TimeUnit.MINUTES)
                .maximumSize(1000)
                .build(new CacheLoader<String, List<Person>>() {
                    @Override
                    public List<Person> load(String queryKey) throws Exception {
                        List<String> ids = luceneSearcher.search(queryKey);
                        return dbService.getPersonsById(ids);
                    }
                });
    }
}

In this example, I am setting the cache entries to expire after 10 minutes of being written or updated in the cache, with a maximum amount of 1,000 entires. Note the usage of CacheLoader on line 15.

在这个例子中，我设置cache的条目会在写入或者更新10分钟后过时，最大数目数量是1000。注意第15行的CacheLoader的例子

RemovalListener

The RemovalListener will receive notification of an item being removed from the cache. These notifications could be from manual invalidations or from a automatic one due to time expiration or garbage collection. The RemovalListener<K,V> parameters can be set to listen for specific type. To receive notifications for any key or value set them to use Object. It should be noted here that a RemovalListener will receive a RemovalNotification<K,V> object that implements the Map.Entry interface. The key or value could be null if either has already been garbage collected. Also the key and value object will be strong references, regardless of the type of references used by the cache.

RemovalListener会在条目被从cache移除之后收到通知。这个通知可能源于手动地使条目失效，或者因为时间过时或者垃圾回收而自动地移除条目。RemovalListener<K,V>的类型参数能够被设置以监听指定的类型。若是要接收任何的kv的通知，把它们设成Object。须要说明的是，RemovalListener会收到一个RemovalNotification<K,V>类型的对象，这个对象实现了Map.Entry接口。若是key或者value被垃圾回收了，那么key和value可能会为null.并且key和value对象是是strong reference，无论在cache中的时候的reference的类型。

CacheStats

There is also a very useful class CacheStats that can be retrieved via a call to Cache.stats(). The CacheStats object can give insight into the effectiveness and performance of your cache by providing statistics such as:

有一个很是有用CacheStats类的对象，可使用Cache.status()来获取。CacheStats对象经过给你下面的统计，能够给出关于你的cache的效率和性能的洞察。

• hit count  命中总数

• miss count 未命中总数

• total load time 总的加载时间

• total requests 总的请求数目

CacheStats provides many other counts in addition to the ones listed above.

除了上边列出的统计结果，CacheStatus还提供了不少其它的值。

Conclusion

The Guava Cache presents some very compelling functionality. The decision to use a Guava Cache really comes down to the tradeoff between memory availability/usage versus increases in performance. I have added a unit test CacheTest demonstrating the usages discussed here. As alway comments and suggestions are welcomed. Thanks for your time.

GuavaCache提供了一些很是有竞争力的功能。使用Guava Cache源于对可用/使用的内存以及性能的折衷。我添加了一个单元测试来展现这里讨论的使用状况。像往常同样，欢迎评论和建议。谢谢你的时间。