0
# Client Services
1

2
Abstract base classes and request handling framework for building type-safe Google API clients with automatic JSON parsing and error handling.
3

4
## Core Imports
5

6
```java
7
import com.google.api.client.googleapis.services.AbstractGoogleClient;
8
import com.google.api.client.googleapis.services.json.AbstractGoogleJsonClient;
9
import com.google.api.client.googleapis.services.AbstractGoogleClientRequest;
10
import com.google.api.client.googleapis.services.json.AbstractGoogleJsonClientRequest;
11
import com.google.api.client.googleapis.services.GoogleClientRequestInitializer;
12
import com.google.api.client.googleapis.services.CommonGoogleClientRequestInitializer;
13
```
14

15
## Abstract Client Classes
16

17
### AbstractGoogleClient
18

19
Thread-safe abstract base class for Google API clients.
20

21
```java { .api }
22
public abstract class AbstractGoogleClient {
23
    protected AbstractGoogleClient(Builder builder);
24
    
25
    public final HttpRequestFactory getRequestFactory();
26
    public final GoogleClientRequestInitializer getGoogleClientRequestInitializer();
27
    public final String getRootUrl();
28
    public final String getServicePath();
29
    public final String getBaseUrl();
30
    public final String getApplicationName();
31
    public final ObjectParser getObjectParser();
32
    public final boolean getSuppressPatternChecks();
33
    public final boolean getSuppressRequiredParameterChecks();
34
    public final String getUniverseDomain();
35
    
36
    public void validateUniverseDomain() throws IOException;
37
    public final BatchRequest batch();
38
    public final BatchRequest batch(HttpRequestInitializer httpRequestInitializer);
39
    
40
    protected void initialize(AbstractGoogleClientRequest<?> googleClientRequest) throws IOException;
41
    
42
    public static abstract class Builder {
43
        protected Builder(HttpTransport transport, String rootUrl, String servicePath, 
44
            ObjectParser objectParser, HttpRequestInitializer httpRequestInitializer);
45
        
46
        public abstract AbstractGoogleClient build();
47
        
48
        public final HttpTransport getTransport();
49
        public final String getRootUrl();
50
        public Builder setRootUrl(String rootUrl);
51
        
52
        public final String getServicePath();
53
        public Builder setServicePath(String servicePath);
54
        
55
        public final GoogleClientRequestInitializer getGoogleClientRequestInitializer();
56
        public Builder setGoogleClientRequestInitializer(GoogleClientRequestInitializer googleClientRequestInitializer);
57
        
58
        public final HttpRequestInitializer getHttpRequestInitializer();
59
        public Builder setHttpRequestInitializer(HttpRequestInitializer httpRequestInitializer);
60
        
61
        public final String getApplicationName();
62
        public Builder setApplicationName(String applicationName);
63
        
64
        public final ObjectParser getObjectParser();
65
        
66
        public final boolean getSuppressPatternChecks();
67
        public Builder setSuppressPatternChecks(boolean suppressPatternChecks);
68
        
69
        public final boolean getSuppressRequiredParameterChecks();
70
        public Builder setSuppressRequiredParameterChecks(boolean suppressRequiredParameterChecks);
71
        
72
        public final boolean getSuppressAllChecks();
73
        public Builder setSuppressAllChecks(boolean suppressAllChecks);
74
        
75
        public Builder setBatchPath(String batchPath);
76
        
77
        public final String getUniverseDomain();
78
        public Builder setUniverseDomain(String universeDomain);
79
    }
80
}
81
```
82

83
### AbstractGoogleJsonClient
84

85
Thread-safe Google JSON client extending AbstractGoogleClient.
86

87
```java { .api }
88
public abstract class AbstractGoogleJsonClient extends AbstractGoogleClient {
89
    protected AbstractGoogleJsonClient(Builder builder);
90
    
91
    public JsonObjectParser getObjectParser();
92
    public final JsonFactory getJsonFactory();
93
    
94
    public static abstract class Builder extends AbstractGoogleClient.Builder {
95
        protected Builder(HttpTransport transport, JsonFactory jsonFactory, String rootUrl, 
96
            String servicePath, HttpRequestInitializer httpRequestInitializer, boolean legacyDataWrapper);
97
        
98
        public abstract AbstractGoogleJsonClient build();
99
        
100
        public final JsonObjectParser getObjectParser();
101
        public final JsonFactory getJsonFactory();
102
        
103
        public Builder setRootUrl(String rootUrl);
104
        public Builder setServicePath(String servicePath);
105
        public Builder setGoogleClientRequestInitializer(GoogleClientRequestInitializer googleClientRequestInitializer);
106
        public Builder setHttpRequestInitializer(HttpRequestInitializer httpRequestInitializer);
107
        public Builder setApplicationName(String applicationName);
108
        public Builder setSuppressPatternChecks(boolean suppressPatternChecks);
109
        public Builder setSuppressRequiredParameterChecks(boolean suppressRequiredParameterChecks);
110
        public Builder setSuppressAllChecks(boolean suppressAllChecks);
111
        public Builder setBatchPath(String batchPath);
112
        public Builder setUniverseDomain(String universeDomain);
113
    }
114
}
115
```
116

