0
# Field Mask Operations
1

2
Comprehensive utilities for working with FieldMask protobuf type, enabling selective field operations, merging strategies, validation, and set operations on field paths. FieldMask allows precise control over which fields are included in operations like updates, queries, and data transfers.
3

4
## Capabilities
5

6
### FieldMask Creation from Strings
7

8
Create FieldMask instances from string representations of field paths.
9

10
```java { .api }
11
/**
12
 * Parses a string to create a FieldMask.
13
 * 
14
 * @param value Comma-separated field paths
15
 * @return FieldMask containing the parsed paths
16
 */
17
public static FieldMask fromString(String value);
18

19
/**
20
 * Parses and validates a string to create a FieldMask.
21
 * 
22
 * @param type Message class for validation
23
 * @param value Comma-separated field paths  
24
 * @return FieldMask containing the parsed and validated paths
25
 * @throws IllegalArgumentException if any field path is invalid
26
 */
27
public static FieldMask fromString(Class<? extends Message> type, String value);
28
```
29

30
### FieldMask Creation from Path Lists
31

32
Create FieldMask instances from collections of field paths.
33

34
```java { .api }
35
/**
36
 * Constructs a FieldMask from a list of field paths with validation.
37
 * 
38
 * @param type Message class for validation
39
 * @param paths Iterable of field path strings
40
 * @return FieldMask containing the validated paths
41
 * @throws IllegalArgumentException if any field path is invalid
42
 */
43
public static FieldMask fromStringList(Class<? extends Message> type, Iterable<String> paths);
44

45
/**
46
 * Constructs a FieldMask from a list of field paths with descriptor validation.
47
 * 
48
 * @param descriptor Message descriptor for validation
49
 * @param paths Iterable of field path strings
50
 * @return FieldMask containing the validated paths
51
 * @throws IllegalArgumentException if any field path is invalid
52
 */
53
public static FieldMask fromStringList(Descriptor descriptor, Iterable<String> paths);
54

55
/**
56
 * Constructs a FieldMask from a list of field paths without validation.
57
 * 
58
 * @param paths Iterable of field path strings
59
 * @return FieldMask containing the paths
60
 */
61
public static FieldMask fromStringList(Iterable<String> paths);
62
```
63

64
### FieldMask Creation from Field Numbers
65

66
Create FieldMask instances from protobuf field numbers.
67

68
```java { .api }
69
/**
70
 * Constructs a FieldMask from field numbers.
71
 * 
72
 * @param type Message class for field resolution
73
 * @param fieldNumbers Variable arguments of field numbers
74
 * @return FieldMask containing paths for the specified field numbers
75
 * @throws IllegalArgumentException if any field number is invalid
76
 */
77
public static FieldMask fromFieldNumbers(Class<? extends Message> type, int... fieldNumbers);
78

79
/**
80
 * Constructs a FieldMask from field numbers.
81
 * 
82
 * @param type Message class for field resolution
83
 * @param fieldNumbers Iterable of field numbers
84
 * @return FieldMask containing paths for the specified field numbers
85
 * @throws IllegalArgumentException if any field number is invalid
86
 */
87
public static FieldMask fromFieldNumbers(Class<? extends Message> type, Iterable<Integer> fieldNumbers);
88
```
89

90
### String Conversion
91

92
Convert FieldMask instances to string representations.
93

94
```java { .api }
95
/**
96
 * Converts a FieldMask to a string representation.
97
 * 
98
 * @param fieldMask FieldMask to convert
99
 * @return Comma-separated string of field paths
100
 */
101
public static String toString(FieldMask fieldMask);
102

103
/**
104
 * Converts a FieldMask to Proto3 JSON string format.
105
 * Converts snake_case to camelCase and joins paths with commas.
106
 * 
107
 * @param fieldMask FieldMask to convert
108
 * @return JSON-formatted string representation
109
 */
110
public static String toJsonString(FieldMask fieldMask);
111

112
/**
113
 * Converts a Proto3 JSON string to FieldMask.
114
 * Splits on commas and converts camelCase to snake_case.
115
 * 
116
 * @param value JSON-formatted field mask string
117
 * @return FieldMask parsed from JSON string
118
 */
119
public static FieldMask fromJsonString(String value);
120
```
121

