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)