Skip to content

Commit e11b6e5

Browse files
committed
Separate DynamoDBContextConfig and DynamoDBOperationConfig, clean up documentation
1 parent 1c1d7b5 commit e11b6e5

File tree

1 file changed

+133
-37
lines changed
  • sdk/src/Services/DynamoDBv2/Custom/DataModel

1 file changed

+133
-37
lines changed

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

+133-37
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,10 @@
1313
* permissions and limitations under the License.
1414
*/
1515

16-
using System;
17-
using System.Collections.Generic;
18-
1916
using Amazon.DynamoDBv2.DocumentModel;
20-
using Amazon.DynamoDBv2.Model;
21-
using System.Globalization;
2217
using Amazon.Util;
18+
using System;
19+
using System.Collections.Generic;
2320

2421
namespace Amazon.DynamoDBv2.DataModel
2522
{
@@ -69,30 +66,24 @@ public DynamoDBContextConfig()
6966
}
7067

7168
/// <summary>
72-
/// Property that directs DynamoDBContext to use consistent reads.
69+
/// Property that directs <see cref="DynamoDBContext"/> to use consistent reads.
7370
/// If property is not set, behavior defaults to non-consistent reads.
7471
/// </summary>
72+
/// <remarks>
73+
/// Refer to the <see href="https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html">
74+
/// Read Consistency</see> topic in the DynamoDB Developer Guide for more information.
75+
/// </remarks>
7576
public bool? ConsistentRead { get; set; }
7677

7778
/// <summary>
78-
/// Property that directs DynamoDBContext to skip version checks
79+
/// Property that directs <see cref="DynamoDBContext"/> to skip version checks
7980
/// when saving or deleting an object with a version attribute.
8081
/// If property is not set, version checks are performed.
8182
/// </summary>
8283
public bool? SkipVersionCheck { get; set; }
8384

8485
/// <summary>
85-
/// Indicates which DynamoDB table to use. This overrides the table specified
86-
/// by the <see cref="DynamoDBTableAttribute"/> on the .NET objects that you're saving or loading.
87-
/// </summary>
88-
/// <remarks>
89-
/// If you specify this on <see cref="DynamoDBContextConfig"/>, then it will apply to all
90-
/// objects/tables used with that <see cref="DynamoDBContext"/> object unless overriden by an operation-specific config.
91-
/// </remarks>
92-
public string OverrideTableName { get; set; }
93-
94-
/// <summary>
95-
/// Property that directs DynamoDBContext to prefix all table names
86+
/// Property that directs <see cref="DynamoDBContext"/> to prefix all table names
9687
/// with a specific string.
9788
/// If property is null or empty, no prefix is used and default
9889
/// table names are used.
@@ -112,15 +103,15 @@ public DynamoDBContextConfig()
112103
public MetadataCachingMode? MetadataCachingMode { get; set; }
113104

114105
/// <summary>
115-
/// Property that directs DynamoDBContext to ignore null values
106+
/// Property that directs <see cref="DynamoDBContext"/> to ignore null values
116107
/// on attributes during a Save operation.
117108
/// If the property is false (or not set), null values will be
118109
/// interpreted as directives to delete the specific attribute.
119110
/// </summary>
120111
public bool? IgnoreNullValues { get; set; }
121112

122113
/// <summary>
123-
/// Property that directs DynamoDBContext to enable empty string values
114+
/// Property that directs <see cref="DynamoDBContext"/> to enable empty string values
124115
/// on attributes during a Save operation.
125116
/// If the property is false (or not set), empty string values will be
126117
/// interpreted as null values.
@@ -148,7 +139,9 @@ public DynamoDBContextConfig()
148139
/// <summary>
149140
/// If true, all <see cref="DateTime"/> properties are retrieved in UTC timezone while reading data from DynamoDB. Else, the local timezone is used.
150141
/// </summary>
151-
/// <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>
142+
/// <remarks>This setting is only applicable to the high-level library.
143+
/// Service calls made via <see cref="AmazonDynamoDBClient"/> will always return
144+
/// <see cref="DateTime"/> attributes in UTC.</remarks>
152145
public bool? RetrieveDateTimeInUtc { get; set; }
153146
}
154147

