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