0
# Guava FailureAccess
1
2
Guava FailureAccess provides internal optimization utilities for accessing failure causes in Future implementations without the overhead of full exception handling. This micro-optimization library enables efficient failure cause retrieval for completed futures, primarily used internally by Guava and other Google libraries.
3
4
## Package Information
5
6
- **Package Name**: failureaccess
7
- **Package Type**: maven
8
- **Group ID**: com.google.guava
9
- **Language**: Java
10
- **Installation**: Add to your `pom.xml`:
11
12
```xml
13
<dependency>
14
<groupId>com.google.guava</groupId>
15
<artifactId>failureaccess</artifactId>
16
<version>1.0.3</version>
17
</dependency>
18
```
19
20
Or to your `build.gradle`:
21
22
```gradle
23
implementation 'com.google.guava:failureaccess:1.0.3'
24
```
25
26
## Core Imports
27
28
```java
29
import com.google.common.util.concurrent.internal.InternalFutureFailureAccess;
30
import com.google.common.util.concurrent.internal.InternalFutures;
31
```
32
33
## Basic Usage
34
35
```java
36
import com.google.common.util.concurrent.internal.InternalFutureFailureAccess;
37
import com.google.common.util.concurrent.internal.InternalFutures;
38
39
// Extend InternalFutureFailureAccess in your Future implementation
40
public class CustomFuture<V> extends InternalFutureFailureAccess {
41
private volatile Throwable failure;
42
43
@Override
44
protected Throwable tryInternalFastPathGetFailure() {
45
return failure; // Return failure cause if available, null otherwise
46
}
47
48
// Your Future implementation...
49
}
50
51
// Use InternalFutures to access failure cause from outside the class
52
CustomFuture<String> future = new CustomFuture<>();
53
Throwable failureCause = InternalFutures.tryInternalFastPathGetFailure(future);
54
55
if (failureCause != null) {
56
// Future has failed - handle the failure
57
System.out.println("Future failed with: " + failureCause.getMessage());
58
}
59
```
60
61
## Architecture
62
63
The library follows a simple optimization pattern:
64
65
- **InternalFutureFailureAccess**: Abstract base class that Future implementations extend to provide optional failure access
66
- **InternalFutures**: Static utility class that provides public access to the protected failure retrieval method
67
- **Contract Enforcement**: Strict requirements ensure that failure access only works for properly failed futures (not cancelled ones)
68
69
## Capabilities
70
71
### Future Failure Access
72
73
The core capability for accessing failure causes from Future implementations without exception overhead.
74
75
```java { .api }
76
/**
77
* Abstract base class for futures that can optionally provide access to failure causes.
78
* Used for micro-optimization of Future utilities.
79
*/
80
public abstract class InternalFutureFailureAccess {
81
/**
82
* Protected constructor for use by subclasses.
83
* Prevents direct instantiation - must be extended.
84
*/
85
protected InternalFutureFailureAccess();
86
87
/**
88
* Returns the failure cause if this Future has failed, null otherwise.
89
* Protected method - use InternalFutures.tryInternalFastPathGetFailure() to access.
90
*
91
* Contract: If this returns non-null, then:
92
* - isDone() must return true
93
* - isCancelled() must return false
94
* - get() must throw ExecutionException with this as the cause
95
*/
96
protected abstract Throwable tryInternalFastPathGetFailure();
97
}
98
```
99
100
### Static Utility Access
101
102
Public interface for accessing the failure cause from InternalFutureFailureAccess instances.
103
104
```java { .api }
105
/**
106
* Static utilities for InternalFutureFailureAccess.
107
* Most users will never need to use this class.
108
* Follows utility class pattern with private constructor.
109
*/
110
public final class InternalFutures {
111
/**
112
* Returns the failure cause if the given Future has failed, null otherwise.
113
* This is the public way to access the protected tryInternalFastPathGetFailure method.
114
*
115
* @param future The InternalFutureFailureAccess instance to query
116
* @return The failure cause if available, null otherwise
117
*/
118
public static Throwable tryInternalFastPathGetFailure(InternalFutureFailureAccess future);
119
120
/** Private constructor prevents instantiation - this is a utility class. */
121
private InternalFutures();
122
}
123
```
124
125
## Usage Contract
126
127
The failure access mechanism has a strict contract:
128
129
**If `tryInternalFastPathGetFailure()` returns non-null:**
130
- `isDone()` must return `true` on the Future
131
- `isCancelled()` must return `false` on the Future
132
- `get()` must not block and must throw `ExecutionException` with the returned `Throwable` as its cause
133
134
**Failure definition:**
135
- "Failure" means completed with an exception
136
- Does NOT include cancelled futures
137
- Method may return `null` even for failed futures (optimization is optional)
138
139
## Error Handling
140
141
This library does not throw exceptions during normal operation. The `tryInternalFastPathGetFailure()` method returns `null` when no failure information is available, requiring callers to handle this case appropriately.
142
143
## Compatibility
144
145
- **GWT Compatible**: All classes work in Google Web Toolkit environments
146
- **Java Module System**: Provides module definition `com.google.common.util.concurrent.internal` for JPMS compatibility
147
- **Multi-Release JAR**: Includes Java 9+ module support while maintaining Java 8 compatibility
148
- **Android Compatible**: Designed to work on Android without pulling in full Guava dependency
149
150
### Module Information
151
152
For projects using the Java Platform Module System (JPMS), the library provides:
153
154
```java
155
module com.google.common.util.concurrent.internal {
156
exports com.google.common.util.concurrent.internal;
157
}
158
```
159
160
This allows proper module dependency declaration in your `module-info.java`:
161
162
```java
163
requires com.google.common.util.concurrent.internal;
164
```