@@ -160,11 +153,101 @@ public DynamoDBContextConfig()
160153
#if NET8_0_OR_GREATER
161154
[System.Diagnostics.CodeAnalysis.RequiresUnreferencedCode(Amazon.DynamoDBv2.Custom.Internal.InternalConstants.RequiresUnreferencedCodeMessage)]
162155
#endif
163-
public class DynamoDBOperationConfig : DynamoDBContextConfig
156+
public class DynamoDBOperationConfig
164157
{
165158
/// <summary>
166-
/// Property that indicates a query should traverse the index backward.
167-
/// If the property is false (or not set), traversal shall be forward.
159+
/// Property that directs <see cref="DynamoDBContext"/> to use consistent reads.
160+
/// If property is not set, behavior defaults to non-consistent reads.
161+
/// </summary>
162+
/// <remarks>
163+
/// Refer to the <see href="https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html">
164+
/// Read Consistency</see> topic in the DynamoDB Developer Guide for more information.
165+
/// </remarks>
166+
public bool? ConsistentRead { get; set; }
167+
168+
/// <summary>
169+
/// Property that directs <see cref="DynamoDBContext"/> to skip version checks
170+
/// when saving or deleting an object with a version attribute.
171+
/// If property is not set, version checks are performed.
172+
/// </summary>
173+
public bool? SkipVersionCheck { get; set; }
174+
175+
/// <summary>
176+
/// Indicates which DynamoDB table to use. This overrides the table specified
177+
/// by the <see cref="DynamoDBTableAttribute"/> on the .NET objects that you're saving or loading.
178+
/// </summary>
179+
/// <remarks>
180+
/// If you want to specify this globally instead of for each operation, you can use
181+
/// the <see cref="TableAlias"/> or <see cref="TypeMapping"/> collections
182+
/// on <see cref="AWSConfigsDynamoDB.Context"/>.
183+
/// </remarks>
184+
public string OverrideTableName { get; set; }
185+
186+
/// <summary>
187+
/// Property that directs <see cref="DynamoDBContext"/> to prefix all table names
188+
/// with a specific string.
189+
/// If property is null or empty, no prefix is used and default
190+
/// table names are used.
191+
/// </summary>
192+
public string TableNamePrefix { get; set; }
193+
194+
/// <summary>
195+
/// The object persistence model API relies on an internal cache of the DynamoDB table's metadata to construct and validate
196+
/// requests. This controls how the cache key is derived, which influences when the SDK will call
197+
/// IAmazonDynamoDB.DescribeTable(string) internally to populate the cache.
198+
/// </summary>
199+
/// <remarks>
200+
/// For <see cref="MetadataCachingMode.Default"/> the cache key will be a combination of the table name, credentials, region and service URL.
201+
/// For <see cref="MetadataCachingMode.TableNameOnly"/> the cache key will only consist of the table name. This reduces cache misses in contexts
202+
/// where you are accessing tables with identical structure but using different credentials or endpoints (such as a multi-tenant application).
203+
/// </remarks>
204+
public MetadataCachingMode? MetadataCachingMode { get; set; }
205+
206+
/// <summary>
207+
/// Property that directs <see cref="DynamoDBContext"/> to ignore null values
208+
/// on attributes during a Save operation.
209+
/// If the property is false (or not set), null values will be
210+
/// interpreted as directives to delete the specific attribute.
211+
/// </summary>
212+
public bool? IgnoreNullValues { get; set; }
213+
214+
/// <summary>
215+
/// Property that directs <see cref="DynamoDBContext"/> to enable empty string values
216+
/// on attributes during a Save operation.
217+
/// If the property is false (or not set), empty string values will be
218+
/// interpreted as null values.
219+
/// </summary>
220+
public bool? IsEmptyStringValueEnabled { get; set; }
221+
222+
/// <summary>
223+
/// Conversion specification which controls how conversion between
224+
/// .NET and DynamoDB types happens.
225+
/// </summary>
226+
public DynamoDBEntryConversion Conversion { get; set; }
227+
228+
/// <summary>
229+
/// If true disables fetching table metadata automatically from DynamoDB. Table metadata must be
230+
/// defined by <see cref="DynamoDBAttribute"/> attributes and/or in <see cref = "AWSConfigsDynamoDB"/>.
231+
/// </summary>
232+
/// <remarks>
233+
/// Setting this to true can avoid latency and thread starvation due to blocking asynchronous
234+
/// IAmazonDynamoDB.DescribeTable(string) calls that are used to populate the SDK's cache of
235+
/// table metadata. It requires that the table's index schema be accurately described via the above methods,
236+
/// otherwise exceptions may be thrown and/or the results of certain DynamoDB operations may change.
237+
/// </remarks>
238+
public bool? DisableFetchingTableMetadata { get; set; }
239+
240+
/// <summary>
241+
/// If true, all <see cref="DateTime"/> properties are retrieved in UTC timezone while reading data from DynamoDB. Else, the local timezone is used.
242+
/// </summary>
243+
/// <remarks>This setting is only applicable to the high-level library.
244+
/// Service calls made via <see cref="AmazonDynamoDBClient"/> will always return
245+
/// <see cref="DateTime"/> attributes in UTC.</remarks>
246+
public bool? RetrieveDateTimeInUtc { get; set; }
247+
248+
/// <summary>
249+
/// Indicates whether a query should traverse the index backwards in descending order by range key value.
250+
/// If the property is false (or not set), traversal shall be in ascending order.
168251
/// </summary>
169252
public bool? BackwardQuery { get; set; }
170253

@@ -175,20 +258,31 @@ public class DynamoDBOperationConfig : DynamoDBContextConfig
175258
public string IndexName { get; set; }
176259

177260
/// <summary>
178-
/// A logical operator to apply to the filter conditions:
179-
/// AND - If all of the conditions evaluate to true, then the entire filter evaluates to true.
180-
/// OR - If at least one of the conditions evaluate to true, then the entire filter evaluates to true.
181-
///
182-
/// Default value is AND.
261+
/// The logical operator to apply to the filter conditions.
183262
/// </summary>
263+
/// <remarks>
264+
/// <list type="bullet">
265+
/// <item>
266+
/// <term><see cref="ConditionalOperatorValues.And" /></term>
267+
/// <definition>If all of the conditions evaluate to true, then the entire filter evaluates to true.</definition>
268+
/// </item>
269+
/// <item>
270+
/// <term><see cref="ConditionalOperatorValues.Or" /></term>
271+
/// <definition>If at least one of the conditions evaluate to true, then the entire filter evaluates to true.</definition>
272+
/// </item>
273+
/// </list>
274+
/// The default value is <see cref="ConditionalOperatorValues.And" />.
275+
/// </remarks>
184276
public ConditionalOperatorValues ConditionalOperator { get; set; }
185277

186278
/// <summary>
187-
/// Query filter for the Query operation operation. Evaluates the query results and returns only
279+
/// Query filter for the Query operation. Evaluates the query results and returns only
188280
/// the matching values. If you specify more than one condition, then by default all of the
189-
/// conditions must evaluate to true. To match only some conditions, set ConditionalOperator to Or.
190-
/// Note: Conditions must be against non-key properties.
281+
/// conditions must evaluate to true. To match only some conditions, set <see cref="ConditionalOperator"/> to <see cref="ConditionalOperatorValues.Or" />.
191282
/// </summary>
283+
/// <remarks>
284+
/// Note: Conditions must be against non-key properties.
285+
/// </remarks>
192286
public List<ScanCondition> QueryFilter { get; set; }
193287

194288
/// <summary>
@@ -199,7 +293,9 @@ public DynamoDBOperationConfig()
199293
QueryFilter = new List<ScanCondition>();
200294
}
201295

