# Migration Guide: Moving from Guava's Deprecated APIs to Standard Java Alternatives

> Migrate from Guava's deprecated APIs to standard Java. Replace Preconditions, FluentFuture, and functional interfaces with JDK alternatives to modernize your code and remove dependencies.

- Repository: [Google/guava](https://github.com/google/guava)
- Tags: migration-guide
- Published: 2026-08-08

---

**Migrate from Guava's deprecated utilities to standard JDK alternatives by replacing `Preconditions` with `Objects.requireNonNull`, `FluentFuture` with `CompletableFuture`, Guava functional interfaces with `java.util.function`, and immutable collections with `List.of`/`Set.of` to eliminate external dependencies and modernize your codebase.**

This migration guide moving from Guava's deprecated APIs to standard Java alternatives targets the `google/guava` repository, where many core utilities have been superseded by Java 8+ features. As the JDK has evolved to include native `Optional` types, functional interfaces, and immutable collection factories, Guava has marked overlapping APIs as `@Deprecated` to encourage migration. Removing these legacy dependencies reduces your classpath complexity and aligns your code with modern Java standards.

## Preconditions and Argument Validation

In [[`guava/src/com/google/common/base/Preconditions.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/base/Preconditions.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/base/Preconditions.java), many overloads of `checkNotNull(T reference, Object errorMessage)` and `checkArgument(boolean expression, Object errorMessage)` are deprecated in favor of standard JDK methods available since Java 7. The `java.util.Objects` class provides equivalent null-checking with better performance characteristics.

Replace Guava's argument checking with `Objects.requireNonNull`:

```java
// Guava (deprecated overload)
import com.google.common.base.Preconditions;
String name = Preconditions.checkNotNull(user.getName(), "User name must be provided");

// Java 7+ standard alternative
import java.util.Objects;
String name = Objects.requireNonNull(user.getName(), "User name must be provided");

```

## Immutable Collections

The `ImmutableList.Builder.addAll(Iterable)` method and similar builders in [[`guava/src/com/google/common/collect/ImmutableList.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/collect/ImmutableList.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/collect/ImmutableList.java) are deprecated because Java 9 introduced factory methods that create immutable collections without extra dependencies. `List.of()`, `Set.of()`, and `Map.ofEntries()` provide compile-time type safety and optimized internal implementations.

Migrate collection construction:

```java
// Guava (deprecated builder pattern)
import com.google.common.collect.ImmutableList;
ImmutableList<String> list = ImmutableList.<String>builder()
    .addAll(existingCollection)
    .build();

// Java 9+ standard equivalent
import java.util.List;
List<String> list = List.of(existingCollection.toArray(new String[0]));

// For dynamic sizes or Java 8 compatibility
import java.util.Collections;
List<String> list = Collections.unmodifiableList(new ArrayList<>(existingCollection));

```

## Asynchronous Programming with Futures

`FluentFuture` in [[`guava/src/com/google/common/util/concurrent/FluentFuture.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/util/concurrent/FluentFuture.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/util/concurrent/FluentFuture.java) provided chained asynchronous operations, but Java 8's `CompletableFuture` offers equivalent functionality natively. Deprecated methods like `transformAsync(AsyncFunction, Executor)`, `catching(Class, Function, Executor)`, and `withTimeout(Duration, Executor)` have direct counterparts in the standard library.

Replace asynchronous chaining:

```java
// Guava (deprecated methods)
import com.google.common.util.concurrent.FluentFuture;
FluentFuture<String> future = FluentFuture.from(someAsyncCallable())
    .transformAsync(this::doSomethingAsync, executor)
    .catching(RuntimeException.class, ex -> "fallback", executor);

// Java 8+ standard equivalent
import java.util.concurrent.CompletableFuture;
CompletableFuture<String> future = CompletableFuture.supplyAsync(someAsyncCallable, executor)
    .thenComposeAsync(this::doSomethingAsync, executor)
    .exceptionally(ex -> "fallback");

```

For timeout operations, use `orTimeout(long, TimeUnit)` available since Java 9 instead of Guava's `withTimeout`.

## Functional Programming Interfaces

Guava's `Function`, `Predicate`, and `Supplier` interfaces in [[`guava/src/com/google/common/base/Function.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/base/Function.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/base/Function.java), [[`Predicate.java`](https://github.com/google/guava/blob/main/Predicate.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/base/Predicate.java), and [[`Supplier.java`](https://github.com/google/guava/blob/main/Supplier.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/base/Supplier.java) are deprecated in favor of `java.util.function` equivalents. These standard interfaces integrate seamlessly with the Stream API and lambda expressions introduced in Java 8.

Update functional interface imports:

```java
// Guava (deprecated)
import com.google.common.base.Function;
Function<String, Integer> lengthFn = new Function<String, Integer>() {
    public Integer apply(String s) { return s.length(); }
};

// Java 8+ standard
import java.util.function.Function;
Function<String, Integer> lengthFn = s -> s.length();

```

## Stream Processing Utilities

The `Streams` utility class in [[`guava/src/com/google/common/collect/Streams.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/collect/Streams.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/collect/Streams.java) provided methods like `mapConcat` and `zip` that are now redundant with the Java 8+ Stream API. Use `flatMap`, `Stream.concat`, or `IntStream.range` for equivalent functionality with better parallel stream support.

Replace stream operations:

```java
// Guava (deprecated)
import com.google.common.collect.Streams;
import java.util.Arrays;
List<String> result = Streams.mapConcat(list, s -> Arrays.asList(s.split(",")));

// Java 8+ standard
import java.util.stream.Collectors;
List<String> result = list.stream()
    .flatMap(s -> Arrays.stream(s.split(",")))
    .collect(Collectors.toList());

```

## Additional Deprecated Utilities

Several other Guava components have standard replacements:

- **Optional**: Replace [[`guava/src/com/google/common/base/Optional.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/base/Optional.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/base/Optional.java) with `java.util.Optional` (Java 8). Use `Optional.ofNullable(value)` instead of `Optional.fromNullable(value)`.

- **Range**: The static constructors in [[`guava/src/com/google/common/collect/Range.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/collect/Range.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/collect/Range.java) are deprecated; for temporal ranges, use `java.time.LocalDate` with `isAfter`/`isBefore` checks.

- **Joiner and Splitter**: Replace [[`guava/src/com/google/common/base/Joiner.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/base/Joiner.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/base/Joiner.java) and [[`Splitter.java`](https://github.com/google/guava/blob/main/Splitter.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/base/Splitter.java) with `String.join(delimiter, elements)` or `Collectors.joining()` for concatenation, and `String.split()` or `Pattern.compile()` for splitting.

- **Hashing**: Cryptographic hash functions in [[`guava/src/com/google/common/hash/Hashing.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/hash/Hashing.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/hash/Hashing.java) like `md5()` are deprecated for security; use `java.security.MessageDigest.getInstance("SHA-256")` instead.

- **Caching**: While many configuration methods in [[`guava/src/com/google/common/cache/CacheBuilder.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/cache/CacheBuilder.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/cache/CacheBuilder.java) are deprecated, consider migrating to **Caffeine** for a modern, high-performance cache, or use `ConcurrentHashMap` with `computeIfAbsent` for simple cases.

## Summary

- **Preconditions**: Replace `Preconditions.checkNotNull` with `Objects.requireNonNull` from [[`guava/src/com/google/common/base/Preconditions.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/base/Preconditions.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/base/Preconditions.java).
- **Collections**: Use `List.of()` and `Set.of()` (Java 9+) instead of `ImmutableList.Builder` from [[`guava/src/com/google/common/collect/ImmutableList.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/collect/ImmutableList.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/collect/ImmutableList.java).
- **Async**: Migrate `FluentFuture` chains to `CompletableFuture` methods from [[`guava/src/com/google/common/util/concurrent/FluentFuture.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/util/concurrent/FluentFuture.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/util/concurrent/FluentFuture.java).
- **Functions**: Update `Function`, `Predicate`, and `Supplier` imports to `java.util.function` equivalents from [`guava/src/com/google/common/base/`](https://github.com/google/guava/tree/master/guava/src/com/google/common/base).
- **Streams**: Replace `Streams.mapConcat` with `Stream.flatMap` from [[`guava/src/com/google/common/collect/Streams.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/collect/Streams.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/collect/Streams.java).
- **Security**: Use `MessageDigest` instead of deprecated hash utilities in [[`guava/src/com/google/common/hash/Hashing.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/hash/Hashing.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/hash/Hashing.java).

## Frequently Asked Questions

### How do I replace Guava's `Preconditions.checkNotNull` with standard Java?

Use `Objects.requireNonNull(T obj, String message)` available in `java.util.Objects` since Java 7. This method throws a `NullPointerException` with the specified message if the object is null, matching the behavior of the deprecated `checkNotNull` overloads in [[`guava/src/com/google/common/base/Preconditions.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/base/Preconditions.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/base/Preconditions.java).

### What is the Java standard equivalent for Guava's `FluentFuture`?

Replace `FluentFuture` chains with `java.util.concurrent.CompletableFuture` introduced in Java 8. Map `transformAsync` to `thenComposeAsync`, `catching` to `exceptionally`, and `withTimeout` to `orTimeout` (Java 9+), eliminating the need for [[`guava/src/com/google/common/util/concurrent/FluentFuture.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/util/concurrent/FluentFuture.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/util/concurrent/FluentFuture.java).

### Can I replace Guava's immutable collections with JDK methods?

Yes. Use `List.of()`, `Set.of()`, and `Map.ofEntries()` introduced in Java 9 to replace `ImmutableList.Builder` and similar classes from [[`guava/src/com/google/common/collect/ImmutableList.java`](https://github.com/google/guava/blob/main/guava/src/com/google/common/collect/ImmutableList.java)](https://github.com/google/guava/blob/master/guava/src/com/google/common/collect/ImmutableList.java). For collections larger than 10 elements or dynamic sizes, use `Collections.unmodifiableList(new ArrayList<>(list))`.

### Are all Guava functional interfaces deprecated?

Yes, `Function`, `Predicate`, and `Supplier` in [`guava/src/com/google/common/base/`](https://github.com/google/guava/tree/master/guava/src/com/google/common/base) are deprecated in favor of `java.util.function.Function`, `Predicate`, and `Supplier`. These standard interfaces work directly with the Stream API and lambda expressions, providing better interoperability than Guava's legacy types.