0
# Proto Google Common Protos
1
2
Protocol Buffer classes for Google's common protos, providing Java implementations of standardized message types and service definitions used across Google APIs and services. This library enables type-safe access to core Google Cloud API structures, gRPC service definitions, and common data types.
3
4
## Package Information
5
6
- **Package Name**: proto-google-common-protos
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: `implementation 'com.google.api.grpc:proto-google-common-protos:2.57.0'`
10
11
## Core Imports
12
13
```java
14
import com.google.api.Http;
15
import com.google.api.HttpRule;
16
import com.google.rpc.Status;
17
import com.google.rpc.Code;
18
import com.google.type.Money;
19
import com.google.type.Date;
20
import com.google.longrunning.Operation;
21
```
22
23
## Basic Usage
24
25
```java
26
// Working with HTTP rules for REST API mapping
27
HttpRule rule = HttpRule.newBuilder()
28
.setGet("/api/v1/users/{user_id}")
29
.build();
30
31
// Creating error status responses
32
Status errorStatus = Status.newBuilder()
33
.setCode(Code.INVALID_ARGUMENT.getNumber())
34
.setMessage("Invalid user ID provided")
35
.build();
36
37
// Working with monetary values
38
Money price = Money.newBuilder()
39
.setCurrencyCode("USD")
40
.setUnits(29)
41
.setNanos(990000000) // $29.99
42
.build();
43
44
// Handling long-running operations
45
Operation operation = Operation.newBuilder()
46
.setName("operations/my-operation-id")
47
.setDone(false)
48
.build();
49
```
50
51
## Architecture
52
53
Proto Google Common Protos is structured around Protocol Buffer message definitions organized into functional packages:
54
55
- **Core API Infrastructure** (`com.google.api`): Service configuration, HTTP mappings, authentication, and API annotations
56
- **RPC Framework** (`com.google.rpc`, `com.google.rpc.context`): Standard error handling, status codes, and context information for gRPC services
57
- **Common Data Types** (`com.google.type`): Reusable types like Money, Date, Color, and geographic coordinates
58
- **Operations Management** (`com.google.longrunning`): Support for asynchronous operations with status tracking
59
- **Cloud Services** (`com.google.cloud`): Cloud platform audit logging and location services
60
- **Application Framework** (`com.google.apps`): Google Apps Card UI components and interactions
61
- **Geographic Types** (`com.google.geo.type`): Viewport and geographic data structures
62
- **Logging Types** (`com.google.logging.type`): HTTP request logging and severity levels
63
- **Shopping Types** (`com.google.shopping.type`): E-commerce related data types like Channel, Price, Weight
64
65
All classes follow Protocol Buffer Java conventions with message classes, OrBuilder interfaces, and Proto descriptor classes providing type-safe access to structured data.
66
67
## Capabilities
68
69
### API Infrastructure and Configuration
70
71
Core service configuration including HTTP mappings, authentication rules, quota management, and API annotations. Essential for defining gRPC services with REST endpoints.
72
73
```java { .api }
74
class Service {
75
String getName();
76
repeated Api getApisList();
77
Http getHttp();
78
Authentication getAuthentication();
79
Quota getQuota();
80
Documentation getDocumentation();
81
// Additional configuration methods
82
}
83
84
class Http {
85
repeated HttpRule getRulesList();
86
boolean getFullyDecodeReservedExpansion();
87
}
88
89
class HttpRule {
90
String getSelector();
91
String getGet();
92
String getPost();
93
String getPut();
94
String getDelete();
95
String getPatch();
96
HttpRule getCustom();
97
String getBody();
98
String getResponseBody();
99
repeated HttpRule getAdditionalBindingsList();
100
}
101
```
102
103
[API Infrastructure](./api-infrastructure.md)
104
105
### RPC Status and Error Handling
106
107
Standard error model and status codes for consistent error handling across gRPC services. Includes structured error details and context information.
108
109
```java { .api }
110
class Status {
111
int getCode();
112
String getMessage();
113
repeated Any getDetailsList();
114
115
static Status.Builder newBuilder();
116
Status.Builder toBuilder();
117
}
118
119
enum Code {
120
OK(0),
121
CANCELLED(1),
122
UNKNOWN(2),
123
INVALID_ARGUMENT(3),
124
DEADLINE_EXCEEDED(4),
125
NOT_FOUND(5),
126
ALREADY_EXISTS(6),
127
PERMISSION_DENIED(7),
128
RESOURCE_EXHAUSTED(8),
129
FAILED_PRECONDITION(9),
130
ABORTED(10),
131
OUT_OF_RANGE(11),
132
UNIMPLEMENTED(12),
133
INTERNAL(13),
134
UNAVAILABLE(14),
135
DATA_LOSS(15),
136
UNAUTHENTICATED(16);
137
}
138
```
139
140
[RPC Status and Error Handling](./rpc-status.md)
141
142
### Common Data Types
143
144
Standard data types for representing time, money, geographic coordinates, and other common concepts across Google APIs.
145
146
```java { .api }
147
class Money {
148
String getCurrencyCode();
149
long getUnits();
150
int getNanos();
151
152
static Money.Builder newBuilder();
153
}
154
155
class Date {
156
int getYear();
157
int getMonth();
158
int getDay();
159
160
static Date.Builder newBuilder();
161
}
162
163
class LatLng {
164
double getLatitude();
165
double getLongitude();
166
167
static LatLng.Builder newBuilder();
168
}
169
170
class TimeOfDay {
171
int getHours();
172
int getMinutes();
173
int getSeconds();
174
int getNanos();
175
}
176
```
177
178
[Common Data Types](./common-types.md)
179
180
### Long-Running Operations
181
182
Support for asynchronous operations that don't complete immediately, providing status tracking, cancellation, and result retrieval.
183
184
```java { .api }
185
class Operation {
186
String getName();
187
Any getMetadata();
188
boolean getDone();
189
Status getError();
190
Any getResponse();
191
192
static Operation.Builder newBuilder();
193
}
194
195
class GetOperationRequest {
196
String getName();
197
198
static GetOperationRequest.Builder newBuilder();
199
}
200
201
class ListOperationsRequest {
202
String getName();
203
String getFilter();
204
int getPageSize();
205
String getPageToken();
206
207
static ListOperationsRequest.Builder newBuilder();
208
}
209
```
210
211
[Long-Running Operations](./longrunning-operations.md)
212
213
### Cloud Platform Types
214
215
Cloud-specific types for audit logging, location services, and platform integration.
216
217
```java { .api }
218
class AuditLog {
219
String getServiceName();
220
String getMethodName();
221
String getResourceName();
222
AuthenticationInfo getAuthenticationInfo();
223
repeated AuthorizationInfo getAuthorizationInfoList();
224
RequestMetadata getRequestMetadata();
225
Struct getRequest();
226
Struct getResponse();
227
Status getStatus();
228
}
229
230
class Location {
231
String getName();
232
String getLocationId();
233
String getDisplayName();
234
Struct getLabels();
235
Any getMetadata();
236
}
237
```
238
239
[Cloud Platform Types](./cloud-platform.md)
240
241
### Google Apps Card Framework
242
243
UI components and interactions for building cards in Google Workspace applications.
244
245
```java { .api }
246
class Card {
247
repeated Section getSectionsList();
248
CardHeader getHeader();
249
String getName();
250
CardFixedFooter getFixedFooter();
251
DisplayStyle getDisplayStyle();
252
253
static Card.Builder newBuilder();
254
}
255
256
class Widget {
257
TextParagraph getTextParagraph();
258
Image getImage();
259
DecoratedText getDecoratedText();
260
ButtonList getButtonList();
261
TextInput getTextInput();
262
SelectionInput getSelectionInput();
263
DateTimePicker getDateTimePicker();
264
Divider getDivider();
265
Grid getGrid();
266
Columns getColumns();
267
}
268
```
269
270
[Google Apps Cards](./apps-cards.md)
271
272
## Protocol Buffer Patterns
273
274
### Message Construction
275
276
All message classes provide builder patterns for construction:
277
278
```java
279
// Create a new message
280
Status status = Status.newBuilder()
281
.setCode(Code.NOT_FOUND.getNumber())
282
.setMessage("Resource not found")
283
.build();
284
285
// Modify existing message
286
Status updatedStatus = status.toBuilder()
287
.setMessage("Updated message")
288
.build();
289
```
290
291
### OrBuilder Interfaces
292
293
All message classes implement corresponding OrBuilder interfaces for read access during construction:
294
295
```java
296
public interface StatusOrBuilder extends MessageOrBuilder {
297
int getCode();
298
String getMessage();
299
java.util.List<com.google.protobuf.Any> getDetailsList();
300
// Additional getter methods
301
}
302
```
303
304
### Serialization and Parsing
305
306
Standard Protocol Buffer serialization methods:
307
308
```java
309
// Serialize to bytes
310
byte[] bytes = status.toByteArray();
311
312
// Parse from bytes
313
Status parsed = Status.parseFrom(bytes);
314
315
// JSON serialization (requires JsonFormat)
316
String json = JsonFormat.printer().print(status);
317
Status fromJson = Status.newBuilder();
318
JsonFormat.parser().merge(json, fromJson);
319
```
320
321
## Error Handling
322
323
Common patterns for working with status and error information:
324
325
```java
326
// Check operation result
327
if (operation.getDone()) {
328
if (operation.hasError()) {
329
Status error = operation.getError();
330
Code code = Code.forNumber(error.getCode());
331
System.err.println("Operation failed: " + error.getMessage());
332
} else {
333
// Operation completed successfully
334
Any response = operation.getResponse();
335
// Process response
336
}
337
} else {
338
// Operation still in progress
339
System.out.println("Operation pending: " + operation.getName());
340
}
341
```
342
343
## Dependencies
344
345
This library requires:
346
347
- `com.google.protobuf:protobuf-java` - Core Protocol Buffers runtime
348
- Java 8 or higher
349
350
Commonly used with:
351
- gRPC Java libraries for service implementation
352
- Google Cloud client libraries for API integration
353
- Jackson or Gson for JSON serialization (optional)