202-
// Checks if the IndexName is set on the config
296+
/// <summary>
297+
/// Checks if the IndexName is set on the config
298+
/// </summary>
203299
internal bool IsIndexOperation { get { return !string.IsNullOrEmpty(IndexName); } }
204300
}
205301

@@ -360,14 +456,14 @@ public DynamoDBFlatConfig(DynamoDBOperationConfig operationConfig, DynamoDBConte
360456
DynamoDBEntryConversion conversion = operationConfig.Conversion ?? contextConfig.Conversion ?? DynamoDBEntryConversion.CurrentConversion;
361457
MetadataCachingMode metadataCachingMode = operationConfig.MetadataCachingMode ?? contextConfig.MetadataCachingMode ?? DynamoDBv2.MetadataCachingMode.Default;
362458

363-
string overrideTableName =
364-
!string.IsNullOrEmpty(operationConfig.OverrideTableName) ? operationConfig.OverrideTableName :
365-
!string.IsNullOrEmpty(contextConfig.OverrideTableName) ? contextConfig.OverrideTableName : string.Empty;
366459
string tableNamePrefix =
367460
!string.IsNullOrEmpty(operationConfig.TableNamePrefix) ? operationConfig.TableNamePrefix :
368461
!string.IsNullOrEmpty(contextConfig.TableNamePrefix) ? contextConfig.TableNamePrefix : string.Empty;
369462

370-
// These properties can only be set at the operation level, and are related to querying or scanning
463+
// These properties can only be set at the operation level, most are related to querying or scanning.
464+
// We don't support overriding the table name at the context level, since a context object can be used with multiple tables.
465+
string overrideTableName =
466+
!string.IsNullOrEmpty(operationConfig.OverrideTableName) ? operationConfig.OverrideTableName : string.Empty;
371467
bool backwardQuery = operationConfig.BackwardQuery ?? false;
372468
string indexName =
373469
!string.IsNullOrEmpty(operationConfig.IndexName) ? operationConfig.IndexName : DefaultIndexName;

0 commit comments

Comments
 (0)