Create separate operation-specific configs for the object-persistence Scan and Query operations (#3383)

Author: ashovlin

sdk/src/Services/DynamoDBv2/Custom/DataModel/ContextInternal.cs

@@ -331,7 +331,9 @@ private static bool ShouldSave(DynamoDBEntry entry, bool ignoreNullValues)
             throw new InvalidOperationException("Unrecognized DynamoDBEntry object");
         }
 
-        // Deserializing DynamoDB document into an object
+        /// <summary>
+        /// Deserializes a DynamoDB document to an object
+        /// </summary>
         private T DocumentToObject<T>(ItemStorage storage, DynamoDBFlatConfig flatConfig)
         {
             Type type = typeof(T);
@@ -392,7 +394,9 @@ private void PopulateInstance(ItemStorage storage, object instance, DynamoDBFlat
             }
         }
 
-        // Serializing an object into a DynamoDB document
+        /// <summary>
+        /// Serializes an object into a DynamoDB document
+        /// </summary>
         private ItemStorage ObjectToItemStorage<T>(T toStore, bool keysOnly, DynamoDBFlatConfig flatConfig)
         {
             if (toStore == null) return null;
@@ -769,8 +773,10 @@ private static bool IsSupportedDictionaryType(Type type, out Type keyType, out T
             return true;
         }
 
-        // Deserializes a given Document to instance of targetType
-        // Use only for property conversions, not for full item conversion
+        /// <summary>
+        /// Deserializes a given Document to instance of targetType
+        /// Use only for property conversions, not for full item conversion
+        /// </summary>
         private object DeserializeFromDocument(Document document, Type targetType, DynamoDBFlatConfig flatConfig)
         {
             ItemStorageConfig storageConfig = StorageConfigCache.GetConfig(targetType, flatConfig, conversionOnly: true);
@@ -779,8 +785,11 @@ private object DeserializeFromDocument(Document document, Type targetType, Dynam
             object value = DocumentToObject(targetType, storage, flatConfig);
             return value;
         }
-        // Serializes a given value to Document
-        // Use only for property conversions, not for full item conversion
+
+        /// <summary>
+        /// Serializes a given value to Document
+        /// Use only for property conversions, not for full item conversion
+        /// </summary>
         private Document SerializeToDocument(object value, Type type, DynamoDBFlatConfig flatConfig)
         {
             ItemStorageConfig config = StorageConfigCache.GetConfig(type, flatConfig, conversionOnly: true);
@@ -789,7 +798,9 @@ private Document SerializeToDocument(object value, Type type, DynamoDBFlatConfig
             return doc;
         }
 
-        // Get/Set object properties
+        /// <summary>
+        /// Get/Set object properties
+        /// </summary>
         private static bool TrySetValue(object instance, MemberInfo member, object value)
         {
             FieldInfo fieldInfo = member as FieldInfo;
@@ -832,7 +843,9 @@ private static bool TryGetValue(object instance, MemberInfo member, out object v
             }
         }
 
-        // Query/Scan building
+        /// <summary>
+        /// Query/Scan building
+        /// </summary>
         private ScanFilter ComposeScanFilter(IEnumerable<ScanCondition> conditions, ItemStorageConfig storageConfig, DynamoDBFlatConfig flatConfig)
         {
             ScanFilter filter = new ScanFilter();

sdk/src/Services/DynamoDBv2/Custom/DataModel/QueryConfig.cs

@@ -0,0 +1,104 @@
+/*
+ * 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.
+ */
+
+using Amazon.DynamoDBv2.DocumentModel;
+using System;
+using System.Collections.Generic;
+
+namespace Amazon.DynamoDBv2.DataModel
+{
+    /// <summary>
+    /// Input for the Query operation in the object-persistence programming model
+    /// </summary>
+#if NET8_0_OR_GREATER
+    // The DataModel namespace doesn't support trimming yet, so annotate public classes/methods as incompatible
+    [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode(Custom.Internal.InternalConstants.RequiresUnreferencedCodeMessage)]
+#endif
+    public class QueryConfig : BaseOperationConfig
+    {
+        /// <summary>
+        /// Indicates whether a query should traverse the index backwards in descending order by range key value.
+        /// If the property is false (or not set), traversal shall be in ascending order.
+        /// </summary>
+        public bool? BackwardQuery { get; set; }
+
+        /// <summary>
+        /// Indicates the name of the index to query against.
+        /// This value is optional if the index name can be inferred from the call.
+        /// </summary>
+        public string IndexName { get; set; }
+
+        /// <summary>
+        /// The logical operator to apply to the filter conditions.
+        /// </summary>
+        /// <remarks>
+        /// <list type="bullet">
+        ///     <item>
+        ///         <term><see cref="ConditionalOperatorValues.And" /></term>
+        ///         <definition>If all of the conditions evaluate to true, then the entire filter evaluates to true.</definition>
+        ///     </item>
+        ///     <item>
+        ///         <term><see cref="ConditionalOperatorValues.Or" /></term>
+        ///         <definition>If at least one of the conditions evaluate to true, then the entire filter evaluates to true.</definition>
+        ///     </item>
+        /// </list>
+        /// The default value is <see cref="ConditionalOperatorValues.And" />.
+        /// </remarks>
+        public ConditionalOperatorValues ConditionalOperator { get; set; }
+
+        /// <summary>
+        /// Query filter for the Query operation. Evaluates the query results and returns only
+        /// the matching values. If you specify more than one condition, then by default all of the
+        /// conditions must evaluate to true. To match only some conditions, set <see cref="ConditionalOperator"/> to <see cref="ConditionalOperatorValues.Or" />.
+        /// </summary>
+        /// <remarks>
+        /// Note: Conditions must be against non-key properties.
+        /// </remarks>
+        public List<ScanCondition> QueryFilter { get; set; }
+
+        /// <summary>
+        /// Property that directs <see cref="DynamoDBContext" /> to use consistent reads.
+        /// If property is not set, behavior defaults to non-consistent reads.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the <see href="https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html">
+        /// Read Consistency</see> topic in the DynamoDB Developer Guide for more information.
+        /// </remarks>
+        public bool? ConsistentRead { get; set; }
+
+        /// <summary>
+        /// If true, all <see cref="DateTime"/> properties are retrieved in UTC timezone while reading data from DynamoDB. Else, the local timezone is used.
+        /// </summary>
+        /// <remarks>
+        /// This setting is only applicable to the high-level library. Service calls made via 
+        /// <see cref="AmazonDynamoDBClient"/> will always return <see cref="DateTime"/> attributes in UTC.
+        /// </remarks>
+        public bool? RetrieveDateTimeInUtc { get; set; }
+
+        /// <inheritdoc/>
+        internal override DynamoDBOperationConfig ToDynamoDBOperationConfig()
+        {
+            var config = base.ToDynamoDBOperationConfig();
+            config.BackwardQuery = BackwardQuery;
+            config.IndexName = IndexName;
+            config.ConditionalOperator = ConditionalOperator;
+            config.QueryFilter = QueryFilter;
+            config.ConsistentRead = ConsistentRead;
+            config.RetrieveDateTimeInUtc = RetrieveDateTimeInUtc;
+
+            return config;
+        }
+    }
+}

sdk/src/Services/DynamoDBv2/Custom/DataModel/ScanConfig.cs

@@ -0,0 +1,97 @@
+/*
+ * 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.
+ */
+
+using Amazon.DynamoDBv2.DocumentModel;
+using System;
+using System.Collections.Generic;
+
+namespace Amazon.DynamoDBv2.DataModel
+{
+    /// <summary>
+    /// Input for the Scan operation in the object-persistence programming model
+    /// </summary>
+#if NET8_0_OR_GREATER
+    // The DataModel namespace doesn't support trimming yet, so annotate public classes/methods as incompatible
+    [System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode(Custom.Internal.InternalConstants.RequiresUnreferencedCodeMessage)]
+#endif
+    public class ScanConfig : BaseOperationConfig
+    {
+        /// <summary>
+        /// Indicates the name of the index to scan against.
+        /// This value is optional if the index name can be inferred from the call.
+        /// </summary>
+        public string IndexName { get; set; }
+
+        /// <summary>
+        /// The logical operator to apply to the filter conditions.
+        /// </summary>
+        /// <remarks>
+        /// <list type="bullet">
+        ///     <item>
+        ///         <term><see cref="ConditionalOperatorValues.And" /></term>
+        ///         <definition>If all of the conditions evaluate to true, then the entire filter evaluates to true.</definition>
+        ///     </item>
+        ///     <item>
+        ///         <term><see cref="ConditionalOperatorValues.Or" /></term>
+        ///         <definition>If at least one of the conditions evaluate to true, then the entire filter evaluates to true.</definition>
+        ///     </item>
+        /// </list>
+        /// The default value is <see cref="ConditionalOperatorValues.And" />.
+        /// </remarks>
+        public ConditionalOperatorValues ConditionalOperator { get; set; }
+
+        /// <summary>
+        /// Filter for the Scan operation. Evaluates the query results and returns only
+        /// the matching values. If you specify more than one condition, then by default all of the
+        /// conditions must evaluate to true. To match only some conditions, set <see cref="ConditionalOperator"/> to <see cref="ConditionalOperatorValues.Or" />.
+        /// </summary>
+        /// <remarks>
+        /// Note: Conditions must be against non-key properties.
+        /// </remarks>
+        public List<ScanCondition> QueryFilter { get; set; }
+
+        /// <summary>
+        /// Property that directs <see cref="DynamoDBContext" /> to use consistent reads.
+        /// If property is not set, behavior defaults to non-consistent reads.
+        /// </summary>
+        /// <remarks>
+        /// Refer to the <see href="https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html">
+        /// Read Consistency</see> topic in the DynamoDB Developer Guide for more information.
+        /// </remarks>
+        public bool? ConsistentRead { get; set; }
+
+        /// <summary>
+        /// If true, all <see cref="DateTime"/> properties are retrieved in UTC timezone while reading data from DynamoDB. Else, the local timezone is used.
+        /// </summary>
+        /// <remarks>
+        /// This setting is only applicable to the high-level library. Service calls made via 
+        /// <see cref="AmazonDynamoDBClient"/> will always return <see cref="DateTime"/> attributes in UTC.
+        /// </remarks>
+        public bool? RetrieveDateTimeInUtc { get; set; }
+
+        /// <inheritdoc/>
+        internal override DynamoDBOperationConfig ToDynamoDBOperationConfig()
+        {
+            var config = base.ToDynamoDBOperationConfig();
+            config.IndexName = IndexName;
+            config.ConditionalOperator = ConditionalOperator;
+            config.QueryFilter = QueryFilter;
+            config.ConsistentRead = ConsistentRead;
+            config.RetrieveDateTimeInUtc = RetrieveDateTimeInUtc;
+
+            return config;
+        }
+    }
+}