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
```