An Overview of Guava:

Google Core Libraries

for Java
Kevin Bourrillion
Java Core Libraries Team
Google, Inc.
Presented at QCon November 8, 2012

Google Confidential and Proprietary

What's Guava?
Free open-source library for Java, GWT, Android.
14 packages chock full of utility classes and methods:
annotations
base
cache
collect
collect.testing
eventbus
hash

io
math
net
primitives
reflect
testing
util.concurrent

(These packages live under com.google.common.)

Google Confidential and Proprietary

Where does it come from?

We are the Java Core Libraries Team at Google.
What do we do?
Why do we release Guava?
It's a junk drawer then?
Why are you here talking about it?

Google Confidential and Proprietary

Actual User Quotes

On any new Java project, the first thing I do is add a
dependency to Guava; I just know Im going to need it.
Writing Java without Guava was like coding with one hand
tied behind my back.
Guava makes Java bearable again.
(We happen to think Java is more than bearable anyway,
but still: Guava makes writing Java programs easier.)

*paraphrased. But I swear people really said these things. Honest.

Google Confidential and Proprietary

About this presentation

Google Confidential and Proprietary

com.google.common.base

Google Confidential and Proprietary

String joining
Who here has ever written this utility?
public class StringUtil {
public static String join(
String separator, Iterable<String> pieces) {
// any of ~5 common implementations goes here
}
}

Google Confidential and Proprietary

String joining 2
But what about all the variations?
What to do with nulls?
skip over them? skip but leave separator? substitute
"null" or some other string? Just die?
Joining an Iterable, Iterator, varargs/array?
Return a String, or append to an Appendable?
We could be looking at 18 to 48 different methods here.
To cover all these bases we made Joiner:
return Joiner.on(", ")
.skipNulls()
.join("one", null, "two", "three");
Google Confidential and Proprietary

Joiner: what's going on here?

To get a Joiner:
static Joiner on(String)
static Joiner on(char)
To get an altered Joiner from that:
Joiner skipNulls()
Joiner useForNull(String)
To actually join stuff:
String join(Itera___)
String join(Object...)
Appendable appendTo(Appendable, Itera___)
Appendable appendTo(Object...)
Google Confidential and Proprietary