122
### Validation
123

124
Validate FieldMask instances and individual field paths.
125

126
```java { .api }
127
/**
128
 * Checks whether paths in a FieldMask are valid for a message type.
129
 * 
130
 * @param type Message class for validation
131
 * @param fieldMask FieldMask to validate
132
 * @return true if all paths are valid, false otherwise
133
 */
134
public static boolean isValid(Class<? extends Message> type, FieldMask fieldMask);
135

136
/**
137
 * Checks whether paths in a FieldMask are valid for a message descriptor.
138
 * 
139
 * @param descriptor Message descriptor for validation
140
 * @param fieldMask FieldMask to validate
141
 * @return true if all paths are valid, false otherwise
142
 */
143
public static boolean isValid(Descriptor descriptor, FieldMask fieldMask);
144

145
/**
146
 * Checks whether a field path is valid for a message type.
147
 * 
148
 * @param type Message class for validation
149
 * @param path Field path to validate
150
 * @return true if path is valid, false otherwise
151
 */
152
public static boolean isValid(Class<? extends Message> type, String path);
153

154
/**
155
 * Checks whether a field path is valid for a message descriptor.
156
 * 
157
 * @param descriptor Message descriptor for validation (nullable)
158
 * @param path Field path to validate
159
 * @return true if path is valid, false otherwise
160
 */
161
public static boolean isValid(Descriptor descriptor, String path);
162
```
163

164
### Set Operations
165

166
Perform set operations on FieldMask instances.
167

168
```java { .api }
169
/**
170
 * Converts a FieldMask to its canonical form.
171
 * Sorts field paths alphabetically and removes redundant paths.
172
 * 
173
 * @param mask FieldMask to normalize
174
 * @return Normalized FieldMask
175
 */
176
public static FieldMask normalize(FieldMask mask);
177

178
/**
179
 * Creates a union of two or more FieldMasks.
180
 * 
181
 * @param firstMask First FieldMask
182
 * @param secondMask Second FieldMask
183
 * @param otherMasks Additional FieldMasks to union
184
 * @return FieldMask containing union of all input masks
185
 */
186
public static FieldMask union(FieldMask firstMask, FieldMask secondMask, FieldMask... otherMasks);
187

188
/**
189
 * Subtracts FieldMasks from the first mask.
190
 * 
191
 * @param firstMask Base FieldMask to subtract from
192
 * @param secondMask FieldMask to subtract
193
 * @param otherMasks Additional FieldMasks to subtract
194
 * @return FieldMask with specified paths removed
195
 */
196
public static FieldMask subtract(FieldMask firstMask, FieldMask secondMask, FieldMask... otherMasks);
197

198
/**
199
 * Calculates the intersection of two FieldMasks.
200
 * 
201
 * @param mask1 First FieldMask
202
 * @param mask2 Second FieldMask
203
 * @return FieldMask containing intersection of the two masks
204
 */
205
public static FieldMask intersection(FieldMask mask1, FieldMask mask2);
206
```
207

208
### Message Merging
209

210
Merge fields from one message to another using FieldMask selection.
211

