1 /*
2  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License").
5  * You may not use this file except in compliance with the License.
6  * A copy of the License is located at
7  *
8  *  http://aws.amazon.com/apache2.0
9  *
10  * or in the "license" file accompanying this file. This file is distributed
11  * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12  * express or implied. See the License for the specific language governing
13  * permissions and limitations under the License.
14  */
15 
16 package software.amazon.awssdk.enhanced.dynamodb;
17 
18 import java.util.function.Consumer;
19 import software.amazon.awssdk.annotations.SdkPublicApi;
20 import software.amazon.awssdk.annotations.ThreadSafe;
21 import software.amazon.awssdk.core.pagination.sync.SdkIterable;
22 import software.amazon.awssdk.enhanced.dynamodb.model.CreateTableEnhancedRequest;
23 import software.amazon.awssdk.enhanced.dynamodb.model.DeleteItemEnhancedRequest;
24 import software.amazon.awssdk.enhanced.dynamodb.model.DeleteItemEnhancedResponse;
25 import software.amazon.awssdk.enhanced.dynamodb.model.DescribeTableEnhancedResponse;
26 import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedRequest;
27 import software.amazon.awssdk.enhanced.dynamodb.model.GetItemEnhancedResponse;
28 import software.amazon.awssdk.enhanced.dynamodb.model.Page;
29 import software.amazon.awssdk.enhanced.dynamodb.model.PageIterable;
30 import software.amazon.awssdk.enhanced.dynamodb.model.PutItemEnhancedRequest;
31 import software.amazon.awssdk.enhanced.dynamodb.model.PutItemEnhancedResponse;
32 import software.amazon.awssdk.enhanced.dynamodb.model.QueryConditional;
33 import software.amazon.awssdk.enhanced.dynamodb.model.QueryEnhancedRequest;
34 import software.amazon.awssdk.enhanced.dynamodb.model.ScanEnhancedRequest;
35 import software.amazon.awssdk.enhanced.dynamodb.model.UpdateItemEnhancedRequest;
36 import software.amazon.awssdk.enhanced.dynamodb.model.UpdateItemEnhancedResponse;
37 import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
38 import software.amazon.awssdk.services.dynamodb.model.ConsumedCapacity;
39 import software.amazon.awssdk.services.dynamodb.model.DescribeTableRequest;
40 import software.amazon.awssdk.services.dynamodb.waiters.DynamoDbWaiter;
41 
42 /**
43  * Synchronous interface for running commands against an object that is linked to a specific DynamoDb table resource
44  * and therefore knows how to map records from that table into a modelled object.
45  * <p>
46  * By default, all command methods throw an {@link UnsupportedOperationException} to prevent interface extensions from
47  * breaking implementing classes.
48  * <p>
49  * @param <T> The type of the modelled object.
50  */
51 @SdkPublicApi
52 @ThreadSafe
53 public interface DynamoDbTable<T> extends MappedTableResource<T> {
54     /**
55      * Returns a mapped index that can be used to execute commands against a secondary index belonging to the table
56      * being mapped by this object. Note that only a subset of the commands that work against a table will work
57      * against a secondary index.
58      *
59      * @param indexName The name of the secondary index to build the command interface for.
60      * @return A {@link DynamoDbIndex} object that can be used to execute database commands against.
61      */
index(String indexName)62     DynamoDbIndex<T> index(String indexName);
63 
64     /**
65      * Creates a new table in DynamoDb with the name and schema already defined for this DynamoDbTable
66      * together with additional parameters specified in the supplied request object, {@link CreateTableEnhancedRequest}.
67      * <p>
68      * Use {@link DynamoDbEnhancedClient#table(String, TableSchema)} to define the mapped table resource.
69      * <p>
70      * This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous
71      * operation and that the table may not immediately be available for writes and reads. You can use
72      * {@link DynamoDbWaiter#waitUntilTableExists(DescribeTableRequest)} to wait for the resource to be ready.
73      * <p>
74      * Example:
75      * <pre>
76      * {@code
77      *
78      * ProvisionedThroughput provisionedThroughput = ProvisionedThroughput.builder()
79      *                                                                    .readCapacityUnits(50L)
80      *                                                                    .writeCapacityUnits(50L)
81      *                                                                    .build();
82      * mappedTable.createTable(CreateTableEnhancedRequest.builder()
83      *                                                   .provisionedThroughput(provisionedThroughput)
84      *                                                   .build());
85      *
86      * dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));
87      * }
88      * </pre>
89      *
90      * @param request A {@link CreateTableEnhancedRequest} containing optional parameters for table creation.
91      */
createTable(CreateTableEnhancedRequest request)92     default void createTable(CreateTableEnhancedRequest request) {
93         throw new UnsupportedOperationException();
94     }
95 
96     /**
97      * Creates a new table in DynamoDb with the name and schema already defined for this DynamoDbTable
98      * together with additional parameters specified in the supplied request object, {@link CreateTableEnhancedRequest}.
99      * <p>
100      * Use {@link DynamoDbEnhancedClient#table(String, TableSchema)} to define the mapped table resource.
101      * <p>
102      * This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous
103      * operation and that the table may not immediately be available for writes and reads. You can use
104      * {@link DynamoDbWaiter#waitUntilTableExists(DescribeTableRequest)} to wait for the resource to be ready.
105      * <p>
106      * <b>Note:</b> This is a convenience method that creates an instance of the request builder avoiding the need to
107      * create one manually via {@link CreateTableEnhancedRequest#builder()}.
108      * <p>
109      * Example:
110      * <pre>
111      * {@code
112      *
113      * ProvisionedThroughput provisionedThroughput = ProvisionedThroughput.builder()
114      *                                                                    .readCapacityUnits(50L)
115      *                                                                    .writeCapacityUnits(50L)
116      *                                                                    .build();
117      * mappedTable.createTable(r -> r.provisionedThroughput(provisionedThroughput));
118      * dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));
119      * }
120      * </pre>
121      *
122      * @param requestConsumer A {@link Consumer} of {@link CreateTableEnhancedRequest.Builder} containing optional
123      *                        parameters for table creation.
124      */
createTable(Consumer<CreateTableEnhancedRequest.Builder> requestConsumer)125     default void createTable(Consumer<CreateTableEnhancedRequest.Builder> requestConsumer) {
126         throw new UnsupportedOperationException();
127     }
128 
129     /**
130      * Creates a new table in DynamoDb with the name and schema already defined for this DynamoDbTable.
131      * <p>
132      * Use {@link DynamoDbEnhancedClient#table(String, TableSchema)} to define the mapped table resource.
133      * <p>
134      * This operation calls the low-level DynamoDB API CreateTable operation. Note that this is an asynchronous
135      * operation and that the table may not immediately be available for writes and reads. You can use
136      * {@link DynamoDbWaiter#waitUntilTableExists(DescribeTableRequest)} to wait for the resource to be ready.
137      * <p>
138      * Example:
139      * <pre>
140      * {@code
141      *
142      * mappedTable.createTable();
143      * dynamoDbClient.waiter().waitUntilTableExists(b -> b.tableName(tableName));
144      * }
145      * </pre>
146      *
147      */
createTable()148     default void createTable() {
149         throw new UnsupportedOperationException();
150     }
151 
152     /**
153      * Deletes a single item from the mapped table using a supplied primary {@link Key}.
154      * <p>
155      * The additional configuration parameters that the enhanced client supports are defined
156      * in the {@link DeleteItemEnhancedRequest}.
157      * <p>
158      * This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for
159      * further details and constraints.
160      * <p>
161      * Example:
162      * <pre>
163      * {@code
164      *
165      * MyItem previouslyPersistedItem = mappedTable.delete(DeleteItemEnhancedRequest.builder().key(key).build());
166      * }
167      * </pre>
168      *
169      * @param request A {@link DeleteItemEnhancedRequest} with key and optional directives for deleting an item from the
170      *                table.
171      * @return The item that was persisted in the database before it was deleted.
172      */
deleteItem(DeleteItemEnhancedRequest request)173     default T deleteItem(DeleteItemEnhancedRequest request) {
174         throw new UnsupportedOperationException();
175     }
176 
177     /**
178      * Deletes a single item from the mapped table using a supplied primary {@link Key}.
179      * <p>
180      * The additional configuration parameters that the enhanced client supports are defined
181      * in the {@link DeleteItemEnhancedRequest}.
182      * <p>
183      * This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for
184      * further details and constraints.
185      * <p>
186      * <b>Note:</b> This is a convenience method that creates an instance of the request builder avoiding the need to
187      * create one manually via {@link DeleteItemEnhancedRequest#builder()}.
188      * <p>
189      * Example:
190      * <pre>
191      * {@code
192      *
193      * MyItem previouslyPersistedItem = mappedTable.delete(r -> r.key(key));
194      * }
195      * </pre>
196      *
197      * @param requestConsumer A {@link Consumer} of {@link DeleteItemEnhancedRequest} with key and
198      * optional directives for deleting an item from the table.
199      * @return The item that was persisted in the database before it was deleted.
200      */
deleteItem(Consumer<DeleteItemEnhancedRequest.Builder> requestConsumer)201     default T deleteItem(Consumer<DeleteItemEnhancedRequest.Builder> requestConsumer) {
202         throw new UnsupportedOperationException();
203     }
204 
205     /**
206      * Deletes a single item from the mapped table using a supplied primary {@link Key}.
207      * <p>
208      * This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for
209      * further details and constraints.
210      * <p>
211      * Example:
212      * <pre>
213      * {@code
214      *
215      * MyItem previouslyPersistedItem = mappedTable.delete(key);
216      * }
217      * </pre>
218      *
219      * @param key A {@link Key} that will be used to match a specific record to delete from the database table.
220      * @return The item that was persisted in the database before it was deleted.
221      */
deleteItem(Key key)222     default T deleteItem(Key key) {
223         throw new UnsupportedOperationException();
224     }
225 
226     /**
227      * Deletes a single item from the mapped table using just the key of a supplied modelled 'key item' object.
228      * <p>
229      * This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for
230      * further details and constraints.
231      * <p>
232      * Example:
233      * <pre>
234      * {@code
235      *
236      * MyItem previouslyPersistedItem = mappedTable.deleteItem(keyItem);
237      * }
238      * </pre>
239      *
240      * @param keyItem A modelled item with the primary key fields set that will be used to match a specific record to
241      *                delete from the database table.
242      * @return The item that was persisted in the database before it was deleted.
243      */
deleteItem(T keyItem)244     default T deleteItem(T keyItem) {
245         throw new UnsupportedOperationException();
246     }
247 
248     /**
249      * Deletes a single item from the mapped table using a supplied primary {@link Key}.
250      * <p>
251      * The additional configuration parameters that the enhanced client supports are defined
252      * in the {@link DeleteItemEnhancedRequest}.
253      * <p>
254      * This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for
255      * further details and constraints. Unlike {@link #deleteItem(DeleteItemEnhancedRequest)}, this returns a response object,
256      * allowing the user to retrieve additional information from DynamoDB related to the API call, such as
257      * {@link ConsumedCapacity} if specified on the request.
258      * <p>
259      * Example:
260      * <pre>
261      * {@code
262      *
263      * DeleteItemEnhancedRequest request = DeleteItemEnhancedRequest.builder().key(key).build();
264      * DeleteItemEnhancedResponse<MyItem> response = mappedTable.deleteItemWithResponse(request);
265      * }
266      * </pre>
267      *
268      * @param request A {@link DeleteItemEnhancedRequest} with key and optional directives for deleting an item from the
269      *                table.
270      * @return The response returned by DynamoDB.
271      */
deleteItemWithResponse(DeleteItemEnhancedRequest request)272     default DeleteItemEnhancedResponse<T> deleteItemWithResponse(DeleteItemEnhancedRequest request) {
273         throw new UnsupportedOperationException();
274     }
275 
276     /**
277      * Deletes a single item from the mapped table using a supplied primary {@link Key}.
278      * <p>
279      * The additional configuration parameters that the enhanced client supports are defined
280      * in the {@link DeleteItemEnhancedRequest}.
281      * <p>
282      * This operation calls the low-level DynamoDB API DeleteItem operation. Consult the DeleteItem documentation for
283      * further details and constraints. Unlike {@link #deleteItem(Consumer)}, this returns a response object, allowing the user to
284      * retrieve additional information from DynamoDB related to the API call, such as {@link ConsumedCapacity} if specified on
285      * the request.
286      * <p>
287      * <b>Note:</b> This is a convenience method that creates an instance of the request builder avoiding the need to
288      * create one manually via {@link DeleteItemEnhancedRequest#builder()}.
289      * <p>
290      * Example:
291      * <pre>
292      * {@code
293      *
294      * DeleteItemEnhancedResponse<MyItem> response = mappedTable.deleteWithResponse(r -> r.key(key));
295      * }
296      * </pre>
297      *
298      * @param requestConsumer A {@link Consumer} of {@link DeleteItemEnhancedRequest} with key and
299      * optional directives for deleting an item from the table.
300      * @return The response returned by DynamoDB.
301      */
deleteItemWithResponse(Consumer<DeleteItemEnhancedRequest.Builder> requestConsumer)302     default DeleteItemEnhancedResponse<T>  deleteItemWithResponse(Consumer<DeleteItemEnhancedRequest.Builder> requestConsumer) {
303         throw new UnsupportedOperationException();
304     }
305 
306     /**
307      * Retrieves a single item from the mapped table using a supplied primary {@link Key}.
308      * <p>
309      * The additional configuration parameters that the enhanced client supports are defined
310      * in the {@link GetItemEnhancedRequest}.
311      * <p>
312      * This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for
313      * further details and constraints.
314      * <p>
315      * Example:
316      * <pre>
317      * {@code
318      *
319      * MyItem item = mappedTable.getItem(GetItemEnhancedRequest.builder().key(key).build());
320      * }
321      * </pre>
322      *
323      * @param request A {@link GetItemEnhancedRequest} with key and optional directives for retrieving an item from the
324      *                table.
325      * @return The retrieved item
326      */
getItem(GetItemEnhancedRequest request)327     default T getItem(GetItemEnhancedRequest request) {
328         throw new UnsupportedOperationException();
329     }
330 
331     /**
332      * Retrieves a single item from the mapped table using a supplied primary {@link Key}.
333      * <p>
334      * The additional configuration parameters that the enhanced client supports are defined
335      * in the {@link GetItemEnhancedRequest}.
336      * <p>
337      * This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for
338      * further details and constraints.
339      * <p>
340      * <b>Note:</b> This is a convenience method that creates an instance of the request builder avoiding the need to
341      * create one manually via {@link GetItemEnhancedRequest#builder()}.
342      * <p>
343      * Example:
344      * <pre>
345      * {@code
346      *
347      * MyItem item = mappedTable.getItem(r -> r.key(key));
348      * }
349      * </pre>
350      *
351      * @param requestConsumer A {@link Consumer} of {@link GetItemEnhancedRequest.Builder} with key and optional
352      *                        directives for retrieving an item from the table.
353      * @return The retrieved item
354      */
getItem(Consumer<GetItemEnhancedRequest.Builder> requestConsumer)355     default T getItem(Consumer<GetItemEnhancedRequest.Builder> requestConsumer) {
356         throw new UnsupportedOperationException();
357     }
358 
359     /**
360      * Retrieves a single item from the mapped table using a supplied primary {@link Key}.
361      * <p>
362      * This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for
363      * further details and constraints.
364      * <p>
365      * Example:
366      * <pre>
367      * {@code
368      *
369      * MyItem item = mappedTable.getItem(key);
370      * }
371      * </pre>
372      *
373      * @param key A {@link Key} that will be used to match a specific record to retrieve from the database table.
374      * @return The retrieved item
375      */
getItem(Key key)376     default T getItem(Key key) {
377         throw new UnsupportedOperationException();
378     }
379 
380     /**
381      * Retrieves a single item from the mapped table using just the key of a supplied modelled 'key item'.
382      * <p>
383      * This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for
384      * further details and constraints.
385      * <p>
386      * Example:
387      * <pre>
388      * {@code
389      *
390      * MyItem item = mappedTable.getItem(keyItem);
391      * }
392      * </pre>
393      *
394      * @param keyItem A modelled item with the primary key fields set that will be used to match a specific record to
395      *                retrieve from the database table.
396      * @return The retrieved item
397      */
getItem(T keyItem)398     default T getItem(T keyItem) {
399         throw new UnsupportedOperationException();
400     }
401 
402     /**
403      * Retrieves a single item from the mapped table using a supplied primary {@link Key}. This is similar to
404      * {@link #getItem(GetItemEnhancedRequest)} but returns {@link GetItemEnhancedResponse} for additional information.
405      *
406      * <p>
407      * The additional configuration parameters that the enhanced client supports are defined
408      * in the {@link GetItemEnhancedRequest}.
409      * <p>
410      * This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for
411      * further details and constraints.
412      * <p>
413      * Example:
414      * <pre>
415      * {@code
416      *
417      * MyItem item = mappedTable.getItemWithResponse(GetItemEnhancedRequest.builder().key(key).build());
418      * }
419      * </pre>
420      *
421      * @param request A {@link GetItemEnhancedRequest} with key and optional directives for retrieving an item from the
422      *                table.
423      * @return The retrieved item
424      */
getItemWithResponse(GetItemEnhancedRequest request)425     default GetItemEnhancedResponse<T> getItemWithResponse(GetItemEnhancedRequest request) {
426         throw new UnsupportedOperationException();
427     }
428 
429     /**
430      * Retrieves a single item from the mapped table using a supplied primary {@link Key}. This is similar to
431      * {@link #getItem(Consumer<GetItemEnhancedRequest.Builder>)} but returns {@link GetItemEnhancedResponse} for additional
432      * information.
433      *
434      * <p>
435      * The additional configuration parameters that the enhanced client supports are defined
436      * in the {@link GetItemEnhancedRequest}.
437      * <p>
438      * This operation calls the low-level DynamoDB API GetItem operation. Consult the GetItem documentation for
439      * further details and constraints.
440      * <p>
441      * <b>Note:</b> This is a convenience method that creates an instance of the request builder avoiding the need to
442      * create one manually via {@link GetItemEnhancedRequest#builder()}.
443      * <p>
444      * Example:
445      * <pre>
446      * {@code
447      *
448      * MyItem item = mappedTable.getItemWithResponse(r -> r.key(key));
449      * }
450      * </pre>
451      *
452      * @param requestConsumer A {@link Consumer} of {@link GetItemEnhancedRequest.Builder} with key and optional
453      *                        directives for retrieving an item from the table.
454      * @return The retrieved item
455      */
getItemWithResponse(Consumer<GetItemEnhancedRequest.Builder> requestConsumer)456     default GetItemEnhancedResponse<T> getItemWithResponse(Consumer<GetItemEnhancedRequest.Builder> requestConsumer) {
457         throw new UnsupportedOperationException();
458     }
459 
460     /**
461      * Executes a query against the primary index of the table using a {@link QueryConditional} expression to retrieve a
462      * list of items matching the given conditions.
463      * <p>
464      * The result can be accessed either through iterable {@link Page}s or {@link Page#items()} directly. If you are iterating
465      * the pages, the result is accessed through iterable pages (see {@link Page}) in an interactive way; each time a
466      * result page is retrieved, a query call is made to DynamoDb to get those entries. If no matches are found,
467      * the resulting iterator will contain an empty page. Results are sorted by sort key value in ascending order by default;
468      * this behavior can be overridden in the {@link QueryEnhancedRequest}.
469      * <p>
470      * The additional configuration parameters that the enhanced client supports are defined
471      * in the {@link QueryEnhancedRequest}.
472      * <p>
473      * This operation calls the low-level DynamoDB API Query operation. Consult the Query documentation for
474      * further details and constraints.
475      * <p>
476      * Example:
477      * <p>
478      * 1) Iterating through pages
479      *
480      * <pre>
481      * {@code
482      * QueryConditional queryConditional = QueryConditional.keyEqualTo(Key.builder().partitionValue("id-value").build());
483      * PageIterable<MyItem> results = table.query(QueryEnhancedRequest.builder()
484      *                                                                        .queryConditional(queryConditional)
485      *                                                                        .build());
486      * results.stream().forEach(p -> p.items().forEach(item -> System.out.println(item)))
487      * }
488      * </pre>
489      *
490      * 2) Iterating through items
491      *
492      * <pre>
493      * {@code
494      * results.items().stream().forEach(item -> System.out.println(item));
495      * }
496      * </pre>
497      *
498      * @see #query(QueryConditional)
499      * @see #query(Consumer)
500      * @see DynamoDbClient#queryPaginator
501      * @param request A {@link QueryEnhancedRequest} defining the query conditions and how
502      * to handle the results.
503      * @return an iterator of type {@link SdkIterable} with paginated results (see {@link Page}).
504      */
query(QueryEnhancedRequest request)505     default PageIterable<T> query(QueryEnhancedRequest request) {
506         throw new UnsupportedOperationException();
507     }
508 
509     /**
510      * This is a convenience method that creates an instance of the request builder avoiding the need to create one
511      * manually via {@link QueryEnhancedRequest#builder()}.
512      * <p>
513      * Example:
514      * <pre>
515      * {@code
516      *
517      * PageIterable<MyItem> results =
518      *     mappedTable.query(r -> r.queryConditional(QueryConditional.keyEqualTo(k -> k.partitionValue("id-value"))));
519      * }
520      * </pre>
521      * @see #query(QueryEnhancedRequest)
522      * @see #query(QueryConditional)
523      * @param requestConsumer A {@link Consumer} of {@link QueryEnhancedRequest} defining the query conditions and how to
524      * handle the results.
525      * @return an iterator of type {@link SdkIterable} with paginated results (see {@link Page}).
526      */
query(Consumer<QueryEnhancedRequest.Builder> requestConsumer)527     default PageIterable<T> query(Consumer<QueryEnhancedRequest.Builder> requestConsumer) {
528         throw new UnsupportedOperationException();
529     }
530 
531     /**
532      * Executes a query against the primary index of the table using a {@link QueryConditional} expression to retrieve a
533      * list of items matching the given conditions.
534      * <p>
535      * Example:
536      * <pre>
537      * {@code
538      *
539      * PageIterable<MyItem> results =
540      *     mappedTable.query(QueryConditional.keyEqualTo(Key.builder().partitionValue("id-value").build()));
541      * }
542      * </pre>
543      *
544      * @see #query(QueryEnhancedRequest)
545      * @see #query(Consumer)
546      * @see DynamoDbClient#queryPaginator
547      * @param queryConditional A {@link QueryConditional} defining the matching criteria for records to be queried.
548      * @return an iterator of type {@link SdkIterable} with paginated results (see {@link Page}).
549      */
query(QueryConditional queryConditional)550     default PageIterable<T> query(QueryConditional queryConditional) {
551         throw new UnsupportedOperationException();
552     }
553 
554     /**
555      * Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be
556      * replaced with this item.
557      * <p>
558      * The additional configuration parameters that the enhanced client supports are defined
559      * in the {@link PutItemEnhancedRequest}.
560      * <p>
561      * This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for
562      * further details and constraints.
563      * <p>
564      * Example:
565      * <pre>
566      * {@code
567      *
568      * mappedTable.putItem(PutItemEnhancedRequest.builder(MyItem.class).item(item).build());
569      * }
570      * </pre>
571      *
572      * @param request A {@link PutItemEnhancedRequest} that includes the item to enter into
573      * the table, its class and optional directives.
574      */
putItem(PutItemEnhancedRequest<T> request)575     default void putItem(PutItemEnhancedRequest<T> request) {
576         throw new UnsupportedOperationException();
577     }
578 
579     /**
580      * Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be
581      * replaced with this item.
582      * <p>
583      * The additional configuration parameters that the enhanced client supports are defined
584      * in the {@link PutItemEnhancedRequest}.
585      * <p>
586      * This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for
587      * further details and constraints.
588      * <p>
589      * Example:
590      * <pre>
591      * {@code
592      *
593      * mappedTable.putItem(r -> r.item(item));
594      * }
595      * </pre>
596      *
597      * @param requestConsumer A {@link Consumer} of {@link PutItemEnhancedRequest.Builder} that includes the item
598      * to enter into the table, its class and optional directives.
599      */
putItem(Consumer<PutItemEnhancedRequest.Builder<T>> requestConsumer)600     default void putItem(Consumer<PutItemEnhancedRequest.Builder<T>> requestConsumer) {
601         throw new UnsupportedOperationException();
602     }
603 
604     /**
605      * Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be
606      * replaced with this item.
607      * <p>
608      * This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for
609      * further details and constraints.
610      * <p>
611      * Example:
612      * <pre>
613      * {@code
614      *
615      * mappedTable.putItem(item);
616      * }
617      * </pre>
618      *
619      * @param item the modelled item to be inserted into or overwritten in the database table.
620      */
putItem(T item)621     default void putItem(T item) {
622         throw new UnsupportedOperationException();
623     }
624 
625     /**
626      * Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be
627      * replaced with this item. This is similar to {@link #putItem(PutItemEnhancedRequest)} but returns
628      * {@link PutItemEnhancedResponse} for additional information.
629      * <p>
630      * The additional configuration parameters that the enhanced client supports are defined
631      * in the {@link PutItemEnhancedRequest}.
632      * <p>
633      * This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for
634      * further details and constraints.
635      * <p>
636      * Example:
637      * <pre>
638      * {@code
639      *
640      * mappedTable.putItem(PutItemEnhancedRequest.builder(MyItem.class).item(item).build());
641      * }
642      * </pre>
643      *
644      * @param request A {@link PutItemEnhancedRequest} that includes the item to enter into
645      * the table, its class and optional directives.
646      *
647      * @return The response returned by DynamoDB.
648      */
putItemWithResponse(PutItemEnhancedRequest<T> request)649     default PutItemEnhancedResponse<T> putItemWithResponse(PutItemEnhancedRequest<T> request) {
650         throw new UnsupportedOperationException();
651     }
652 
653     /**
654      * Puts a single item in the mapped table. If the table contains an item with the same primary key, it will be
655      * replaced with this item. This is similar to {@link #putItem(PutItemEnhancedRequest)} but returns
656      * {@link PutItemEnhancedResponse} for additional information.
657      * <p>
658      * The additional configuration parameters that the enhanced client supports are defined
659      * in the {@link PutItemEnhancedRequest}.
660      * <p>
661      * This operation calls the low-level DynamoDB API PutItem operation. Consult the PutItem documentation for
662      * further details and constraints.
663      * <p>
664      * Example:
665      * <pre>
666      * {@code
667      *
668      * mappedTable.putItem(PutItemEnhancedRequest.builder(MyItem.class).item(item).build());
669      * }
670      * </pre>
671      *
672      * @param requestConsumer A {@link Consumer} of {@link PutItemEnhancedRequest.Builder} that includes the item
673      * to enter into the table, its class and optional directives.
674      *
675      * @return The response returned by DynamoDB.
676      */
putItemWithResponse(Consumer<PutItemEnhancedRequest.Builder<T>> requestConsumer)677     default PutItemEnhancedResponse<T> putItemWithResponse(Consumer<PutItemEnhancedRequest.Builder<T>> requestConsumer) {
678         throw new UnsupportedOperationException();
679     }
680 
681     /**
682      * Scans the table and retrieves all items.
683      * <p>
684      * The result can be accessed either through iterable {@link Page}s or items across all pages directly. Each time a
685      * result page is retrieved, a query call is made to DynamoDb to get those entries. If no matches are found,
686      * the resulting iterator will contain an empty page.
687      * <p>
688      * The additional configuration parameters that the enhanced client supports are defined
689      * in the {@link ScanEnhancedRequest}.
690      * <p>
691      * Example:
692      * <p>
693      * 1) Iterating through pages
694      * <pre>
695      * {@code
696      *
697      * PageIterable<MyItem> results = mappedTable.scan(ScanEnhancedRequest.builder().consistentRead(true).build());
698      * results.stream().forEach(p -> p.items().forEach(item -> System.out.println(item)))
699      * }
700      * </pre>
701      *
702      * <p>
703      * 2) Iterating through items
704      * <pre>
705      * {@code
706      *
707      * PageIterable<MyItem> results = mappedTable.scan(ScanEnhancedRequest.builder().consistentRead(true).build());
708      * results.items().stream().forEach(item -> System.out.println(item));
709      * }
710      * </pre>
711      *
712      * @see #scan(Consumer)
713      * @see #scan()
714      * @see DynamoDbClient#scanPaginator
715      * @param request A {@link ScanEnhancedRequest} defining how to handle the results.
716      * @return an iterator of type {@link SdkIterable} with paginated results (see {@link Page}).
717      */
scan(ScanEnhancedRequest request)718     default PageIterable<T> scan(ScanEnhancedRequest request) {
719         throw new UnsupportedOperationException();
720     }
721 
722     /**
723      * This is a convenience method that creates an instance of the request builder avoiding the need to create one
724      * manually via {@link ScanEnhancedRequest#builder()}.
725      *
726      * <p>
727      * Example:
728      * <pre>
729      * {@code
730      *
731      * PageIterable<MyItem> results = mappedTable.scan(r -> r.limit(5));
732      * }
733      * </pre>
734      *
735      * @see #scan(ScanEnhancedRequest)
736      * @see #scan()
737      * @param requestConsumer A {@link Consumer} of {@link ScanEnhancedRequest} defining the query conditions and how to
738      * handle the results.
739      * @return an iterator of type {@link SdkIterable} with paginated results (see {@link Page}).
740      */
scan(Consumer<ScanEnhancedRequest.Builder> requestConsumer)741     default PageIterable<T> scan(Consumer<ScanEnhancedRequest.Builder> requestConsumer) {
742         throw new UnsupportedOperationException();
743     }
744 
745     /**
746      * Scans the table and retrieves all items using default settings.
747      * <p>
748      * The result can be accessed either through iterable {@link Page}s or items across all pages directly. Each time a
749      * result page is retrieved, a query call is made to DynamoDb to get those entries. If no matches are found,
750      * the resulting iterator will contain an empty page.
751      * <p>
752      * Example:
753      * <pre>
754      * {@code
755      *
756      * PageIterable<MyItem> results = mappedTable.scan();
757      * }
758      * </pre>
759      *
760      * @see #scan(ScanEnhancedRequest)
761      * @see #scan(Consumer)
762      * @see DynamoDbClient#scanPaginator
763      * @return an iterator of type {@link SdkIterable} with paginated results (see {@link Page}).
764      */
scan()765     default PageIterable<T> scan() {
766         throw new UnsupportedOperationException();
767     }
768 
769     /**
770      * Updates an item in the mapped table, or adds it if it doesn't exist.
771      * <p>
772      * The additional configuration parameters that the enhanced client supports are defined
773      * in the {@link UpdateItemEnhancedRequest}.
774      * <p>
775      * This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for
776      * further details and constraints.
777      * <p>
778      * Example:
779      * <pre>
780      * {@code
781      *
782      * MyItem item = mappedTable.updateItem(UpdateItemEnhancedRequest.builder(MyItem.class).item(item).build());
783      * }
784      * </pre>
785      *
786      * @param request A {@link UpdateItemEnhancedRequest} that includes the item to be updated,
787      * its class and optional directives.
788      * @return The updated item
789      */
updateItem(UpdateItemEnhancedRequest<T> request)790     default T updateItem(UpdateItemEnhancedRequest<T> request) {
791         throw new UnsupportedOperationException();
792     }
793 
794     /**
795      * Updates an item in the mapped table, or adds it if it doesn't exist.
796      * <p>
797      * The additional configuration parameters that the enhanced client supports are defined
798      * in the {@link UpdateItemEnhancedRequest}.
799      * <p>
800      * This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for
801      * further details and constraints.
802      * <p>
803      * Example:
804      * <pre>
805      * {@code
806      *
807      * MyItem item = mappedTable.updateItem(r -> r.item(item));
808      * }
809      * </pre>
810      *
811      * @param requestConsumer A {@link Consumer} of {@link UpdateItemEnhancedRequest.Builder} that includes the item
812      * to be updated, its class and optional directives.
813      * @return The updated item
814      */
updateItem(Consumer<UpdateItemEnhancedRequest.Builder<T>> requestConsumer)815     default T updateItem(Consumer<UpdateItemEnhancedRequest.Builder<T>> requestConsumer) {
816         throw new UnsupportedOperationException();
817     }
818 
819     /**
820      * Updates an item in the mapped table, or adds it if it doesn't exist.
821      * <p>
822      * This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for
823      * further details and constraints.
824      * <p>
825      * Example:
826      * <pre>
827      * {@code
828      *
829      * MyItem item = mappedTable.updateItem(item);
830      * }
831      * </pre>
832      *
833      * @param item the modelled item to be inserted into or updated in the database table.
834      * @return The updated item
835      */
updateItem(T item)836     default T updateItem(T item) {
837         throw new UnsupportedOperationException();
838     }
839 
840     /**
841      * Updates an item in the mapped table, or adds it if it doesn't exist. This is similar to
842      * {@link #updateItem(UpdateItemEnhancedRequest)}} but returns {@link UpdateItemEnhancedResponse} for additional information.
843      * <p>
844      * This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for
845      * further details and constraints.
846      * <p>
847      * Example:
848      * <pre>
849      * {@code
850      * UpdateItemEnhancedRequest<MyItem> request = UpdateItemEnhancedRequest.builder(MyItem.class).item(myItem).build();
851      * UpdateItemEnhancedResponse<MyItem> response = mappedTable.updateItemWithResponse(request);
852      * }
853      * </pre>
854      * <p>
855      *
856      *
857      * @param request the modelled item to be inserted into or updated in the database table.
858      * @return The response returned by DynamoDB.
859      */
updateItemWithResponse(UpdateItemEnhancedRequest<T> request)860     default UpdateItemEnhancedResponse<T> updateItemWithResponse(UpdateItemEnhancedRequest<T> request) {
861         throw new UnsupportedOperationException();
862     }
863 
864     /**
865      * Updates an item in the mapped table, or adds it if it doesn't exist. This is similar to
866      * {@link #updateItem(Consumer)} but returns {@link UpdateItemEnhancedResponse} for additional information.
867      * <p>
868      * This operation calls the low-level DynamoDB API UpdateItem operation. Consult the UpdateItem documentation for
869      * further details and constraints.
870      * <p>
871      * Example:
872      * <pre>
873      * {@code
874      *
875      * UpdateItemEnhancedResponse<MyItem> response = mappedTable.updateItemWithResponse(r ->r.item(myItem));
876      * }
877      * </pre>
878      * <p>
879      *
880      *
881      * @param requestConsumer A {@link Consumer} of {@link UpdateItemEnhancedRequest.Builder} that includes the item
882      *      * to be updated, its class and optional directives.
883      * @return The response from DynamoDB.
884      */
updateItemWithResponse(Consumer<UpdateItemEnhancedRequest.Builder<T>> requestConsumer)885     default UpdateItemEnhancedResponse<T> updateItemWithResponse(Consumer<UpdateItemEnhancedRequest.Builder<T>> requestConsumer) {
886         throw new UnsupportedOperationException();
887     }
888 
889     /**
890      * Deletes a table in DynamoDb with the name and schema already defined for this DynamoDbTable.
891      * <p>
892      * Use {@link DynamoDbEnhancedClient#table(String, TableSchema)} to define the mapped table resource.
893      * <p>
894      * This operation calls the low-level DynamoDB API DeleteTable operation.
895      * Note that this is an asynchronous operation and that the table may not immediately be deleted. You can use
896      * {@link DynamoDbWaiter#waitUntilTableNotExists}
897      * in the underlying client.
898      * <p>
899      * Example:
900      * <pre>
901      * {@code
902      *
903      * mappedTable.deleteTable();
904      * }
905      * </pre>
906      *
907      */
deleteTable()908     default void deleteTable() {
909         throw new UnsupportedOperationException();
910     }
911 
912     /**
913      * Describes a table in DynamoDb with the name defined for this {@link DynamoDbTable}.
914      * This operation calls the low-level DynamoDB API DescribeTable operation,
915      * see {@link DynamoDbClient#describeTable(DescribeTableRequest)}
916      * <p>
917      * Example:
918      * <pre>
919      * {@code
920      *
921      * DescribeTableEnhancedResponse response = mappedTable.describeTable();
922      * }
923      * </pre>
924      *
925      */
describeTable()926     default DescribeTableEnhancedResponse describeTable() {
927         throw new UnsupportedOperationException();
928     }
929 }
930