0
# protobuf-java-util
1
2
A comprehensive set of utilities for working with Protocol Buffers in Java applications. The library provides essential functionality for JSON format conversion, field mask operations, time-based utilities, structured data manipulation, and proto file operations. All utilities are designed for maximum reusability across protobuf-based systems including web APIs, data processing pipelines, and distributed systems.
3
4
## Package Information
5
6
- **Package Name**: protobuf-java-util
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to pom.xml:
10
```xml
11
<dependency>
12
<groupId>com.google.protobuf</groupId>
13
<artifactId>protobuf-java-util</artifactId>
14
<version>4.31.1</version>
15
</dependency>
16
```
17
18
## Core Imports
19
20
```java
21
import com.google.protobuf.util.JsonFormat;
22
import com.google.protobuf.util.FieldMaskUtil;
23
import com.google.protobuf.util.Timestamps;
24
import com.google.protobuf.util.Durations;
25
import com.google.protobuf.util.Structs;
26
import com.google.protobuf.util.Values;
27
import com.google.protobuf.util.ProtoFileUtil;
28
```
29
30
## Basic Usage
31
32
```java
33
import com.google.protobuf.util.JsonFormat;
34
import com.google.protobuf.util.Timestamps;
35
import com.google.protobuf.util.Durations;
36
import com.google.protobuf.Timestamp;
37
import com.google.protobuf.Duration;
38
39
// JSON format conversion
40
JsonFormat.Printer printer = JsonFormat.printer();
41
JsonFormat.Parser parser = JsonFormat.parser();
42
43
// Create and print a message as JSON
44
String jsonString = printer.print(myMessage);
45
46
// Parse JSON back to protobuf message
47
MyMessage.Builder messageBuilder = MyMessage.newBuilder();
48
parser.merge(jsonString, messageBuilder);
49
MyMessage parsedMessage = messageBuilder.build();
50
51
// Timestamp utilities
52
Timestamp now = Timestamps.now();
53
Timestamp fromEpoch = Timestamps.fromMillis(System.currentTimeMillis());
54
String timestampString = Timestamps.toString(now);
55
56
// Duration utilities
57
Duration oneHour = Durations.fromHours(1);
58
Duration fiveMinutes = Durations.fromMinutes(5);
59
Duration total = Durations.add(oneHour, fiveMinutes);
60
61
// Proto file utilities
62
String editionString = ProtoFileUtil.getEditionString(Edition.EDITION_2023);
63
```
64
65
## Architecture
66
67
The protobuf-java-util library is organized around several key functional areas:
68
69
- **JSON Format Conversion**: Bidirectional conversion between protobuf messages and JSON using Proto3 JSON mapping specification
70
- **Field Mask Operations**: Utilities for selective field operations, merging, and filtering using FieldMask proto type
71
- **Time Utilities**: Comprehensive timestamp and duration manipulation supporting RFC 3339 format and various time unit conversions
72
- **Structured Data**: Builder utilities for creating google.protobuf.Struct and google.protobuf.Value messages
73
- **Proto File Utilities**: Helper functions for working with proto file metadata and descriptors
74
75
## Capabilities
76
77
### JSON Format Conversion
78
79
Complete bidirectional conversion system between protobuf messages and JSON format, supporting Proto3 JSON mapping specification with configurable options for field naming, default values, and type registries.
80
81
```java { .api }
82
public static JsonFormat.Printer printer();
83
public static JsonFormat.Parser parser();
84
85
// Printer methods
86
public JsonFormat.Printer usingTypeRegistry(TypeRegistry registry);
87
public JsonFormat.Printer includingDefaultValueFields(Set<FieldDescriptor> fields);
88
public JsonFormat.Printer preservingProtoFieldNames();
89
public JsonFormat.Printer omittingInsignificantWhitespace();
90
public String print(MessageOrBuilder message) throws InvalidProtocolBufferException;
91
92
// Parser methods
93
public JsonFormat.Parser usingTypeRegistry(TypeRegistry registry);
94
public JsonFormat.Parser ignoringUnknownFields();
95
public void merge(String json, Message.Builder builder) throws InvalidProtocolBufferException;
96
```
97
98
[JSON Format Conversion](./json-format.md)
99
100
### Field Mask Operations
101
102
Comprehensive utilities for working with FieldMask protobuf type, enabling selective field operations, merging strategies, validation, and set operations on field paths.
103
104
```java { .api }
105
public static FieldMask fromString(String value);
106
public static FieldMask fromStringList(Class<? extends Message> type, Iterable<String> paths);
107
public static String toJsonString(FieldMask fieldMask);
108
public static boolean isValid(Class<? extends Message> type, FieldMask fieldMask);
109
public static FieldMask union(FieldMask firstMask, FieldMask secondMask, FieldMask... otherMasks);
110
public static void merge(FieldMask mask, Message source, Message.Builder destination);
111
```
112
113
[Field Mask Operations](./field-mask.md)
114
115
### Timestamp Utilities
116
117
Complete timestamp manipulation supporting RFC 3339 format, various time unit conversions, validation, comparison, and arithmetic operations with full range checking and normalization.
118
119
```java { .api }
120
public static final Timestamp MIN_VALUE;
121
public static final Timestamp MAX_VALUE;
122
public static final Timestamp EPOCH;
123
124
public static Timestamp now();
125
public static Timestamp fromMillis(long milliseconds);
126
public static Timestamp parse(String value) throws ParseException;
127
public static String toString(Timestamp timestamp);
128
public static boolean isValid(Timestamp timestamp);
129
public static Duration between(Timestamp from, Timestamp to);
130
public static Timestamp add(Timestamp start, Duration length);
131
```
132
133
[Timestamp Utilities](./timestamps.md)
134
135
### Duration Utilities
136
137
Duration manipulation with support for various time units, string format conversion, validation, comparison, and arithmetic operations with proper normalization and range checking.
138
139
```java { .api }
140
public static final Duration MIN_VALUE;
141
public static final Duration MAX_VALUE;
142
public static final Duration ZERO;
143
144
public static Duration fromHours(long hours);
145
public static Duration fromMinutes(long minutes);
146
public static Duration fromSeconds(long seconds);
147
public static Duration parse(String value) throws ParseException;
148
public static String toString(Duration duration);
149
public static boolean isValid(Duration duration);
150
public static Duration add(Duration d1, Duration d2);
151
public static Duration subtract(Duration d1, Duration d2);
152
```
153
154
[Duration Utilities](./durations.md)
155
156
### Structured Data Utilities
157
158
Factory methods for creating google.protobuf.Struct and google.protobuf.Value messages with type-safe builders for various data types including null, boolean, number, string, struct, and list values.
159
160
```java { .api }
161
// Structs utilities
162
public static Struct of(String k1, Value v1);
163
public static Struct of(String k1, Value v1, String k2, Value v2);
164
public static Struct of(String k1, Value v1, String k2, Value v2, String k3, Value v3);
165
166
// Values utilities
167
public static Value ofNull();
168
public static Value of(boolean value);
169
public static Value of(double value);
170
public static Value of(String value);
171
public static Value of(Struct value);
172
public static Value of(ListValue value);
173
```
174
175
[Structured Data Utilities](./structured-data.md)
176
177
### Proto File Utilities
178
179
Utility functions for working with proto file metadata and descriptors, particularly for handling protobuf edition information.
180
181
```java { .api }
182
public static String getEditionString(Edition edition);
183
```
184
185
## Types
186
187
```java { .api }
188
// Field Mask Merge Options
189
public static final class FieldMaskUtil.MergeOptions {
190
public boolean replaceMessageFields();
191
public boolean replaceRepeatedFields();
192
public boolean replacePrimitiveFields();
193
public FieldMaskUtil.MergeOptions setReplaceMessageFields(boolean value);
194
public FieldMaskUtil.MergeOptions setReplaceRepeatedFields(boolean value);
195
public FieldMaskUtil.MergeOptions setReplacePrimitiveFields(boolean value);
196
}
197
198
// JSON Format Type Registry
199
public static class JsonFormat.TypeRegistry {
200
public static TypeRegistry getEmptyTypeRegistry();
201
public static TypeRegistry.Builder newBuilder();
202
public Descriptor find(String name);
203
204
public static class Builder {
205
public Builder add(Descriptor messageType);
206
public Builder add(Iterable<Descriptor> messageTypes);
207
public TypeRegistry build();
208
}
209
}
210
```