DynamoDb Enhanced Client : changed the way extensions are loaded, loads VersionedRecordExtension by default

Author: bmaizels

services-custom/dynamodb-enhanced/README.md

@@ -250,18 +250,32 @@ key differences:
 
 ### Using extensions
 The mapper supports plugin extensions to provide enhanced functionality
-beyond the simple primitive mapped operations. Only one extension can be
-loaded into a DynamoDbEnhancedClient. Any number of extensions can be chained
-together in a specific order into a single extension using a
-ChainExtension. Extensions have two hooks, beforeWrite() and
+beyond the simple primitive mapped operations. Extensions have two hooks, beforeWrite() and
 afterRead(); the former can modify a write operation before it happens,
 and the latter can modify the results of a read operation after it
 happens. Some operations such as UpdateItem perform both a write and
 then a read, so call both hooks.
 
+Extensions are loaded in the order they are specified in the enhanced client builder. This load order can be important,
+as one extension can be acting on values that have been transformed by a previous extension. By default, just the
+VersionedRecordExtension will be loaded, however you can override this behavior on the client builder and load any
+extensions you like or specify none if you do not want the default bundled VersionedRecordExtension.
+
+In this example, a custom extension named 'verifyChecksumExtension' is being loaded after the VersionedRecordExtension
+which is usually loaded by default by itself:
+```java
+DynamoDbEnhancedClientExtension versionedRecordExtension = VersionedRecordExtension.builder().build();
+
+DynamoDbEnhancedClient enhancedClient = 
+    DynamoDbEnhancedClient.builder()
+                          .dynamoDbClient(dynamoDbClient)
+                          .extensions(versionedRecordExtension, verifyChecksumExtension)
+                          .build();
+```
+
 #### VersionedRecordExtension
 
-This extension will increment and track a record version number as
+This extension is loaded by default and will increment and track a record version number as
 records are written to the database. A condition will be added to every
 write that will cause the write to fail if the record version number of
 the actual persisted record does not match the value that the
@@ -270,14 +284,6 @@ record updates, if another process updates a record between the time the
 first process has read the record and is writing an update to it then
 that write will fail. 
 
