0
# Google API Common
1

2
Google API Common provides foundational types and utilities for building robust Google API client applications in Java. It serves as a core library that enables developers to work with asynchronous operations, service lifecycle management, path templates, and resource name handling across the entire Google Cloud Java ecosystem.
3

4
## Package Information
5

6
- **Package Name**: api-common
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>com.google.api</groupId>
13
    <artifactId>api-common</artifactId>
14
    <version>2.50.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.google.api.core.ApiFuture;
22
import com.google.api.core.ApiFutures;
23
import com.google.api.core.SettableApiFuture;
24
import com.google.api.pathtemplate.PathTemplate;
25
import com.google.api.resourcenames.ResourceName;
26
```
27

28
## Basic Usage
29

30
```java
31
import com.google.api.core.ApiFuture;
32
import com.google.api.core.ApiFutures;
33
import com.google.api.core.SettableApiFuture;
34
import com.google.api.pathtemplate.PathTemplate;
35
import com.google.common.util.concurrent.MoreExecutors;
36

37
// Create and manipulate futures
38
SettableApiFuture<String> future = SettableApiFuture.create();
39
future.set("Hello World");
40

41
// Transform future results
42
ApiFuture<Integer> lengthFuture = ApiFutures.transform(
43
    future, 
44
    String::length, 
45
    MoreExecutors.directExecutor()
46
);
47

48
// Work with path templates
49
PathTemplate template = PathTemplate.create("projects/{project}/topics/{topic}");
50
String path = template.instantiate("my-project", "my-topic");
51
Map<String, String> vars = template.match("projects/my-project/topics/my-topic");
52
```
53

54
## Architecture
55

56
Google API Common is built around several key components:
57

58
- **Async Operations**: `ApiFuture` and `ApiFutures` utilities provide a consistent async programming model similar to Guava's `ListenableFuture`
59
- **Service Lifecycle**: `ApiService` interface and `AbstractApiService` base class for managing service startup/shutdown
60
- **Path Templates**: `PathTemplate` class for parsing and generating URLs with variable substitution
61
- **Resource Names**: `ResourceName` interface and implementations for type-safe resource identifier handling
62
- **API Stability**: Annotation system (`@BetaApi`, `@InternalApi`) for marking API stability levels
63
- **Clock Abstraction**: `ApiClock` interface for testable time operations
64

65
## Capabilities
66

67
### Asynchronous Operations
68

69
Core async programming utilities with futures, callbacks, and transformation operations. Essential for non-blocking API operations and result composition.
70

71
```java { .api }
72
interface ApiFuture<V> extends Future<V> {
73
    void addListener(Runnable listener, Executor executor);
74
}
75

76
class ApiFutures {
77
    static <V> void addCallback(
78
        ApiFuture<V> future, 
79
        ApiFutureCallback<? super V> callback, 
80
        Executor executor
81
    );
82
    static <V> ApiFuture<V> immediateFuture(V value);
83
    static <I, O> ApiFuture<O> transform(
84
        ApiFuture<? extends I> input, 
85
        ApiFunction<? super I, ? extends O> function, 
86
        Executor executor
87
    );
88
}
89

90
class SettableApiFuture<V> implements ApiFuture<V> {
91
    static <V> SettableApiFuture<V> create();
92
    boolean set(V value);
93
    boolean setException(Throwable throwable);
94
}
95
```
96

97
[Core API](./core-api.md)
98

99
### Path Template Processing
100

101
URL path template parsing, variable extraction, and path generation for Google API resource patterns. Critical for building REST API clients.
102

103
```java { .api }
104
class PathTemplate {
105
    static PathTemplate create(String template);
106
    boolean matches(String path);
107
    Map<String, String> match(String path);
108
    String instantiate(Map<String, String> values);
109
    Set<String> vars();
110
}
111

112
class TemplatedResourceName implements Map<String, String> {
113
    static TemplatedResourceName create(PathTemplate template, String path);
114
    PathTemplate template();
115
    TemplatedResourceName parentName();
116
}
117
```
118

119
[Path Templates](./path-template.md)
120

121
### Resource Name Handling
122

123
Type-safe resource identifier management with support for different resource name formats and factory patterns.
124

125
```java { .api }
126
interface ResourceName {
127
    Map<String, String> getFieldValuesMap();
128
    String getFieldValue(String fieldName);
129
}
130

131
class UntypedResourceName implements ResourceName {
132
    static UntypedResourceName parse(String formattedString);
133
    static boolean isParsableFrom(String formattedString);
134
}
135

136
interface ResourceNameFactory<T extends ResourceName> {
137
    T parse(String formattedString);
138
}
139
```
140

141
[Resource Names](./resource-names.md)
142

143
### Service Lifecycle Management
144

145
Managed service lifecycle with startup, shutdown, and state monitoring capabilities for long-running services.
146

147
```java { .api }
148
interface ApiService {
149
    ApiService startAsync();
150
    ApiService stopAsync();
151
    void awaitRunning();
152
    boolean isRunning();
153
    State state();
154
    void addListener(Listener listener, Executor executor);
155
    
156
    enum State {
157
        NEW, STARTING, RUNNING, STOPPING, TERMINATED, FAILED
158
    }
159
}
160

161
abstract class AbstractApiService implements ApiService {
162
    protected abstract void doStart();
163
    protected abstract void doStop();
164
    protected final void notifyStarted();
165
    protected final void notifyStopped();
166
}
167
```
168

169
[Core API](./core-api.md)
170

171
## Types
172

173
### Core Functional Interfaces
174

175
```java { .api }
176
@FunctionalInterface
177
interface ApiFunction<F, T> {
178
    T apply(F input);
179
}
180

181
@FunctionalInterface  
182
interface ApiAsyncFunction<I, O> {
183
    ApiFuture<O> apply(I input) throws Exception;
184
}
185

186
interface ApiFutureCallback<V> {
187
    void onFailure(Throwable t);
188
    void onSuccess(V result);
189
}
190
```
191

192
### Clock Abstractions
193

194
```java { .api }
195
interface ApiClock {
196
    long nanoTime();
197
    long millisTime();
198
}
199

200
class NanoClock implements ApiClock {
201
    static ApiClock getDefaultClock();
202
}
203

204
class CurrentMillisClock implements ApiClock {
205
    static ApiClock getDefaultClock();
206
}
207
```
208

209
### API Stability Annotations
210

211
```java { .api }
212
@Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE, ANNOTATION_TYPE})
213
@interface BetaApi {
214
    String value() default "";
215
}
216

217
@BetaApi
218
@Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE, ANNOTATION_TYPE})  
219
@interface InternalApi {
220
    String value() default "";
221
}
222

223
@BetaApi
224
@Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE, ANNOTATION_TYPE})
225
@interface ObsoleteApi {
226
    String value();
227
}
228

229
@BetaApi
230
@Target({TYPE, METHOD, CONSTRUCTOR, FIELD, PACKAGE, ANNOTATION_TYPE})
231
@interface InternalExtensionOnly {
232
    String value() default "";
233
}
234
```