117
**Usage Example:**
118

119
```java
120
import com.google.api.client.googleapis.services.json.AbstractGoogleJsonClient;
121
import com.google.api.client.json.gson.GsonFactory;
122

123
// Example custom client extending AbstractGoogleJsonClient
124
public class MyGoogleApiClient extends AbstractGoogleJsonClient {
125
    
126
    public MyGoogleApiClient(Builder builder) {
127
        super(builder);
128
    }
129
    
130
    public static final class Builder extends AbstractGoogleJsonClient.Builder {
131
        public Builder(HttpTransport transport, JsonFactory jsonFactory, 
132
                      HttpRequestInitializer httpRequestInitializer) {
133
            super(transport, jsonFactory, 
134
                  "https://myapi.googleapis.com/", 
135
                  "myapi/v1/", 
136
                  httpRequestInitializer, 
137
                  false);
138
        }
139
        
140
        public MyGoogleApiClient build() {
141
            return new MyGoogleApiClient(this);
142
        }
143
    }
144
}
145

146
// Usage
147
HttpTransport transport = GoogleNetHttpTransport.newTrustedTransport();
148
JsonFactory jsonFactory = GsonFactory.getDefaultInstance();
149
HttpRequestInitializer credential = // ... your credential
150

151
MyGoogleApiClient client = new MyGoogleApiClient.Builder(transport, jsonFactory, credential)
152
    .setApplicationName("My Application")
153
    .build();
154
```
155

156
## Request Classes
157

158
### AbstractGoogleClientRequest
159

160
Abstract base class for Google API requests.
161

162
```java { .api }
163
public abstract class AbstractGoogleClientRequest<T> extends GenericUrl {
164
    protected AbstractGoogleClientRequest(AbstractGoogleClient abstractGoogleClient, 
165
        String requestMethod, String uriTemplate, Object content, Class<T> responseClass);
166
    
167
    public final AbstractGoogleClient getAbstractGoogleClient();
168
    public final String getRequestMethod();
169
    public final String getUriTemplate();
170
    public final Object getHttpContent();
171
    public final Class<T> getResponseClass();
172
    
173
    public final String getMediaUploadType();
174
    protected AbstractGoogleClientRequest<T> setMediaUploadType(String mediaUploadType);
175
    
176
    public HttpHeaders getRequestHeaders();
177
    public AbstractGoogleClientRequest<T> setRequestHeaders(HttpHeaders headers);
178
    
179
    public HttpHeaders getLastResponseHeaders();
180
    public int getLastStatusCode();
181
    public String getLastStatusMessage();
182
    
183
    public final boolean getDisableGZipContent();
184
    public AbstractGoogleClientRequest<T> setDisableGZipContent(boolean disableGZipContent);
185
    
186
    public T execute() throws IOException;
187
    public HttpResponse executeUnparsed() throws IOException;
188
    public void executeAndDownloadTo(OutputStream outputStream) throws IOException;
189
    public InputStream executeAsInputStream() throws IOException;
190
    
191
    protected void newExceptionOnError(HttpResponse response) throws IOException;
192
    
193
    public AbstractGoogleClientRequest<T> setAlt(String alt);
194
    public AbstractGoogleClientRequest<T> setFields(String fields);
195
    public AbstractGoogleClientRequest<T> setKey(String key);
196
    public AbstractGoogleClientRequest<T> setOauthToken(String oauthToken);
197
    public AbstractGoogleClientRequest<T> setPrettyPrint(Boolean prettyPrint);
198
    public AbstractGoogleClientRequest<T> setQuotaUser(String quotaUser);
199
    public AbstractGoogleClientRequest<T> setUserIp(String userIp);
200
}
201
```
202

203
### AbstractGoogleJsonClientRequest
204

205
JSON-specific implementation of AbstractGoogleClientRequest.
206

