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.time.Instant;
19 import software.amazon.awssdk.annotations.SdkPublicApi;
20 import software.amazon.awssdk.annotations.ThreadSafe;
21 import software.amazon.awssdk.enhanced.dynamodb.internal.converter.attribute.InstantAsStringAttributeConverter;
22 import software.amazon.awssdk.enhanced.dynamodb.internal.converter.attribute.StringAttributeConverter;
23 import software.amazon.awssdk.services.dynamodb.model.AttributeValue;
24 
25 /**
26  * Converts between a specific Java type and an {@link AttributeValue}.
27  *
28  * <p>
29  * Examples:
30  * <ul>
31  *     <li>The {@link StringAttributeConverter} converts a {@link String} into a DynamoDB string
32  *     ({@link software.amazon.awssdk.services.dynamodb.model.AttributeValue#s()}).</li>
33  *     <li>The {@link InstantAsStringAttributeConverter} converts an {@link Instant} into a DynamoDB string
34  *     ({@link software.amazon.awssdk.services.dynamodb.model.AttributeValue#s()}).</li>
35  * </ul>
36  */
37 @SdkPublicApi
38 @ThreadSafe
39 public interface AttributeConverter<T> {
40     /**
41      * Convert the provided Java object into an {@link AttributeValue}. This will raise a {@link RuntimeException} if the
42      * conversion fails, or the input is null.
43      *
44      * <p>
45      * Example:
46      * <pre>
47      * {@code
48      * InstantAsStringAttributeConverter converter = InstantAsStringAttributeConverter.create();
49      * assertEquals(converter.transformFrom(Instant.EPOCH),
50      *              EnhancedAttributeValue.fromString("1970-01-01T00:00:00Z").toAttributeValue());
51      * }
52      * </pre>
53      */
transformFrom(T input)54     AttributeValue transformFrom(T input);
55 
56     /**
57      * Convert the provided {@link AttributeValue} into a Java object. This will raise a {@link RuntimeException} if the
58      * conversion fails, or the input is null.
59      *
60      * <p>
61      * <pre>
62      * Example:
63      * {@code
64      * InstantAsStringAttributeConverter converter = InstantAsStringAttributeConverter.create();
65      * assertEquals(converter.transformTo(EnhancedAttributeValue.fromString("1970-01-01T00:00:00Z").toAttributeValue()),
66      *              Instant.EPOCH);
67      * }
68      * </pre>
69      */
transformTo(AttributeValue input)70     T transformTo(AttributeValue input);
71 
72     /**
73      * The type supported by this converter.
74      */
type()75     EnhancedType<T> type();
76 
77     /**
78      * The {@link AttributeValueType} that a converter stores and reads values
79      * from DynamoDB via the {@link AttributeValue} class.
80      */
attributeValueType()81     AttributeValueType attributeValueType();
82 }
83