-To load the extension:
-```java
-DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
-                        .dynamoDbClient(dynamoDbClient)
-                        .extendWith(VersionedRecordExtension.builder().build())
-                        .build();
-```
-
 To tell the extension which attribute to use to track the record version
 number tag a numeric attribute in the TableSchema:
 ```java

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedAsyncClient.java

@@ -35,7 +35,7 @@
  * Asynchronous interface for running commands against a DynamoDb database.
  */
 @SdkPublicApi
-public interface DynamoDbEnhancedAsyncClient {
+public interface DynamoDbEnhancedAsyncClient extends DynamoDbEnhancedResource {
 
     /**
      * Returns a mapped table that can be used to execute commands that work with mapped items against that table.
@@ -90,11 +90,23 @@ static DynamoDbEnhancedAsyncClient.Builder builder() {
     /**
      * The builder definition for a {@link DynamoDbEnhancedAsyncClient}.
      */
-    interface Builder {
-        Builder dynamoDbClient(DynamoDbAsyncClient dynamoDbAsyncClient);
-
-        Builder extendWith(DynamoDbEnhancedClientExtension dynamoDbEnhancedClientExtension);
-
+    interface Builder extends DynamoDbEnhancedResource.Builder {
+        /**
+         * The regular low-level SDK client to use with the enhanced client.
+         * @param dynamoDbClient an initialized {@link DynamoDbAsyncClient}
+         */
+        Builder dynamoDbClient(DynamoDbAsyncClient dynamoDbClient);
+
+        @Override
+        Builder extensions(DynamoDbEnhancedClientExtension... dynamoDbEnhancedClientExtensions);
+
+        @Override
+        Builder extensions(List<DynamoDbEnhancedClientExtension> dynamoDbEnhancedClientExtensions);
+
+        /**
+         * Builds an enhanced client based on the settings supplied to this builder
+         * @return An initialized {@link DynamoDbEnhancedAsyncClient}
+         */
         DynamoDbEnhancedAsyncClient build();
     }
 }

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClient.java

@@ -34,7 +34,7 @@
  * Synchronous interface for running commands against a DynamoDb database.
  */
 @SdkPublicApi
-public interface DynamoDbEnhancedClient {
+public interface DynamoDbEnhancedClient extends DynamoDbEnhancedResource {
 
     /**
      * Returns a mapped table that can be used to execute commands that work with mapped items against that table.
@@ -88,11 +88,23 @@ static Builder builder() {
     /**
      * The builder definition for a {@link DynamoDbEnhancedClient}.
      */
-    interface Builder {
+    interface Builder extends DynamoDbEnhancedResource.Builder {
+        /**
+         * The regular low-level SDK client to use with the enhanced client.
+         * @param dynamoDbClient an initialized {@link DynamoDbClient}
+         */
         Builder dynamoDbClient(DynamoDbClient dynamoDbClient);
 
-        Builder extendWith(DynamoDbEnhancedClientExtension dynamoDbEnhancedClientExtension);
+        @Override
+        Builder extensions(DynamoDbEnhancedClientExtension... dynamoDbEnhancedClientExtensions);
 
+        @Override
+        Builder extensions(List<DynamoDbEnhancedClientExtension> dynamoDbEnhancedClientExtensions);
+
+        /**
+         * Builds an enhanced client based on the settings supplied to this builder
+         * @return An initialized {@link DynamoDbEnhancedClient}
+         */
         DynamoDbEnhancedClient build();
     }
 }

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedClientExtension.java

@@ -18,7 +18,6 @@
 import java.util.Map;
 
 import software.amazon.awssdk.annotations.SdkPublicApi;
-import software.amazon.awssdk.enhanced.dynamodb.extensions.ChainExtension;
 import software.amazon.awssdk.enhanced.dynamodb.extensions.ReadModification;
 import software.amazon.awssdk.enhanced.dynamodb.extensions.WriteModification;
 import software.amazon.awssdk.enhanced.dynamodb.internal.operations.OperationContext;
@@ -29,9 +28,9 @@
  * is written to the database, and one called just after a record is read from the database. This gives the extension the
  * opportunity to act as an invisible layer between the application and the database and transform the data accordingly.
  * <p>
- * Only one extension can be loaded with an enhanced client. In order to combine multiple extensions, the
- * {@link ChainExtension} should be used and initialized with all the component extensions to combine together
- * into a chain.
+ * Multiple extensions can be used with the enhanced client, but the order in which they are loaded is important. For
+ * instance one extension may overwrite the value of an attribute that another extension then includes in a checksum
+ * calculation.
  */
 @SdkPublicApi
 public interface DynamoDbEnhancedClientExtension {

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/DynamoDbEnhancedResource.java

@@ -0,0 +1,55 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License").
+ * You may not use this file except in compliance with the License.
+ * A copy of the License is located at
+ *
+ *  http://aws.amazon.com/apache2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed
+ * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
+ * express or implied. See the License for the specific language governing
+ * permissions and limitations under the License.
+ */
+
+package software.amazon.awssdk.enhanced.dynamodb;
+
+import java.util.List;
+
+import software.amazon.awssdk.annotations.SdkPublicApi;
+
+/**
+ * Shared interface components for {@link DynamoDbEnhancedClient} and {@link DynamoDbEnhancedAsyncClient}. Any common
+ * methods implemented by both of those classes or their builders are declared here.
+ */
+@SdkPublicApi
+public interface DynamoDbEnhancedResource {
+    /**
+     * Shared interface components for the builders of {@link DynamoDbEnhancedClient} and
+     * {@link DynamoDbEnhancedAsyncClient}
+     */
+    interface Builder {
+        /**
+         * Specifies the extensions to load with the enhanced client. The extensions will be loaded in the strict order
+         * they are supplied here. Calling this method will override any bundled extensions that are loaded by default,
+         * namely the {@link software.amazon.awssdk.enhanced.dynamodb.extensions.VersionedRecordExtension}, so this
+         * extension must be included in the supplied list otherwise it will not be loaded. Providing an empty list here
+         * will cause no extensions to get loaded, effectively dropping the default ones.
+         *
+         * @param dynamoDbEnhancedClientExtensions a list of extensions to load with the enhanced client
+         */
+        Builder extensions(DynamoDbEnhancedClientExtension... dynamoDbEnhancedClientExtensions);
+
+        /**
+         * Specifies the extensions to load with the enhanced client. The extensions will be loaded in the strict order
+         * they are supplied here. Calling this method will override any bundled extensions that are loaded by default,
+         * namely the {@link software.amazon.awssdk.enhanced.dynamodb.extensions.VersionedRecordExtension}, so this
+         * extension must be included in the supplied list otherwise it will not be loaded. Providing an empty list here
+         * will cause no extensions to get loaded, effectively dropping the default ones.
+         *
+         * @param dynamoDbEnhancedClientExtensions a list of extensions to load with the enhanced client
+         */
+        Builder extensions(List<DynamoDbEnhancedClientExtension> dynamoDbEnhancedClientExtensions);
+    }
+}

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/extensions/annotations/DynamoDbVersionAttribute.java

@@ -21,7 +21,7 @@
 import java.lang.annotation.Target;
 
 import software.amazon.awssdk.annotations.SdkPublicApi;
-import software.amazon.awssdk.enhanced.dynamodb.internal.extensions.VersionedRecordExtensionAttributeTags;
+import software.amazon.awssdk.enhanced.dynamodb.internal.extensions.VersionRecordAttributeTags;
 import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.BeanTableSchemaAttributeTag;
 
 /**
@@ -32,6 +32,6 @@
 @SdkPublicApi
 @Target({ElementType.METHOD})
 @Retention(RetentionPolicy.RUNTIME)
-@BeanTableSchemaAttributeTag(VersionedRecordExtensionAttributeTags.class)
+@BeanTableSchemaAttributeTag(VersionRecordAttributeTags.class)
 public @interface DynamoDbVersionAttribute {
 }

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/client/DefaultDynamoDbEnhancedAsyncClient.java

@@ -15,6 +15,8 @@
 
 package software.amazon.awssdk.enhanced.dynamodb.internal.client;
 
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.concurrent.CompletableFuture;
 import java.util.function.Consumer;
@@ -36,16 +38,18 @@
 import software.amazon.awssdk.enhanced.dynamodb.model.TransactGetResultPage;
 import software.amazon.awssdk.enhanced.dynamodb.model.TransactWriteItemsEnhancedRequest;
 import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
+import software.amazon.awssdk.utils.Validate;
 
 @SdkInternalApi
 public final class DefaultDynamoDbEnhancedAsyncClient implements DynamoDbEnhancedAsyncClient {
     private final DynamoDbAsyncClient dynamoDbClient;
     private final DynamoDbEnhancedClientExtension extension;
 
-    private DefaultDynamoDbEnhancedAsyncClient(DynamoDbAsyncClient dynamoDbClient,
-                                               DynamoDbEnhancedClientExtension extension) {
-        this.dynamoDbClient = dynamoDbClient;
-        this.extension = extension;
+    private DefaultDynamoDbEnhancedAsyncClient(Builder builder) {
+        this.dynamoDbClient = Validate.paramNotNull(builder.dynamoDbClient, "You must provide a DynamoDbClient to build " +
+            "a DefaultDynamoDbEnhancedAsyncClient.");
+
+        this.extension = ExtensionResolver.resolveExtensions(builder.dynamoDbEnhancedClientExtensions);
     }
 
     public static Builder builder() {
@@ -125,7 +129,7 @@ public DynamoDbEnhancedClientExtension mapperExtension() {
     }
 
     public Builder toBuilder() {
-        return builder().dynamoDbClient(this.dynamoDbClient).extendWith(this.extension);
+        return builder().dynamoDbClient(this.dynamoDbClient).extensions(this.extension);
     }
 
     @Override
@@ -156,33 +160,29 @@ public int hashCode() {
 
     public static final class Builder implements DynamoDbEnhancedAsyncClient.Builder {
         private DynamoDbAsyncClient dynamoDbClient;
-        private DynamoDbEnhancedClientExtension dynamoDbEnhancedClientExtension;
-
-        private Builder() {
-        }
+        private List<DynamoDbEnhancedClientExtension> dynamoDbEnhancedClientExtensions =
+            new ArrayList<>(ExtensionResolver.defaultExtensions());
 
+        @Override
         public DefaultDynamoDbEnhancedAsyncClient build() {
-            if (dynamoDbClient == null) {
-                throw new IllegalArgumentException("You must provide a DynamoDbClient to build a "
-                                                   + "DefaultDynamoDbEnhancedClient.");
-            }
-
-            return new DefaultDynamoDbEnhancedAsyncClient(dynamoDbClient, dynamoDbEnhancedClientExtension);
+            return new DefaultDynamoDbEnhancedAsyncClient(this);
         }
 
-        public Builder dynamoDbClient(DynamoDbAsyncClient dynamoDbAsyncClient) {
-            this.dynamoDbClient = dynamoDbAsyncClient;
+        @Override
+        public Builder dynamoDbClient(DynamoDbAsyncClient dynamoDbClient) {
+            this.dynamoDbClient = dynamoDbClient;
             return this;
         }
 
-        public Builder extendWith(DynamoDbEnhancedClientExtension dynamoDbEnhancedClientExtension) {
-            if (dynamoDbEnhancedClientExtension != null && this.dynamoDbEnhancedClientExtension != null) {
-                throw new IllegalArgumentException("You may only extend a DefaultDynamoDbEnhancedClient with a single "
-                                                   + "extension. To combine multiple extensions, use the "
-                                                   + "ChainMapperExtension.");
-            }
+        @Override
+        public Builder extensions(DynamoDbEnhancedClientExtension... dynamoDbEnhancedClientExtensions) {
+            this.dynamoDbEnhancedClientExtensions = Arrays.asList(dynamoDbEnhancedClientExtensions);
+            return this;
+        }
 
-            this.dynamoDbEnhancedClientExtension = dynamoDbEnhancedClientExtension;
+        @Override
+        public Builder extensions(List<DynamoDbEnhancedClientExtension> dynamoDbEnhancedClientExtensions) {
+            this.dynamoDbEnhancedClientExtensions = new ArrayList<>(dynamoDbEnhancedClientExtensions);
             return this;
         }
     }

services-custom/dynamodb-enhanced/src/main/java/software/amazon/awssdk/enhanced/dynamodb/internal/client/DefaultDynamoDbEnhancedClient.java

@@ -15,6 +15,8 @@
 
 package software.amazon.awssdk.enhanced.dynamodb.internal.client;
 
+import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.List;
 import java.util.function.Consumer;
 
@@ -35,16 +37,18 @@
 import software.amazon.awssdk.enhanced.dynamodb.model.TransactGetResultPage;
 import software.amazon.awssdk.enhanced.dynamodb.model.TransactWriteItemsEnhancedRequest;
 import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
+import software.amazon.awssdk.utils.Validate;
 
 @SdkInternalApi
 public final class DefaultDynamoDbEnhancedClient implements DynamoDbEnhancedClient {
     private final DynamoDbClient dynamoDbClient;
     private final DynamoDbEnhancedClientExtension extension;
 
-    private DefaultDynamoDbEnhancedClient(DynamoDbClient dynamoDbClient,
-                                          DynamoDbEnhancedClientExtension extension) {
-        this.dynamoDbClient = dynamoDbClient;
-        this.extension = extension;
+    private DefaultDynamoDbEnhancedClient(Builder builder) {
+        this.dynamoDbClient = Validate.paramNotNull(builder.dynamoDbClient, "You must provide a DynamoDbClient to build " +
+            "a DefaultDynamoDbEnhancedClient.");
+
+        this.extension = ExtensionResolver.resolveExtensions(builder.dynamoDbEnhancedClientExtensions);
     }
 
     public static Builder builder() {
@@ -119,7 +123,7 @@ public DynamoDbEnhancedClientExtension mapperExtension() {
     }
 
     public Builder toBuilder() {
-        return builder().dynamoDbClient(this.dynamoDbClient).extendWith(this.extension);
+        return builder().dynamoDbClient(this.dynamoDbClient).extensions(this.extension);
     }
 
     @Override
@@ -151,30 +155,29 @@ public int hashCode() {
 
     public static final class Builder implements DynamoDbEnhancedClient.Builder {
         private DynamoDbClient dynamoDbClient;
-        private DynamoDbEnhancedClientExtension dynamoDbEnhancedClientExtension;
+        private List<DynamoDbEnhancedClientExtension> dynamoDbEnhancedClientExtensions =
+            new ArrayList<>(ExtensionResolver.defaultExtensions());
 
+        @Override
         public DefaultDynamoDbEnhancedClient build() {
-            if (dynamoDbClient == null) {
-                throw new IllegalArgumentException("You must provide a DynamoDbClient to build a "
-                                                   + "DefaultDynamoDbEnhancedClient.");
-            }
-
-            return new DefaultDynamoDbEnhancedClient(dynamoDbClient, dynamoDbEnhancedClientExtension);
+            return new DefaultDynamoDbEnhancedClient(this);
         }
 
+        @Override
         public Builder dynamoDbClient(DynamoDbClient dynamoDbClient) {
             this.dynamoDbClient = dynamoDbClient;
             return this;
         }
 
-        public Builder extendWith(DynamoDbEnhancedClientExtension dynamoDbEnhancedClientExtension) {
-            if (dynamoDbEnhancedClientExtension != null && this.dynamoDbEnhancedClientExtension != null) {
-                throw new IllegalArgumentException("You may only extend a DefaultDynamoDbEnhancedClient with a single "
-                                                   + "extension. To combine multiple extensions, use the "
-                                                   + "ChainMapperExtension.");
-            }
+        @Override
+        public Builder extensions(DynamoDbEnhancedClientExtension... dynamoDbEnhancedClientExtensions) {
+            this.dynamoDbEnhancedClientExtensions = Arrays.asList(dynamoDbEnhancedClientExtensions);
+            return this;
+        }
 
-            this.dynamoDbEnhancedClientExtension = dynamoDbEnhancedClientExtension;
+        @Override
+        public Builder extensions(List<DynamoDbEnhancedClientExtension> dynamoDbEnhancedClientExtensions) {
+            this.dynamoDbEnhancedClientExtensions = new ArrayList<>(dynamoDbEnhancedClientExtensions);
             return this;
         }
     }