Field Mask Operations

/**
 * Parses a string to create a FieldMask.
 * 
 * @param value Comma-separated field paths
 * @return FieldMask containing the parsed paths
 */
public static FieldMask fromString(String value);

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

/**
 * Constructs a FieldMask from a list of field paths with validation.
 * 
 * @param type Message class for validation
 * @param paths Iterable of field path strings
 * @return FieldMask containing the validated paths
 * @throws IllegalArgumentException if any field path is invalid
 */
public static FieldMask fromStringList(Class<? extends Message> type, Iterable<String> paths);

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

/**
 * Constructs a FieldMask from a list of field paths without validation.
 * 
 * @param paths Iterable of field path strings
 * @return FieldMask containing the paths
 */
public static FieldMask fromStringList(Iterable<String> paths);

/**
 * Constructs a FieldMask from field numbers.
 * 
 * @param type Message class for field resolution
 * @param fieldNumbers Variable arguments of field numbers
 * @return FieldMask containing paths for the specified field numbers
 * @throws IllegalArgumentException if any field number is invalid
 */
public static FieldMask fromFieldNumbers(Class<? extends Message> type, int... fieldNumbers);

/**
 * Constructs a FieldMask from field numbers.
 * 
 * @param type Message class for field resolution
 * @param fieldNumbers Iterable of field numbers
 * @return FieldMask containing paths for the specified field numbers
 * @throws IllegalArgumentException if any field number is invalid
 */
public static FieldMask fromFieldNumbers(Class<? extends Message> type, Iterable<Integer> fieldNumbers);

/**
 * Converts a FieldMask to a string representation.
 * 
 * @param fieldMask FieldMask to convert
 * @return Comma-separated string of field paths
 */
public static String toString(FieldMask fieldMask);

/**
 * Converts a FieldMask to Proto3 JSON string format.
 * Converts snake_case to camelCase and joins paths with commas.
 * 
 * @param fieldMask FieldMask to convert
 * @return JSON-formatted string representation
 */
public static String toJsonString(FieldMask fieldMask);

/**
 * Converts a Proto3 JSON string to FieldMask.
 * Splits on commas and converts camelCase to snake_case.
 * 
 * @param value JSON-formatted field mask string
 * @return FieldMask parsed from JSON string
 */
public static FieldMask fromJsonString(String value);

/**
 * Checks whether paths in a FieldMask are valid for a message type.
 * 
 * @param type Message class for validation
 * @param fieldMask FieldMask to validate
 * @return true if all paths are valid, false otherwise
 */
public static boolean isValid(Class<? extends Message> type, FieldMask fieldMask);

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

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

/**
 * Checks whether a field path is valid for a message descriptor.
 * 
 * @param descriptor Message descriptor for validation (nullable)
 * @param path Field path to validate
 * @return true if path is valid, false otherwise
 */
public static boolean isValid(Descriptor descriptor, String path);

/**
 * Converts a FieldMask to its canonical form.
 * Sorts field paths alphabetically and removes redundant paths.
 * 
 * @param mask FieldMask to normalize
 * @return Normalized FieldMask
 */
public static FieldMask normalize(FieldMask mask);

/**
 * Creates a union of two or more FieldMasks.
 * 
 * @param firstMask First FieldMask
 * @param secondMask Second FieldMask
 * @param otherMasks Additional FieldMasks to union
 * @return FieldMask containing union of all input masks
 */
public static FieldMask union(FieldMask firstMask, FieldMask secondMask, FieldMask... otherMasks);

/**
 * Subtracts FieldMasks from the first mask.
 * 
 * @param firstMask Base FieldMask to subtract from
 * @param secondMask FieldMask to subtract
 * @param otherMasks Additional FieldMasks to subtract
 * @return FieldMask with specified paths removed
 */
public static FieldMask subtract(FieldMask firstMask, FieldMask secondMask, FieldMask... otherMasks);

/**
 * Calculates the intersection of two FieldMasks.
 * 
 * @param mask1 First FieldMask
 * @param mask2 Second FieldMask
 * @return FieldMask containing intersection of the two masks
 */
public static FieldMask intersection(FieldMask mask1, FieldMask mask2);

/**
 * Merges fields specified by a FieldMask with custom merge options.
 * 
 * @param mask FieldMask specifying which fields to merge
 * @param source Source message to copy fields from
 * @param destination Destination message builder to merge into
 * @param options Merge options controlling merge behavior
 */
public static void merge(FieldMask mask, Message source, Message.Builder destination, FieldMaskUtil.MergeOptions options);

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

/**
 * Returns a new message containing only the fields specified by the mask.
 * 
 * @param mask FieldMask specifying which fields to keep
 * @param source Source message to trim
 * @return New message of same type containing only masked fields
 */
public static <P extends Message> P trim(FieldMask mask, P source);

/**
 * Options to customize merging behavior.
 */
public static final class FieldMaskUtil.MergeOptions {
  /**
   * Gets whether to replace message fields during merge.
   * 
   * @return true if message fields should be replaced
   */
  public boolean replaceMessageFields();
  
  /**
   * Gets whether to replace repeated fields during merge.
   * 
   * @return true if repeated fields should be replaced
   */
  public boolean replaceRepeatedFields();
  
  /**
   * Gets whether to replace primitive fields during merge.
   * 
   * @return true if primitive fields should be replaced
   */
  public boolean replacePrimitiveFields();
  
  /**
   * Sets whether to replace message fields during merge.
   * 
   * @param value true to replace message fields, false to merge them
   * @return This MergeOptions instance for method chaining
   */
  public FieldMaskUtil.MergeOptions setReplaceMessageFields(boolean value);
  
  /**
   * Sets whether to replace repeated fields during merge.
   * 
   * @param value true to replace repeated fields, false to append elements
   * @return This MergeOptions instance for method chaining
   */
  public FieldMaskUtil.MergeOptions setReplaceRepeatedFields(boolean value);
  
  /**
   * Sets whether to replace primitive fields during merge.
   * 
   * @param value true to replace primitive fields, false to always set from source
   * @return This MergeOptions instance for method chaining
   */
  public FieldMaskUtil.MergeOptions setReplacePrimitiveFields(boolean value);
}

import com.google.protobuf.util.FieldMaskUtil;
import com.google.protobuf.FieldMask;

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

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

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

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

// Set operations
FieldMask mask1 = FieldMaskUtil.fromString("name,email");
FieldMask mask2 = FieldMaskUtil.fromString("email,age");
FieldMask union = FieldMaskUtil.union(mask1, mask2); // "name,email,age"
FieldMask intersection = FieldMaskUtil.intersection(mask1, mask2); // "email"

// Merge with custom options
FieldMaskUtil.MergeOptions options = new FieldMaskUtil.MergeOptions()
    .setReplaceMessageFields(true)
    .setReplaceRepeatedFields(false);

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

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