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.mapper.annotations;
17 
18 import java.lang.annotation.ElementType;
19 import java.lang.annotation.Retention;
20 import java.lang.annotation.RetentionPolicy;
21 import java.lang.annotation.Target;
22 import software.amazon.awssdk.annotations.SdkPublicApi;
23 import software.amazon.awssdk.enhanced.dynamodb.AttributeConverter;
24 import software.amazon.awssdk.enhanced.dynamodb.AttributeConverterProvider;
25 import software.amazon.awssdk.enhanced.dynamodb.DefaultAttributeConverterProvider;
26 import software.amazon.awssdk.enhanced.dynamodb.mapper.BeanTableSchema;
27 
28 /**
29  * Class level annotation that identifies this class as being a DynamoDb mappable entity. Any class used to initialize
30  * a {@link BeanTableSchema} must have this annotation. If a class is used as an attribute type within another
31  * annotated DynamoDb class, either as a document or flattened with the {@link DynamoDbFlatten} annotation, it will also
32  * require this annotation to work automatically without an explicit {@link AttributeConverter}.
33  * <p>
34  * <b>Attribute Converter Providers</b><br>
35  * Using {@link AttributeConverterProvider}s is optional and, if used, the supplied provider supersedes the default
36  * converter provided by the table schema.
37  * <p>
38  * Note:
39  * <ul>
40  *     <li>The converter(s) must provide {@link AttributeConverter}s for all types used in the schema. </li>
41  *     <li>The table schema DefaultAttributeConverterProvider provides standard converters for most primitive
42  *     and common Java types. Use custom AttributeConverterProviders when you have specific needs for type conversion
43  *     that the defaults do not cover.</li>
44  *     <li>If you provide a list of attribute converter providers, you can add DefaultAttributeConverterProvider
45  *     to the end of the list to fall back on the defaults.</li>
46  *     <li>Providing an empty list {} will cause no providers to get loaded.</li>
47  * </ul>
48  *
49  * Example using attribute converter providers with one custom provider and the default provider:
50  * <pre>
51  * {@code
52  * (converterProviders = {CustomAttributeConverter.class, DefaultAttributeConverterProvider.class});
53  * }
54  * </pre>
55  * <p>
56  * Example using {@link DynamoDbBean}:
57  * <pre>
58  * {@code
59  * @DynamoDbBean
60  * public class Customer {
61  *     private String id;
62  *     private Instant createdOn;
63  *
64  *     @DynamoDbPartitionKey
65  *     public String getId() {
66  *          return this.id;
67  *     }
68  *
69  *     public void setId(String id) {
70  *          this.id = id;
71  *     }
72  *
73  *     public Instant getCreatedOn() {
74  *          return this.createdOn;
75  *     }
76  *     public void setCreatedOn(Instant createdOn) {
77  *          this.createdOn = createdOn;
78  *      }
79  * }
80  * }
81  * </pre>
82  */
83 @Target({ElementType.TYPE})
84 @Retention(RetentionPolicy.RUNTIME)
85 @SdkPublicApi
86 public @interface DynamoDbBean {
converterProviders()87     Class<? extends AttributeConverterProvider>[] converterProviders()
88             default { DefaultAttributeConverterProvider.class };
89 }
90