Add a FieldMaskUtil#trim overload that accepts TrimOptions and allows retaining unset primitive field state.

Existing FieldMaskUtil#trim method behavior remains the same: unset primitive fields specified in the field mask will be explicitly set to their default values after trimming.

PiperOrigin-RevId: 754114689

Author: protobuf-github-bot

java/util/src/main/java/com/google/protobuf/util/FieldMaskUtil.java

@@ -25,19 +25,15 @@
 import java.util.List;
 import javax.annotation.Nullable;
 
-/**
- * Utility helper functions to work with {@link com.google.protobuf.FieldMask}.
- */
+/** Utility helper functions to work with {@link com.google.protobuf.FieldMask}. */
 public final class FieldMaskUtil {
   private static final String FIELD_PATH_SEPARATOR = ",";
   private static final String FIELD_PATH_SEPARATOR_REGEX = ",";
   private static final String FIELD_SEPARATOR_REGEX = "\\.";
 
   private FieldMaskUtil() {}
 
-  /**
-   * Converts a FieldMask to a string.
-   */
+  /** Converts a FieldMask to a string. */
   public static String toString(FieldMask fieldMask) {
     // TODO: Consider using com.google.common.base.Joiner here instead.
     StringBuilder result = new StringBuilder();
@@ -57,9 +53,7 @@ public static String toString(FieldMask fieldMask) {
     return result.toString();
   }
 
-  /**
-   * Parses from a string to a FieldMask.
-   */
+  /** Parses from a string to a FieldMask. */
   public static FieldMask fromString(String value) {
     // TODO: Consider using com.google.common.base.Splitter here instead.
     return fromStringList(Arrays.asList(value.split(FIELD_PATH_SEPARATOR_REGEX)));
@@ -145,8 +139,8 @@ public static FieldMask fromFieldNumbers(
   }
 
   /**
-   * Converts a field mask to a Proto3 JSON string, that is converting from snake case to camel
-   * case and joining all paths into one string with commas.
+   * Converts a field mask to a Proto3 JSON string, that is converting from snake case to camel case
+   * and joining all paths into one string with commas.
    */
   public static String toJsonString(FieldMask fieldMask) {
     List<String> paths = new ArrayList<String>(fieldMask.getPathsCount());
@@ -175,18 +169,14 @@ public static FieldMask fromJsonString(String value) {
     return builder.build();
   }
 
-  /**
-   * Checks whether paths in a given fields mask are valid.
-   */
+  /** Checks whether paths in a given fields mask are valid. */
   public static boolean isValid(Class<? extends Message> type, FieldMask fieldMask) {
     Descriptor descriptor = Internal.getDefaultInstance(type).getDescriptorForType();
 
     return isValid(descriptor, fieldMask);
   }
 
-  /**
-   * Checks whether paths in a given fields mask are valid.
-   */
+  /** Checks whether paths in a given fields mask are valid. */
   public static boolean isValid(Descriptor descriptor, FieldMask fieldMask) {
     for (String path : fieldMask.getPathsList()) {
       if (!isValid(descriptor, path)) {
@@ -196,9 +186,7 @@ public static boolean isValid(Descriptor descriptor, FieldMask fieldMask) {
     return true;
   }
 
-  /**
-   * Checks whether a given field path is valid.
-   */
+  /** Checks whether a given field path is valid. */
   public static boolean isValid(Class<? extends Message> type, String path) {
     Descriptor descriptor = Internal.getDefaultInstance(type).getDescriptorForType();
 
@@ -229,17 +217,14 @@ public static boolean isValid(@Nullable Descriptor descriptor, String path) {
   }
 
   /**
-   * Converts a FieldMask to its canonical form. In the canonical form of a
-   * FieldMask, all field paths are sorted alphabetically and redundant field
-   * paths are removed.
+   * Converts a FieldMask to its canonical form. In the canonical form of a FieldMask, all field
+   * paths are sorted alphabetically and redundant field paths are removed.
    */
   public static FieldMask normalize(FieldMask mask) {
     return new FieldMaskTree(mask).toFieldMask();
   }
 
-  /**
-   * Creates a union of two or more FieldMasks.
-   */
+  /** Creates a union of two or more FieldMasks. */
   public static FieldMask union(
       FieldMask firstMask, FieldMask secondMask, FieldMask... otherMasks) {
     FieldMaskTree maskTree = new FieldMaskTree(firstMask).mergeFromFieldMask(secondMask);
@@ -265,9 +250,7 @@ public static FieldMask subtract(
     return maskTree.toFieldMask();
   }
 
-  /**
-   * Calculates the intersection of two FieldMasks.
-   */
+  /** Calculates the intersection of two FieldMasks. */
   public static FieldMask intersection(FieldMask mask1, FieldMask mask2) {
     FieldMaskTree tree = new FieldMaskTree(mask1);
     FieldMaskTree result = new FieldMaskTree();
@@ -277,9 +260,7 @@ public static FieldMask intersection(FieldMask mask1, FieldMask mask2) {
     return result.toFieldMask();
   }
 
-  /**
-   * Options to customize merging behavior.
-   */
+  /** Options to customize merging behavior. */
   public static final class MergeOptions {
     private boolean replaceMessageFields = false;
     private boolean replaceRepeatedFields = false;
@@ -288,25 +269,25 @@ public static final class MergeOptions {
     private boolean replacePrimitiveFields = false;
 
     /**
-     * Whether to replace message fields (i.e., discard existing content in
-     * destination message fields).
+     * Whether to replace message fields (i.e., discard existing content in destination message
+     * fields).
      */
     public boolean replaceMessageFields() {
       return replaceMessageFields;
     }
 
     /**
-     * Whether to replace repeated fields (i.e., discard existing content in
-     * destination repeated fields).
+     * Whether to replace repeated fields (i.e., discard existing content in destination repeated
+     * fields).
      */
     public boolean replaceRepeatedFields() {
       return replaceRepeatedFields;
     }
 
     /**
-     * Whether to replace primitive (non-repeated and non-message) fields in
-     * destination message fields with the source primitive fields (i.e., clear
-     * destination field if source field is not set).
+     * Whether to replace primitive (non-repeated and non-message) fields in destination message
+     * fields with the source primitive fields (i.e., clear destination field if source field is not
+     * set).
      */
     public boolean replacePrimitiveFields() {
       return replacePrimitiveFields;
@@ -365,20 +346,66 @@ public static void merge(
     new FieldMaskTree(mask).merge(source, destination, options);
   }
 
-  /**
-   * Merges fields specified by a FieldMask from one message to another.
-   */
+  /** Merges fields specified by a FieldMask from one message to another. */
   public static void merge(FieldMask mask, Message source, Message.Builder destination) {
     merge(mask, source, destination, new MergeOptions());
   }
 
+  /** Options to customize trimming behavior. */
+  public static final class TrimOptions {
+    private boolean retainPrimitiveFieldUnsetState = false;
+
+    /** Whether the unset state of primitive fields should be retained when trimming. */
+    public boolean retainPrimitiveFieldUnsetState() {
+      return retainPrimitiveFieldUnsetState;
+    }
+
+    /**
+     * Specify whether the unset state of primitive fields should be retained when trimming.
+     * Defaults to false.
+     *
+     * <p>If true, unset primitive fields indicated by the field mask will remain unset.
+     *
+     * <p>If false, unset primitive fields indicated by the field mask will be set to their default
+     * values.
+     */
+    @CanIgnoreReturnValue
+    public TrimOptions setRetainPrimitiveFieldUnsetState(boolean value) {
+      retainPrimitiveFieldUnsetState = value;
+      return this;
+    }
+  }
+
   /**
-   * Returns the result of keeping only the masked fields of the given proto.
+   * Returns the result of keeping only the masked fields of the given proto with the specified trim
+   * options.
+   *
+   * <p>Note that the behavior with the default {@link TrimOptions} is for unset primitive fields
+   * indicated in the field mask to be explicitly set to their default values. Use {@code new
+   * TrimOptions().setRetainPrimitiveFieldUnsetState(true)} to retain the unset state of primitive
+   * fields.
    */
   @SuppressWarnings("unchecked")
-  public static <P extends Message> P trim(FieldMask mask, P source) {
-   Message.Builder destination = source.newBuilderForType();
-    merge(mask, source, destination);
+  public static <P extends Message> P trim(FieldMask mask, P source, TrimOptions options) {
+    Message.Builder destination = source.newBuilderForType();
+    merge(
+        mask,
+        source,
+        destination,
+        new MergeOptions().setReplacePrimitiveFields(options.retainPrimitiveFieldUnsetState()));
     return (P) destination.build();
   }
+
+  /**
+   * Returns the result of keeping only the masked fields of the given proto.
+   *
+   * <p>This method is equivalent to {@link #trim(FieldMask, Message, TrimOptions)} with default
+   * {@link TrimOptions}.
+   *
+   * <p>Note that unset primitive fields indicated in the field mask will be explicitly set to their
+   * default values.
+   */
+  public static <P extends Message> P trim(FieldMask mask, P source) {
+    return trim(mask, source, new TrimOptions());
+  }
 }