Update default behavior for PATCH ADDs with filter

CHANGELOG.md

@@ -2,7 +2,15 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
-## v3.2.1 - TBD
+## v4.0.0 - TBD
+Updated the default behavior for ADD patch requests with value filters (e.g.,
+`emails[type eq "work"].display`). The SCIM SDK will now target existing values within the
+multi-valued attribute. For more background on this type of patch request, see the release notes for
+the 3.2.0 release where this was introduced (but not made the default). To restore the old behavior,
+set the following property in your application:
+```
+PatchOperation.APPEND_NEW_PATCH_VALUES_PROPERTY = true;
+```
 
 ## v3.2.0 - 2024-Dec-04
 Fixed an issue where `AndFilter.equals()` and `OrFilter.equals()` could incorrectly evaluate to

pom.xml

@@ -18,7 +18,7 @@
   <modelVersion>4.0.0</modelVersion>
   <groupId>com.unboundid.product.scim2</groupId>
   <artifactId>scim2-parent</artifactId>
-  <version>3.2.1-SNAPSHOT</version>
+  <version>4.0.0-SNAPSHOT</version>
   <packaging>pom</packaging>
   <name>UnboundID SCIM2 SDK Parent</name>
   <description>

scim2-assembly/pom.xml

@@ -19,7 +19,7 @@
   <parent>
     <artifactId>scim2-parent</artifactId>
     <groupId>com.unboundid.product.scim2</groupId>
-    <version>3.2.1-SNAPSHOT</version>
+    <version>4.0.0-SNAPSHOT</version>
   </parent>
   <artifactId>scim2-assembly</artifactId>
   <packaging>pom</packaging>

scim2-sdk-client/pom.xml

@@ -19,7 +19,7 @@
     <parent>
         <artifactId>scim2-parent</artifactId>
         <groupId>com.unboundid.product.scim2</groupId>
-        <version>3.2.1-SNAPSHOT</version>
+        <version>4.0.0-SNAPSHOT</version>
     </parent>
     <artifactId>scim2-sdk-client</artifactId>
     <packaging>jar</packaging>

scim2-sdk-common/pom.xml

@@ -19,7 +19,7 @@
     <parent>
         <artifactId>scim2-parent</artifactId>
         <groupId>com.unboundid.product.scim2</groupId>
-        <version>3.2.1-SNAPSHOT</version>
+        <version>4.0.0-SNAPSHOT</version>
     </parent>
     <artifactId>scim2-sdk-common</artifactId>
     <packaging>jar</packaging>

scim2-sdk-common/src/main/java/com/unboundid/scim2/common/messages/PatchOperation.java

