The com.google.common.base Package
This section details some of the common utility classes in the com.google.common.base
Working with Soft, Weak, and Phantom References
If you used any of the SoftReference, WeakReference, or PhantomReference classes in the Java Collections Framework package java.lang.ref directly and wrote code to work with the ReferenceQueue, you will appreciate using the following Library classes:
These classes extend their respective Java Collections Framework classes to work with processing the ReferenceQueue and call back a convenient method finalizeReferent() defined in these classes. So if you have to do some cleanup operation when an object is claimed by the garbage collector (GC), just overriding the finalizeReferent() method will do the trick.
For example, suppose you are using the ImageChunks class to store image binary data in an object's memory and the GC cleaning up this object type is acceptable if the JVM runs low on memory. You can try extending the FinalizableSoftReference class (with, say, the SoftImageChunks class) and overriding the finalizeReferent method. This approach allows you to write the cleanup operation that should be called when the GC claims your object. The primary advantage of FinalizableSoftReference is you wouldn't need to deal with the ReferenceQueue directly.
Commons Collections doesn't have anything equivalent for working with the ReferenceQueue since it is not part of collections enhancement.
The Function interface has the method apply, which is used for transforming from one value to another (String to Integer, for example). Function is used in Maps and Comparators in the com.google.common.collect package for performing transformations. Here are a couple of notable Function uses:
- Maps.uniqueIndex(..) lets you apply a Function to perform a transform on the values of the backing Map instance. As a result, you get a Map instance that contains a mapping between the key and the transformed values.
- Comparators.fromFunction(Function<F,T> function) lets you create a Comparator that will apply the Function on both the items compared. Since the Comparator is created from within this method, the natural ordering of the object is used for comparison.
- The method forMap in the Functions utility class is handy for performing a lookup on a map to do a transformation. This method takes in a Map instance and returns a Function. When the method apply is called, the input is used as the key and the corresponding value will be looked up from the Map.
You can find Function being used in the classes Lists, Iterators, Iterator, and Functions.
The equivalent Commons Collections interface to Function is org.apache.commons.collections.Transformer. It is used in the following classes:
Transformer can be used along with Predicates as well. (Refer to TransformerUtils in the JavaDoc for more details.)
The Nullable annotation type is a cool thing. A general misunderstanding among business application developers is that their applications should not throw run-time exceptions. Nullable allows run-time exceptions to be an acceptable and neat way to write methods that bound the call to a contract. That is, if a method cannot accept null for an argument, a developer could use Nullable to perform a null check that raises an error in the first line of the method.
Commons Collections doesn't have an equivalent to Nullable.
Objects and Preconditions
Objects and Preconditions are utility classes that can be used even without the Java Collections Framework:
- The Objects class contains a series of utility methods to aid calling toString, hashCode, and equals methods on more than one object. It uses Arrays internally to delegate calls to the appropriate type.
- The Preconditions class is very useful for checking the value of the argument passed to a method and raising an error if appropriate.
Predicates can be used to model a scenario in which you want to iterate a collection (for example, when you want to go through a set of employee objects and filter them based on the attribute of salary). Using predicates will save you from having to write the same code repeatedly to perform if checks on the objects added in a list.
When compared to Commons Collections Functors, the Library predicates lack closures support. Predicates allows only filter and find operations, which can be run against a collection. For example, the following filter method in the com.google.common.collect.Iterators class allows filtering a collection based on the predicate passed:
static <T> Iterator<T> filter(Iterator<T> unfiltered, Predicate<? super T> predicate)
So the Library's predicate is ideal for developers intending to get the subset of a collection based on a filtering criterion.