Guava Source Code Structure: A Comprehensive Guide to Navigating google/guava

The Guava source code structure follows a modular Maven/Gradle layout with separate directories for the JRE flavor (guava/), Android flavor (android/), test utilities (guava-testlib/), and integration tests, all organized under com.google.common packages.

Understanding the Guava source code structure is essential for contributing to or extending Google's core Java libraries. The google/guava repository maintains a clean separation between platform-specific implementations while keeping package names consistent across flavors. This guide walks through the exact directory layout, key source files, and how to locate specific utilities within the codebase.

Repository Layout Overview

The root of the google/guava repository contains several distinct modules designed to support multi-platform deployment and comprehensive testing.

• guava/ — Contains the main JRE-flavor implementation with all core collections, concurrency utilities, hashing, graph APIs, and I/O helpers
• android/ — Houses the Android-compatible flavor that mirrors the same APIs but uses Android-optimized implementations
• guava-testlib/ — Provides helper classes and custom assertions used by Guava's internal test suite (e.g., EscaperAsserts)
• guava-bom/ — Maven Bill-of-Materials module that defines version alignment for all Guava artifacts
• integration-tests/ — Build scripts and example projects verifying Guava works with Gradle, Maven, and other ecosystems

Root-level build files include pom.xml and build.gradle descriptors that assemble these modules into distributable JARs, alongside standard documentation files like README.md and CONTRIBUTING.md.

Core Module Structure (guava/)

The primary implementation lives inside guava/src/ following the standard Maven directory layout. Source files are organized under guava/src/com/google/common/ with functional subpackages:

guava/
 └─ src/
     └─ com/google/common/
         ├─ collect/       ← immutable collections, multimaps, caches
         ├─ hash/          ← hashing functions, Bloom filters, primitives
         ├─ graph/         ← graph library (Graph, ValueGraph, Network)
         ├─ util/concurrent/ ← futures, listening executors, rate limiters
         ├─ io/            ← I/O helpers, ByteSource, CharSource
         ├─ math/          ← numeric utilities (LongMath, DoubleMath)
         └─ …               ← additional utility packages

Collections and Immutable Types

The collect package contains Guava's most widely used classes, particularly immutable collections. The file guava/src/com/google/common/collect/ImmutableList.java implements the persistent list interface that returns immutable instances via ImmutableList.of().

Other key files in this package include ImmutableMap.java, ImmutableSet.java, and Multimap implementations, all following the same factory method pattern.

Hashing Utilities

Located under guava/src/com/google/common/hash/, the hashing package provides cryptographic and non-cryptographic hash functions. The Hashing.java file serves as the primary factory class, offering static methods for Murmur3, SHA-1, SHA-256, and SipHash algorithms.

Graph API

The graph package (guava/src/com/google/common/graph/) implements Guava's graph theory library. Graph.java defines the core interface for nodes and edges, while Graphs.java provides static utility methods for graph creation, traversal, and analysis. This package supports both directed and undirected graphs, including mutable and immutable implementations.

Concurrency Utilities

Under guava/src/com/google/common/util/concurrent/, you'll find utilities for asynchronous programming. ListenableFuture implementations and Uninterruptibles.java (helpers for dealing with checked exceptions in concurrent code) reside here. The Futures class provides transformation and combination methods for chained asynchronous operations.

I/O and Math Utilities

The io package contains ByteSource, CharSource, and stream handling utilities in guava/src/com/google/common/io/. The math package offers LongMath and DoubleMath for overflow-aware arithmetic operations.

Android Flavor (android/)

Guava maintains a separate Android-compatible source tree under android/guava/src/ that mirrors the package structure of the main JRE module. Files like android/guava/src/com/google/common/collect/ImmutableList.java contain Android-optimized implementations that avoid Java 8+ language features incompatible with older Android versions.

Import statements remain identical between flavors (import com.google.common.collect.ImmutableList), allowing projects to switch dependencies without code changes.

Testing and Build Infrastructure

Test Utilities (guava-testlib/)

The guava-testlib module contains testing helpers used by Guava's own test suite. Classes like com.google.common.escape.testing.EscaperAsserts provide specialized assertions for escape/unescape logic. This module is published separately so external projects can use Guava's testing utilities.

Build Configuration

The root pom.xml aggregates all modules using Maven's multi-module structure. For Gradle users, build.gradle files in submodules handle compilation. The guava/src/module-info.java file defines the Java 9 module descriptor, explicitly exporting packages like com.google.common.collect and com.google.common.hash.

Practical Code Examples

Below are runnable examples using classes from the core guava/ module. These work identically in both JRE and Android flavors.

Creating an immutable list:

import com.google.common.collect.ImmutableList;

ImmutableList<String> colors = ImmutableList.of("red", "green", "blue");
System.out.println(colors);   // [red, green, blue]

Computing a SHA-256 hash:

import com.google.common.hash.Hashing;
import com.google.common.base.Charsets;

String data = "Guava rocks!";
String hash = Hashing.sha256()
                    .hashString(data, Charsets.UTF_8)
                    .toString();
System.out.println(hash);

Building a directed graph:

import com.google.common.graph.GraphBuilder;
import com.google.common.graph.MutableGraph;

MutableGraph<String> graph = GraphBuilder.directed().build();
graph.putEdge("A", "B");
graph.putEdge("B", "C");
System.out.println(graph.successors("A")); // [B]

Summary

• The guava/ directory contains the standard JRE implementation with packages under com.google.common for collections, hashing, graphs, and concurrency
• The android/ directory mirrors the same structure with Android-compatible implementations at android/guava/src/
• Key entry points include ImmutableList.java for collections, Hashing.java for cryptography, and Graph.java for graph processing
• guava-testlib/ provides testing utilities, while guava-bom/ manages dependency versions
• The repository uses Maven multi-module structure with pom.xml at the root and module descriptors in subdirectories

Frequently Asked Questions

Where is the ImmutableList source code in Guava?

The ImmutableList implementation resides at guava/src/com/google/common/collect/ImmutableList.java in the JRE flavor and android/guava/src/com/google/common/collect/ImmutableList.java for Android. Both files implement the same com.google.common.collect.ImmutableList public API using platform-appropriate internal mechanisms.

How does Guava organize its Android-specific code?

Guava maintains a parallel source tree under the android/ directory that duplicates the package structure of the main guava/ module. This allows the Android flavor to use optimized implementations (avoiding Java 8 streams, for example) while maintaining identical public APIs and import statements.

What is the purpose of the guava-testlib module?

The guava-testlib module contains testing utilities and custom assertions used by Guava's internal test suite, such as EscaperAsserts for testing character escaping logic. It is published as a separate artifact so developers writing extensions to Guava can utilize the same testing infrastructure.

How do I navigate to the graph API implementation files?

The graph API source files are located under guava/src/com/google/common/graph/. Start with Graph.java for the core interface definition, then examine Graphs.java for static utility methods. The Android equivalents exist at android/guava/src/com/google/common/graph/ with identical public interfaces.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}