@@ -329,8 +329,10 @@ private void validateAddOpWithFilter(@Nullable final Path path,
     }
 
     /**
-     * This method processes an add operation whose attribute path contains a
-     * value selection filter. This operation takes the form of:
+     * This method processes an add operation that aims to update a value within
+     * an array. For example, the following patch operation attempts to update
+     * a user's work address by adding a new street address value. Addresses
+     * other than the work address will not be updated.
      * <pre>
      *   {
      *     "op": "add",
@@ -339,33 +341,52 @@ private void validateAddOpWithFilter(@Nullable final Path path,
      *   }
      * </pre>
      *
-     * When this patch operation is applied by a SCIM service provider, it
-     * should result in both the {@code streetAddress} and the {@code type}
-     * fields being appended to the {@code addresses} attribute.
+     * By default, the SCIM SDK will look through the {@code addresses} on the
+     * target resource and add the new value for any address that matches. For
+     * example, consider an existing user resource that has:
      * <pre>
      *   "addresses": [
      *       {
+     *         "formatted": "Formatted Ghost Avenue",
+     *         "type": "work"
+     *       },
+     *       {
+     *         "formatted": "Unrelated Address",
+     *         "type": "home"
+     *       }
+     *   ]
+     * </pre>
+     *
+     * If the above patch operation is applied to this resource, it will result
+     * in:
+     * <pre>
+     *   "addresses": [
+     *       {
+     *         "formatted": "Formatted Ghost Avenue",
      *         "streetAddress": "100 Tricky Ghost Avenue",
      *         "type": "work"
+     *       },
+     *       {
+     *         "formatted": "Unrelated Address",
+     *         "type": "home"
      *       }
      *   ]
      * </pre>
      *
-     * While RFC 7644 does not dictate or describe this use case, this
-     * convention is nevertheless used by some SCIM service providers to specify
-     * additional data for a multi-valued parameter, such as a work address or a
-     * home email.
-     * <br><br>
-     * Note that filters in attribute paths are treated differently for other
-     * types of patch operations. For example, a {@code remove} operation with a
-     * path of {@code addresses[type eq "work"]} would only delete address
-     * values that contain a {@code "type": "work"} field. In other words, these
-     * filters are normally used to modify a subset of multi-valued attributes,
-     * but the use case for add operations is unique.
+     * If the patch operation is applied to a resource that has no work address,
+     * then a new value will be added to the multi-valued attribute.
+     * <pre>
+     *   "addresses": [
+     *       {
+     *         "streetAddress": "100 Tricky Ghost Avenue",
+     *         "type": "work"
+     *       }
+     *    ]
+     * </pre>
      *
      * @param path              The attribute path that contains a value filter.
-     *                          This value filter will be added as part of the
-     *                          new attribute value.
+     *                          This value filter will specify which values
+     *                          within the array that should be updated.
      * @param existingResource  The most recent copy of the resource.
      * @param value             The new sub-attribute value that should be added
      *                          to the existing resource.
@@ -2055,8 +2076,8 @@ private static void validateOperationValue(@Nullable final Path path,
 
   /**
    * This field represents a property that can customize behavior when
-   * processing ADD PATCH operations with a value filter. This is used for
-   * multi-valued attributes such as {@code emails}, and is not used for
+   * processing {@code add} PATCH operations with a value filter. This is used
+   * for multi-valued attributes such as {@code emails}, and is not used for
    * {@code remove} or {@code replace} operations. For example, consider the
    * following patch request:
    * <pre>
@@ -2074,16 +2095,15 @@ private static void validateOperationValue(@Nullable final Path path,
    *
    * When this property is enabled and the above patch request is applied, the
    * following JSON will be appended to the {@code emails} of the user
-   * resource:
+   * resource, regardless of the current contents of the user:
    * <pre>
    *   {
    *     "type": "work",
    *     "display": "apollo.j@example.com"
    *   }
    * </pre>
-   * Note that this value is added regardless of the current state of the
-   * resource, so enabling this property for PATCH requests has the potential
-   * to result in multiple emails containing a {@code type} of {@code work}.
+   * Thus, enabling this property for PATCH requests has the potential to result
+   * in multiple emails containing a {@code type} of {@code work}.
    * <br><br>
    *
    * If this property is <em>disabled</em>, then in the above example, the
@@ -2094,5 +2114,5 @@ private static void validateOperationValue(@Nullable final Path path,
    *
    * @since 3.2.0
    */
-  public static boolean APPEND_NEW_PATCH_VALUES_PROPERTY = true;
+  public static boolean APPEND_NEW_PATCH_VALUES_PROPERTY = false;
 }

scim2-sdk-common/src/test/java/com/unboundid/scim2/common/AddOperationValueFilterTestCase.java

@@ -49,7 +49,11 @@
  *     "value": "sissel@example.com"
  *   }
  * </pre>
+ *
+ * For more background on this type of patch operation, see the Javadoc for
+ * {@link PatchOperation.AddOperation#applyAddWithValueFilter}.
  */
+@SuppressWarnings("JavadocReference")
 public class AddOperationValueFilterTestCase
 {
   /**
@@ -58,7 +62,7 @@ public class AddOperationValueFilterTestCase
   @AfterMethod
   public void tearDown()
   {
-    PatchOperation.APPEND_NEW_PATCH_VALUES_PROPERTY = true;
+    PatchOperation.APPEND_NEW_PATCH_VALUES_PROPERTY = false;
   }
 
   /**
@@ -107,9 +111,6 @@ public void testBasic() throws Exception
     PatchRequest request;
     UserResource resource = new UserResource();
 
-    // Unset the property to use the new behavior.
-    PatchOperation.APPEND_NEW_PATCH_VALUES_PROPERTY = false;
-
     // Add a work email to a list of existing emails.
     resource.setEmails(
         new Email().setValue("existing@example.com").setType("home"),

scim2-sdk-server/pom.xml

@@ -19,7 +19,7 @@
   <parent>
     <artifactId>scim2-parent</artifactId>
     <groupId>com.unboundid.product.scim2</groupId>
-    <version>3.2.1-SNAPSHOT</version>
+    <version>4.0.0-SNAPSHOT</version>
   </parent>
   <artifactId>scim2-sdk-server</artifactId>
   <packaging>jar</packaging>

scim2-ubid-extensions/pom.xml

@@ -19,7 +19,7 @@
   <parent>
       <artifactId>scim2-parent</artifactId>
       <groupId>com.unboundid.product.scim2</groupId>
-      <version>3.2.1-SNAPSHOT</version>
+      <version>4.0.0-SNAPSHOT</version>
   </parent>
   <artifactId>scim2-ubid-extensions</artifactId>
   <packaging>jar</packaging>