Splitter
Similar! But in the other direction.
return Splitter.on("|")
.omitEmptyStrings()
.split("|Harry||Ron|||Hermione
// returns "Harry", "Ron", "Hermione

||");
";

These classes use what we (tentatively) call the "Utility

Object pattern."

Google Confidential and Proprietary

CharMatcher (motivation)
Once upon a time we had a StringUtil class. Soon it was
overflowing with static methods:
allAscii, collapse, collapseControlChars,
collapseWhitespace, indexOfChars, lastIndexNotOf,
numSharedChars, removeChars, removeCrLf, replaceChars,
retainAllChars, strip, stripAndCollapse,
stripNonDigits...

Each dealt with two orthogonal concerns:

(a) what does it consider a matching character?
(b) what do we do with these matching characters?
One static method per combination would not scale.
Google Confidential and Proprietary

CharMatcher
Once again we use the Utility Object pattern.
A CharMatcher instance represents the set of "matching"
characters (part "a"). Methods on that instance provide the
operations (part "b").
// "_34-425==" becomes "34425"
String sanitized =
CharMatcher.anyOf("-=_")
.removeFrom(input);
Separates "configuration" from "processing".

Google Confidential and Proprietary

Getting a CharMatcher
Use a predefined constant (examples)
CharMatcher.WHITESPACE (Unicode)
CharMatcher.ASCII
CharMatcher.ANY
Use a factory method (examples)
CharMatcher.is('x')
CharMatcher.isNot('_')
CharMatcher.oneOf("aeiou")
CharMatcher.inRange('a', 'z')
.or(inRange('A', 'Z')).negate()
Or subclass CharMatcher, implement matches(char).
Google Confidential and Proprietary

Using your new CharMatcher

boolean matchesAllOf(CharSequence)
boolean matchesAnyOf(CharSequence)
boolean matchesNoneOf(CharSequence)
int indexIn(CharSequence, int)
int lastIndexIn(CharSequence, int)
int countIn(CharSequence)
String
String
String
String
String
String
String
String

removeFrom(CharSequence)
retainFrom(CharSequence)
trimFrom(CharSequence)
trimLeadingFrom(CharSequence)
trimTrailingFrom(CharSequence)
collapseFrom(CharSequence, char)
trimAndCollapseFrom(CharSequence, char)
replaceFrom(CharSequence, char)
Google Confidential and Proprietary

CharMatcher (last)
Putting it back together... to scrub an id number, you might
use
String seriesId =
CharMatcher.DIGIT.or(CharMatcher.is('-'))
.retainFrom(input);
In a loop? Move the definition above or to a constant.
static final CharMatcher ID_CHARS =
CharMatcher.DIGIT.or(CharMatcher.is('-'));
...
String id = SERIES_ID_CHARS.retainFrom(input);
Google Confidential and Proprietary

One problem with null

Consider looking up a phone number.
PhoneNumber phone = phoneBook.lookUp("Barack");
if (phone == null) {
// what does this mean?
}
No entry? Or entry exists but the phone number is unlisted?
Or consider a nickname field. null means no nickname, or
we just don't know?

Google Confidential and Proprietary

Optional<T>
Guava's Optional class lets you have a "second kind of
not-there" -- a "positive negative."
// Yes, has a nickname
Optional<String> nickname = Optional.of("Barry");
// Yes, we have no nickname
Optional<String> nickname = Optional.absent();
// Information missing/unknown
Optional<String> nickname = null;
// wat? Throws an exception.
Optional<String> nickname = Optional.of(null);
Google Confidential and Proprietary

Optional<T> basic usage

Optional<String> nickname = person.nickname();
if (nickname == null) return;
if (nickname.isPresent()) {
say("I hear people call you " + nickname.get());
} else {
// calling get() would throw an exception!
say("Your friends are not creative.");
}

Google Confidential and Proprietary

Optional<T> cooler usages

for (String actualNick : nickname.asSet()) {
doSomething(actualNick);
}
or
String firstName = person.firstName();
say("Hello, " + nickname.or(firstName));

Google Confidential and Proprietary

For null-unfriendly
collections
Many collections, including the JDK's Queue and
ConcurrentMap implementations, don't allow null elements.
Queue<Optional<Foo>> is a simple and natural solution!

Google Confidential and Proprietary

Optional<T>: the anti-null?

Some users use Optional even when they have only one
"kind of not-there". They use it as a null replacement.
Before:
Foo foo = someMethodThatMightReturnNull();
foo.whoops(); // I just forgot to check!
After:
Optional<Foo> foo = someMethod();
foo.get().whoops(); // same mistake!
Same mistake possible, but less likely to some degree.
Especially appropriate for public method return types.
Google Confidential and Proprietary

Stopwatch
For measuring elapsed time. Don't use System.
currentTimeMillis()!
Stopwatch watch = new Stopwatch().start();
doSomeOperation();
long micros = watch.elapsedTime(MICROSECONDS);
Stopwatch uses nanoTime() but exposes only relative
timings, a meaningless absolute value
an alternate time source can be substituted using
Ticker
has the same functions as a physical stopwatch
toString() gives human readable format
Google Confidential and Proprietary

Other things in base

... that we're not really going into ...

Preconditions
Objects.toStringHelper()
Objects.firstNonNull(T, T)
Throwables.propagate(Throwable)
CaseFormat
Strings.repeat(String, int)
Equivalence<T>
Function, Predicate, Supplier

Google Confidential and Proprietary

com.google.common.collect

Google Confidential and Proprietary

Collection Types (review)

Set:
doesn't guarantee order, has "unordered equality"
collapses duplicates
List:
guarantees order, has "ordered equality"
allows duplicates (multiple "occurrences")
Aren't these two orthogonal concerns?

Google Confidential and Proprietary

Basic Collection Types

Ordered?

Y
N
+------------+----------+
Y |
List
|
?
|
Dups?
+------------+----------+
N |
?
|
Set
|
+------------+----------+

Google Confidential and Proprietary

Basic Collection Types

Ordered?

Y
N
+------------+----------+
Y |
List
| Multiset |
Dups?
+------------+----------+
N |(UniqueList)|
Set
|
+------------+----------+

Google Confidential and Proprietary

Multiset<E>
Implements Collection<E>.
List:
[a, c, b, b, c, a, a, b]
Set:
[a, c, b]
Multiset: [a, a, a, c, c, b, b, b]
So a Multiset implementation only needs to store one
occurrence of each element, plus a count!
[a x 3, c x 2, b x 3]

Google Confidential and Proprietary

Counting without Multiset

Map<String, Integer> tags = new HashMap<>();
for (BlogPost post : getAllBlogPosts()) {
for (String tag : post.getTags()) {
int value = tags.containsKey(tag) ? tags.get(tag) : 0;
tags.put(tag, value + 1);
}
}
distinct tags: tags.keySet()
count for "java" tag:
tags.containsKey("java") ? tags.get("java") : 0;
total count: // uh oh...

Google Confidential and Proprietary

Counting with Multiset

Multiset<String> tags = HashMultiset.create();
for (BlogPost post : getAllBlogPosts()) {
tags.addAll(post.getTags());
}

distinct tags: tags.elementSet();

count for "java" tag: tags.count("java");
total count: tags.size();

Impls include ConcurrentHashMultiset, EnumMultiset...

Google Confidential and Proprietary

Next...
Map:
a1
b2
c3
d4

Google Confidential and Proprietary

Multimap<K, V>
Map:
a1
b2
c3
d4

Multimap:
a1
b2
c3
a4
Of course, we often also
want to view this as:
a 1, 4
b2
c3

Google Confidential and Proprietary

Multimap<K, V>
Like a Map (key-value pairs), but may have duplicate keys
The values related to a single key can be viewed as a
collection (set or list)
Consistent design to Map<K, V>
(analogy holds: Map : Set :: Multimap : Multiset)
Typically use instead of a Map<K, Collection<V>>
can view as that type using asMap()
Almost always want variable type to be either
ListMultimap or SetMultimap (and not Multimap)
Implementations include HashMultimap,
ArrayListMultimap...
Not going to say much more about these...
Google Confidential and Proprietary

Immutable Collections
ImmutableSet<Integer> luckyNumbers =
ImmutableSet.of(4, 8, 15, 16, 23, 42);
unlike Collections.unmodifiableXXX, they
perform a copy (not a view / wrapper)
type conveys immutability
offered for all collection types, including JDK ones
inherently thread-safe
deterministic, specified iteration order
reduced memory footprint
slightly improved CPU performance

Prefer immutability!
Google Confidential and Proprietary

FluentIterable<T>
You should all know Iterable<T>:
public interface Iterable<T> {
Iterator<T> iterator();
}
Guava can turn your iterables into fluent iterables:
FluentIterable<Thing> things =
FluentIterable.from(getThings());
... but why? ...

Google Confidential and Proprietary

FluentIterable
Because operations! (note: "lazy")
return FluentIterable.from(database.getClientList())
.filter(
new Predicate<Client>() {
public boolean apply(Client client) {
return client.activeInLastMonth();
}
})
.transform(Functions.toStringFunction())
.limit(10)
.toList();
Google Confidential and Proprietary

FluentIterable API
Chaining methods (return FluentIterable<T>)
filter(Predicate)
transform(Function)
skip(int), limit(int)
cycle()
Query methods (return boolean)
allMatch(Predicate), anyMatch(Predicate)
contains(Object)
isEmpty()
Extraction methods (return Optional<T>)
first(), last(), firstMatch(Predicate), get(int)
Conversion methods (return a copied Collection<T>)
toList(), toSet(), toSortedSet(), toArray()
Google Confidential and Proprietary

Functional Programming
Multiset<Integer> lengths = HashMultiset.create(
FluentIterable.from(strings)
.filter(new Predicate<String>() {
@Override public boolean apply(String s) {
return JAVA_UPPER_CASE.matchesAllOf(s);
}
})
.transform(new Function<String, Integer>() {
@Override public Integer apply(String s) {
return s.length();
}
}));

Google Confidential and Proprietary

w/o Functional Programming

Multiset<Integer> lengths = HashMultiset.create();
for (String s : strings) {
if (UPPER_CASE.matchesAllOf(s)) {
lengths.add(s.length());
}
}

Moral: just be careful out there.

Functional style can be great but it's not automatically the
better way to go.
JDK 8 will make functional programming in Java way better
(JSR-335).

Google Confidential and Proprietary

Comparators
Who loves implementing comparators by hand?
Comparator<String> byReverseOffsetThenName =
new Comparator<String>() {
public int compare(String tzId1, String tzId2) {
int offset1 = getOffsetForTzId(tzId1);
int offset2 = getOffsetForTzId(tzId2);
int result = offset2 - offset1; // careful!
return (result == 0)
? tzId1.compareTo(tzId2)
: result;
}
};

Google Confidential and Proprietary

ComparisonChain example
Here's one way to rewrite this:
Comparator<String> byReverseOffsetThenName =
new Comparator<String>() {
public int compare(String tzId1, String tzId2) {
return ComparisonChain.start()
.compare(getOffset(tzId2), getOffset(tzId1))
.compare(tzId1, tzId2)
.result();
}
};

Never allocates. Short-circuits (kind of).

Google Confidential and Proprietary

Ordering example
Here's another:
Ordering<String> byReverseOffsetThenName =
Ordering.natural()
.reverse()
.onResultOf(tzToOffsetFn())
.compound(Ordering.natural());
// okay, this should actually go above
Function<String, Integer> tzToOffsetFn =
new Function<String, Integer>() {
public Integer apply(String tzId) {
return getOffset(tzId);
}
};

Google Confidential and Proprietary

Ordering details 1/3

Implements Comparator, and adds delicious goodies!
(Could have been called FluentComparator.)
Common ways to get an Ordering to start with:
Ordering.natural()
new Ordering() { public int compare(...) {...} }
Ordering.from(preExistingComparator);
Ordering.explicit("alpha", "beta", "gamma", "delta");

... then ...

Google Confidential and Proprietary

Ordering details 2/3

... then you can use the chaining methods to get an altered
version of that Ordering:

reverse()
compound(Comparator)
onResultOf(Function)
nullsFirst()
nullsLast()

... now you've got your Comparator! But also ...

Google Confidential and Proprietary

Ordering details 3/3

Ordering has some handy operations:

immutableSortedCopy(Iterable)
isOrdered(Iterable)
isStrictlyOrdered(Iterable)
min(Iterable)
max(Iterable)
leastOf(int, Iterable)
greatestOf(int, Iterable)

Google Confidential and Proprietary

... which is better?

Ordering or ComparisonChain?
Answer: it depends, and that's why we have both.
Either is better than writing comparators by hand (why?).
When implementing a Comparator with ComparisonChain,
still extend Ordering anyway!

Google Confidential and Proprietary

Glimpses of other stuff

Google Confidential and Proprietary

Static utils for primitives

Google Confidential and Proprietary

Concurrency libraries
First learn the contents of java.util.concurrent.
Then check out our:
ListenableFuture<V>, ListeningExecutorService
CheckedFuture<V, X>
Service, ServiceManager
RateLimiter
ThreadFactoryBuilder
MoreExecutors
AtomicLongMap<K>
AtomicDouble
Uninterruptibles
...
Google Confidential and Proprietary

Caching
Guava has a powerful on-heap keyvalue cache.
LoadingCache<Key, Graph> cache = CacheBuilder.newBuilder()
.maximumSize(50000)
.expireAfterWrite(33, MINUTES)
.removalListener(notifyMe)
.build(
new CacheLoader<Key, Graph>() {
public Graph load(Key key) throws AnyException {
return createExpensiveGraph(key);
}
});
. . .
return cache.getUnchecked(myKey);

Google Confidential and Proprietary

Unified Hashing API

Object.hashCode() is good enough for in-memory hash
tables. What about more advanced hashing use cases
(fingerprinting, cryptographic, bloom filters...)?
HashCode hash = Hashing.murmur3_128().newHasher()
.putInt(person.getId())
.putString(person.getFirstName())
.putBytes(person.getSomeBytes())
.putObject(person.getPet(), petFunnel)
.hash(); // asLong(), asBytes(), toString()...
You can use murmur3 or JDK-provided algorithms (sha1,
crc32, etc.) with one consistent, user-friendly API.
Google Confidential and Proprietary

Coda

Google Confidential and Proprietary

How to contact us
Need help with a specific problem?
Post to Stack Overflow! Use the "guava" tag.
Report a defect, request an enhancement?

http://code.google.com/p/guava-libraries/issues/entry

Start an email discussion?

Send to [email protected]

Google Confidential and Proprietary

Requesting a new feature

It is hard to sell a new feature to Guava -- even for me!
Your best bet: a really well-documented feature request.
Try to search closed issues first, but don't worry (dups
happen).
1. What are you trying to do?
2. What's the best code you can write to accomplish that
using only today's Guava?
3. What would that same code look like if we added your
feature?
4. How do we know this problem comes up often enough
in real life to belong in Guava?
(Don't rush to code up a patch yet.)
Google Confidential and Proprietary

Q&A

Google Confidential and Proprietary

Some FAQs
... in case you don't ask enough questions!

Google Confidential and Proprietary

1. Y U NO Apache Commons?
Should you use Guava or Apache Commons?
We may be biased, so consult this question on Stack
Overflow:
http://tinyurl.com/guava-vs-apache

Google Confidential and Proprietary

2. Why is Guava monolithic?

Why don't we release separate "guava-collections", "guavaio", "guava-primitives", etc.?
For many usages, binary size isn't an issue.
When it is, a split like this won't actually help! Most users
use a little bit from each package.
Our favorite solution: ProGuard.
A single release is much simpler for us and you.

Google Confidential and Proprietary

3. What about GWT?

A significant subset is available for use with Google Web
Toolkit.
Every class marked @GwtCompatible... minus the
members marked @GwtIncompatible.
Note: We haven't spent much time optimizing for GWT.

Google Confidential and Proprietary

4. What about Android?

Everything should work on Android.
Guava 13.0 requires Gingerbread (has been out 2 years).
Targeting Froyo or earlier? There's a backport, guavajdk5.
Note: We haven't spent much time optimizing for Android.

Google Confidential and Proprietary

5. What is "google-collect"?
Heard of the Google Collections Library 1.0?
It's Guava 0.0, essentially. It's the old name of the project
before we had to rename it to Guava.
So please do not use google-collect.jar! Seek and destroy!
Classpath catastrophe will ensue otherwise!
(More history: if you see a funny version like "guava-r07", it
actually means Guava 7.0. Very sorry!)

Google Confidential and Proprietary

6. Where are fold, reduce, etc?

We're not trying to be the end-all be-all of functional
programming in Java!
We have Predicates and Functions, filter() and transform(),
because we had specific needs for them.
If you code in Java but love the FP ethos, then Java 8 will
be the first thing to really make you happy.

Google Confidential and Proprietary

Thanks!

Google Confidential and Proprietary