Guava @Beta APIs: What They Are and When It's Safe to Use Them

Guava @Beta APIs are public classes, methods, and fields marked with the @Beta annotation that are explicitly excluded from the library's binary-compatibility guarantees and may undergo breaking changes or removal in future releases.

The Google Guava library uses the @Beta annotation to designate experimental features that are not yet frozen in the public API surface. When consuming google/guava, understanding these markings is essential, as they signal which components require version pinning and extra scrutiny during dependency upgrades.

What Are Guava @Beta APIs?

The @Beta annotation—defined in guava/src/com/google/common/annotations/Beta.java—serves as a contractual signal between the Guava team and downstream consumers. According to the source code's Javadoc, it "signifies that a public API (public class, method or field) is subject to incompatible changes, or even removal, in a future release."

Technical Implementation Details

In the Beta.java source file, the annotation is configured with specific retention and targeting policies:

• Retention Policy: @Retention(RetentionPolicy.CLASS) ensures the annotation is stored in the class file but is not visible at runtime. This design imposes zero runtime overhead while allowing static analysis tools to detect beta usage via bytecode inspection.
• Scope: The annotation supports ElementType.TYPE, ElementType.CONSTRUCTOR, ElementType.FIELD, and ElementType.METHOD, meaning entire classes (like RateLimiter) or individual methods (like BigDecimalMath.toBigInteger) can be independently marked.
• Propagation: Guava's documentation pipeline automatically propagates the @Beta marker to generated Javadoc pages, ensuring developers see the warning labels when browsing the API reference.

Because beta APIs are excluded from Guava's frozen public surface, they bypass the strict compatibility tests that run against release branches. This allows the Guava team to iterate quickly on new functionality without maintaining backward compatibility for experimental features.

When Is It Safe to Use @Beta APIs?

The safety of depending on @Beta APIs depends entirely on your project's role in the dependency chain and your capacity to manage breaking changes.

Application Code — Safe with caveats. Applications control their own classpath and Guava version, making it generally safe to use beta APIs. However, you must be prepared to refactor code when upgrading Guava versions, as beta methods may change signatures or disappear entirely.

Published Libraries — Discouraged. Libraries that appear on users' classpaths should avoid @Beta APIs unless absolutely essential. Downstream applications lose control over the Guava version when transitive dependencies conflict, forcing breaking upgrades without their consent.

Prototypes and Experiments — Ideal use case. Beta APIs are designed for rapid iteration. Using RateLimiter or BigDecimalMath in proof-of-concept code allows you to leverage cutting-edge utilities without waiting for API stabilization.

Production Systems with Strict SLAs — Avoid unless pinned. While many production systems successfully use long-standing beta APIs (such as RateLimiter, which has carried the annotation since Guava 13.0), you should only do so with a strictly pinned Guava version and a documented migration plan.

Practical Examples of @Beta APIs

Several widely-used Guava utilities remain in beta status. The following examples demonstrate typical usage while acknowledging the contractual risk.

Rate Limiter Example

The RateLimiter class in guava/src/com/google/common/util/concurrent/RateLimiter.java has been marked @Beta since Guava 13.0, yet remains widely adopted for throttling task execution:

import com.google.common.util.concurrent.RateLimiter;

public class ThrottledExecutor {
  // Creates a rate limiter with 5 permits per second
  private static final RateLimiter limiter = RateLimiter.create(5.0);

  public static void submit(Runnable task) {
    // acquire() blocks until a permit is available
    limiter.acquire();
    new Thread(task).start();
  }
}

BigDecimal Math Utilities

The BigDecimalMath class in guava/src/com/google/common/math/BigDecimalMath.java contains precision arithmetic helpers that carry the beta annotation:

import com.google.common.math.BigDecimalMath;
import java.math.BigDecimal;
import java.math.BigInteger;

public class SafeConversion {
  public static BigInteger toBigInt(String value) {
    // Limit integer part to 100 digits to avoid resource exhaustion
    BigDecimal bd = new BigDecimal(value);
    return BigDecimalMath.toBigInteger(bd, 100);
  }
}

Both examples rely on APIs that may evolve or relocate in future Guava releases, requiring vigilance when upgrading dependencies.

Summary

• @Beta annotation — Defined in Beta.java, it marks APIs excluded from binary-compatibility guarantees with RetentionPolicy.CLASS to avoid runtime overhead.
• Application safety — Safe for applications that control their own Guava version, provided you monitor release notes for breaking changes.
• Library risk — Generally inadvisable for published libraries due to transitive dependency conflicts outside your control.
• Version pinning — Essential when using beta APIs in production; lock your dependency version and plan for migration.
• Common examples — RateLimiter.create() and BigDecimalMath.toBigInteger() demonstrate real-world beta API usage that requires upgrade awareness.

Frequently Asked Questions

Will @Beta APIs be removed without warning?

According to the google/guava source code, beta APIs may undergo incompatible changes or removal in future releases. While the team typically provides migration paths for heavily-used beta features (like RateLimiter), there is no guarantee of a deprecation period. You should treat @Beta as a warning that the API contract is unstable.

Can I use @Beta APIs in a published library if I shade Guava?

Shading Guava—relocating its packages into your own namespace—mitigates some risk by isolating your specific Guava version from downstream consumers. However, it increases your artifact size and does not eliminate the need to maintain the beta API code yourself if Guava removes it in a future version. The Beta.java documentation explicitly discourages library usage regardless of shading.

How do I detect @Beta API usage in my codebase?

Since @Beta uses RetentionPolicy.CLASS, it is preserved in compiled bytecode but not available via runtime reflection. You can use static analysis tools like Error Prone or the Guava Beta Checker to scan your source code for @Beta annotations. These tools parse the class files or source to flag usage of com.google.common.annotations.Beta marked elements.

Do @Beta annotations affect runtime performance?

No. Because the annotation is defined with @Retention(RetentionPolicy.CLASS) in Beta.java, the JVM discards it after loading the class. It imposes no memory overhead or reflection cost at runtime, serving purely as a compile-time and documentation marker for API stability contracts.

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