212
```java { .api }
213
/**
214
 * Merges fields specified by a FieldMask with custom merge options.
215
 * 
216
 * @param mask FieldMask specifying which fields to merge
217
 * @param source Source message to copy fields from
218
 * @param destination Destination message builder to merge into
219
 * @param options Merge options controlling merge behavior
220
 */
221
public static void merge(FieldMask mask, Message source, Message.Builder destination, FieldMaskUtil.MergeOptions options);
222

223
/**
224
 * Merges fields specified by a FieldMask with default options.
225
 * 
226
 * @param mask FieldMask specifying which fields to merge
227
 * @param source Source message to copy fields from
228
 * @param destination Destination message builder to merge into
229
 */
230
public static void merge(FieldMask mask, Message source, Message.Builder destination);
231

232
/**
233
 * Returns a new message containing only the fields specified by the mask.
234
 * 
235
 * @param mask FieldMask specifying which fields to keep
236
 * @param source Source message to trim
237
 * @return New message of same type containing only masked fields
238
 */
239
public static <P extends Message> P trim(FieldMask mask, P source);
240
```
241

242
### Merge Options Configuration
243

244
Configure merge behavior for field operations.
245

246
```java { .api }
247
/**
248
 * Options to customize merging behavior.
249
 */
250
public static final class FieldMaskUtil.MergeOptions {
251
  /**
252
   * Gets whether to replace message fields during merge.
253
   * 
254
   * @return true if message fields should be replaced
255
   */
256
  public boolean replaceMessageFields();
257
  
258
  /**
259
   * Gets whether to replace repeated fields during merge.
260
   * 
261
   * @return true if repeated fields should be replaced
262
   */
263
  public boolean replaceRepeatedFields();
264
  
265
  /**
266
   * Gets whether to replace primitive fields during merge.
267
   * 
268
   * @return true if primitive fields should be replaced
269
   */
270
  public boolean replacePrimitiveFields();
271
  
272
  /**
273
   * Sets whether to replace message fields during merge.
274
   * 
275
   * @param value true to replace message fields, false to merge them
276
   * @return This MergeOptions instance for method chaining
277
   */
278
  public FieldMaskUtil.MergeOptions setReplaceMessageFields(boolean value);
279
  
280
  /**
281
   * Sets whether to replace repeated fields during merge.
282
   * 
283
   * @param value true to replace repeated fields, false to append elements
284
   * @return This MergeOptions instance for method chaining
285
   */
286
  public FieldMaskUtil.MergeOptions setReplaceRepeatedFields(boolean value);
287
  
288
  /**
289
   * Sets whether to replace primitive fields during merge.
290
   * 
291
   * @param value true to replace primitive fields, false to always set from source
292
   * @return This MergeOptions instance for method chaining
293
   */
294
  public FieldMaskUtil.MergeOptions setReplacePrimitiveFields(boolean value);
295
}
296
```
297

298
**Usage Examples:**
299

300
```java
301
import com.google.protobuf.util.FieldMaskUtil;
302
import com.google.protobuf.FieldMask;
303

304
// Create FieldMask from string
305
FieldMask mask = FieldMaskUtil.fromString("name,email,address.street");
306

307
// Create and validate FieldMask
308
FieldMask validatedMask = FieldMaskUtil.fromString(User.class, "name,email,age");
309

310
// Convert to JSON format
311
String jsonMask = FieldMaskUtil.toJsonString(mask); // "name,email,address.street"
312

313
// Validate field paths
314
boolean isValid = FieldMaskUtil.isValid(User.class, "profile.name");
315

316
// Set operations
317
FieldMask mask1 = FieldMaskUtil.fromString("name,email");
318
FieldMask mask2 = FieldMaskUtil.fromString("email,age");
319
FieldMask union = FieldMaskUtil.union(mask1, mask2); // "name,email,age"
320
FieldMask intersection = FieldMaskUtil.intersection(mask1, mask2); // "email"
321

322
// Merge with custom options
323
FieldMaskUtil.MergeOptions options = new FieldMaskUtil.MergeOptions()
324
    .setReplaceMessageFields(true)
325
    .setReplaceRepeatedFields(false);
326

327
User.Builder userBuilder = User.newBuilder();
328
FieldMaskUtil.merge(mask, sourceUser, userBuilder, options);
329
User mergedUser = userBuilder.build();
330

331
// Trim message to only include masked fields
332
User trimmedUser = FieldMaskUtil.trim(mask, originalUser);
333
```