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
```