207
```java { .api }
208
public abstract class AbstractGoogleJsonClientRequest<T> extends AbstractGoogleClientRequest<T> {
209
    protected AbstractGoogleJsonClientRequest(AbstractGoogleJsonClient abstractGoogleJsonClient,
210
        String requestMethod, String uriTemplate, Object content, Class<T> responseClass);
211
    
212
    public final AbstractGoogleJsonClient getAbstractGoogleJsonClient();
213
    
214
    public AbstractGoogleJsonClientRequest<T> setAlt(String alt);
215
    public AbstractGoogleJsonClientRequest<T> setFields(String fields);
216
    public AbstractGoogleJsonClientRequest<T> setKey(String key);
217
    public AbstractGoogleJsonClientRequest<T> setOauthToken(String oauthToken);
218
    public AbstractGoogleJsonClientRequest<T> setPrettyPrint(Boolean prettyPrint);
219
    public AbstractGoogleJsonClientRequest<T> setQuotaUser(String quotaUser);
220
    public AbstractGoogleJsonClientRequest<T> setUserIp(String userIp);
221
    
222
    public AbstractGoogleJsonClientRequest<T> setRequestHeaders(HttpHeaders headers);
223
    public AbstractGoogleJsonClientRequest<T> setDisableGZipContent(boolean disableGZipContent);
224
}
225
```
226

227
**Usage Example:**
228

229
```java
230
// Example custom request class
231
public class MyApiRequest extends AbstractGoogleJsonClientRequest<MyResponse> {
232
    
233
    protected MyApiRequest(MyGoogleApiClient client, String httpMethod, 
234
                          String uriTemplate, Object content) {
235
        super(client, httpMethod, uriTemplate, content, MyResponse.class);
236
    }
237
    
238
    // Custom parameter methods
239
    public MyApiRequest setCustomParam(String value) {
240
        return (MyApiRequest) set("customParam", value);
241
    }
242
}
243

244
// Usage
245
MyApiRequest request = new MyApiRequest(client, "GET", "items/{itemId}", null)
246
    .setCustomParam("value")
247
    .setFields("id,name,description");
248

249
MyResponse response = request.execute();
250
```
251

252
## Request Initializers
253

254
### GoogleClientRequestInitializer
255

256
Interface for initializing Google API client requests.
257

258
```java { .api }
259
public interface GoogleClientRequestInitializer {
260
    void initialize(AbstractGoogleClientRequest<?> request) throws IOException;
261
}
262
```
263

264
### CommonGoogleClientRequestInitializer
265

266
Common implementation of GoogleClientRequestInitializer.
267

268
```java { .api }
269
public class CommonGoogleClientRequestInitializer implements GoogleClientRequestInitializer {
270
    public CommonGoogleClientRequestInitializer();
271
    public CommonGoogleClientRequestInitializer(String key);
272
    public CommonGoogleClientRequestInitializer(String key, String userIp);
273
    
274
    public void initialize(AbstractGoogleClientRequest<?> request);
275
    
276
    public final String getKey();
277
    public final String getUserIp();
278
}
279
```
280

281
### CommonGoogleJsonClientRequestInitializer
282

283
JSON-specific request initializer.
284

285
```java { .api }
286
public class CommonGoogleJsonClientRequestInitializer extends CommonGoogleClientRequestInitializer {
287
    public CommonGoogleJsonClientRequestInitializer();
288
    public CommonGoogleJsonClientRequestInitializer(String key);
289
    public CommonGoogleJsonClientRequestInitializer(String key, String userIp);
290
}
291
```
292

293
**Usage Example:**
294

295
```java
296
import com.google.api.client.googleapis.services.CommonGoogleClientRequestInitializer;
297

298
// Create request initializer with API key
299
GoogleClientRequestInitializer requestInitializer = 
300
    new CommonGoogleClientRequestInitializer("your-api-key");
301

302
// Use with client builder
303
MyGoogleApiClient client = new MyGoogleApiClient.Builder(transport, jsonFactory, credential)
304
    .setApplicationName("My Application")
305
    .setGoogleClientRequestInitializer(requestInitializer)
306
    .build();
307

308
// Custom request initializer
309
GoogleClientRequestInitializer customInitializer = new GoogleClientRequestInitializer() {
310
    @Override
311
    public void initialize(AbstractGoogleClientRequest<?> request) throws IOException {
312
        request.setRequestHeaders(new HttpHeaders().set("Custom-Header", "value"));
313
    }
314
};
315
```
316

317
## Types
318

319
### HttpTransport
320

321
HTTP transport interface for network communication.
322

323
### JsonFactory
324

325
JSON factory for parsing and serializing JSON data.
326

327
### HttpRequestInitializer
328

329
Interface for initializing HTTP requests.
330

331
### HttpRequestFactory
332

333
Factory for creating HTTP requests.
334

335
### ObjectParser
336

337
Interface for parsing response objects.
338

339
### JsonObjectParser
340

341
JSON-specific object parser implementation.
342

343
### HttpHeaders
344

345
HTTP headers container.
346

347
### GenericUrl
348

349
Generic URL builder and container.
350

351
### OutputStream
352

353
Java output stream for downloading data.
354

355
### InputStream
356

357
Java input stream for streaming data.
358

359
### IOException
360

361
Exception for I/O operations.
362

363
### Class<T>
364

365
Java class type parameter for response parsing.