|
| 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.internal; |
| 17 | + |
| 18 | +import static software.amazon.awssdk.enhanced.dynamodb.internal.EnhancedClientUtils.cleanAttributeName; |
| 19 | + |
| 20 | +import java.util.Collections; |
| 21 | +import java.util.HashMap; |
| 22 | +import java.util.List; |
| 23 | +import java.util.Map; |
| 24 | +import java.util.Optional; |
| 25 | +import java.util.function.UnaryOperator; |
| 26 | +import java.util.stream.Collectors; |
| 27 | +import java.util.stream.IntStream; |
| 28 | +import java.util.stream.Stream; |
| 29 | +import software.amazon.awssdk.annotations.SdkInternalApi; |
| 30 | +import software.amazon.awssdk.enhanced.dynamodb.NestedAttributeName; |
| 31 | +import software.amazon.awssdk.utils.CollectionUtils; |
| 32 | +import software.amazon.awssdk.utils.Pair; |
| 33 | + |
| 34 | +/** |
| 35 | + * This class represents the concept of a projection expression, which allows the user to specify which specific attributes |
| 36 | + * should be returned when a table is queried. By default, all attribute names in a projection expression are replaced with |
| 37 | + * a cleaned placeholder version of itself, prefixed with <i>#AMZN_MAPPED</i>. |
| 38 | + * <p> |
| 39 | + * A ProjectionExpression can return a correctly formatted projection expression string |
| 40 | + * containing placeholder names (see {@link #projectionExpressionAsString()}), as well as the expression attribute names map which |
| 41 | + * contains the mapping from the placeholder attribute name to the actual attribute name (see |
| 42 | + * {@link #expressionAttributeNames()}). |
| 43 | + * <p> |
| 44 | + * <b>Resolving duplicates</b> |
| 45 | + * <ul> |
| 46 | + * <li>If the input to the ProjectionExpression contains the same attribute name in more than one place, independent of |
| 47 | + * nesting level, it will be mapped to a single placeholder</li> |
| 48 | + * <li>If two attributes resolves to the same placeholder name, a disambiguator is added to the placeholder in order to |
| 49 | + * make it unique.</li> |
| 50 | + * </ul> |
| 51 | + * <p> |
| 52 | + * <b>Placeholder conversion examples</b> |
| 53 | + * <ul> |
| 54 | + * <li>'MyAttribute' maps to {@code #AMZN_MAPPED_MyAttribute}</li> |
| 55 | + * <li>'MyAttribute' appears twice in input but maps to only one entry {@code #AMZN_MAPPED_MyAttribute}.</li> |
| 56 | + * <li>'MyAttribute-1' maps to {@code #AMZN_MAPPED_MyAttribute_1}</li> |
| 57 | + * <li>'MyAttribute-1' and 'MyAttribute.1' in the same input maps to {@code #AMZN_MAPPED_0_MyAttribute_1} and |
| 58 | + * {@code #AMZN_MAPPED_1_MyAttribute_1}</li> |
| 59 | + * </ul> |
| 60 | + * <b>Projection expression usage example</b> |
| 61 | + * <pre> |
| 62 | + * {@code |
| 63 | + * List<NestedAttributeName> attributeNames = Arrays.asList( |
| 64 | + * NestedAttributeName.create("MyAttribute") |
| 65 | + * NestedAttributeName.create("MyAttribute.WithDot", "MyAttribute.03"), |
| 66 | + * NestedAttributeName.create("MyAttribute:03, "MyAttribute") |
| 67 | + * ); |
| 68 | + * ProjectionExpression projectionExpression = ProjectionExpression.create(attributeNames); |
| 69 | + * Map<String, String> expressionAttributeNames = projectionExpression.expressionAttributeNames(); |
| 70 | + * Optional<String> projectionExpressionString = projectionExpression.projectionExpressionAsString(); |
| 71 | + * } |
| 72 | + * |
| 73 | + * results in |
| 74 | + * |
| 75 | + * expressionAttributeNames: { |
| 76 | + * #AMZN_MAPPED_MyAttribute : MyAttribute, |
| 77 | + * #AMZN_MAPPED_MyAttribute_WithDot : MyAttribute.WithDot} |
| 78 | + * #AMZN_MAPPED_0_MyAttribute_03 : MyAttribute.03} |
| 79 | + * #AMZN_MAPPED_1_MyAttribute_03 : MyAttribute:03} |
| 80 | + * } |
| 81 | + * and |
| 82 | + * |
| 83 | + * projectionExpressionString: "#AMZN_MAPPED_MyAttribute,#AMZN_MAPPED_MyAttribute_WithDot.#AMZN_MAPPED_0_MyAttribute_03, |
| 84 | + * #AMZN_MAPPED_1_MyAttribute_03.#AMZN_MAPPED_MyAttribute" |
| 85 | + * </pre> |
| 86 | + * <p> |
| 87 | + * For more information, see <a href= |
| 88 | + * "https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html" |
| 89 | + * >Projection Expressions</a> in the <i>Amazon DynamoDB Developer Guide</i>. |
| 90 | + * </p> |
| 91 | + */ |
| 92 | +@SdkInternalApi |
| 93 | +public class ProjectionExpression { |
| 94 | + |
| 95 | + private static final String AMZN_MAPPED = "#AMZN_MAPPED_"; |
| 96 | + private static final UnaryOperator<String> PROJECTION_EXPRESSION_KEY_MAPPER = k -> AMZN_MAPPED + cleanAttributeName(k); |
| 97 | + |
| 98 | + private final Optional<String> projectionExpressionAsString; |
| 99 | + private final Map<String, String> expressionAttributeNames; |
| 100 | + |
| 101 | + private ProjectionExpression(List<NestedAttributeName> nestedAttributeNames) { |
| 102 | + this.expressionAttributeNames = createAttributePlaceholders(nestedAttributeNames); |
| 103 | + this.projectionExpressionAsString = buildProjectionExpression(nestedAttributeNames, this.expressionAttributeNames); |
| 104 | + } |
| 105 | + |
| 106 | + public static ProjectionExpression create(List<NestedAttributeName> nestedAttributeNames) { |
| 107 | + return new ProjectionExpression(nestedAttributeNames); |
| 108 | + } |
| 109 | + |
| 110 | + public Map<String, String> expressionAttributeNames() { |
| 111 | + return this.expressionAttributeNames; |
| 112 | + } |
| 113 | + |
| 114 | + public Optional<String> projectionExpressionAsString() { |
| 115 | + return this.projectionExpressionAsString; |
| 116 | + } |
| 117 | + |
| 118 | + /** |
| 119 | + * Creates a map of modified attribute/placeholder name -> real attribute name based on what is essentially a list of list of |
| 120 | + * attribute names. Duplicates are removed from the list of attribute names and then the names are transformed |
| 121 | + * into DDB-compatible 'placeholders' using the supplied function, resulting in a |
| 122 | + * map of placeholder name -> list of original attribute names that resolved to that placeholder. |
| 123 | + * If different original attribute names end up having the same placeholder name, a disambiguator is added to those |
| 124 | + * placeholders to make them unique and the number of map entries expand with the length of that list; however this is |
| 125 | + * a rare use-case and normally it's a 1:1 relation. |
| 126 | + */ |
| 127 | + private static Map<String, String> createAttributePlaceholders(List<NestedAttributeName> nestedAttributeNames) { |
| 128 | + if (CollectionUtils.isNullOrEmpty(nestedAttributeNames)) { |
| 129 | + return new HashMap<>(); |
| 130 | + } |
| 131 | + |
| 132 | + Map<String, List<String>> placeholderToAttributeNames = |
| 133 | + nestedAttributeNames.stream() |
| 134 | + .flatMap(n -> n.elements().stream()) |
| 135 | + .distinct() |
| 136 | + .collect(Collectors.groupingBy(PROJECTION_EXPRESSION_KEY_MAPPER, Collectors.toList())); |
| 137 | + |
| 138 | + return Collections.unmodifiableMap( |
| 139 | + placeholderToAttributeNames.entrySet() |
| 140 | + .stream() |
| 141 | + .flatMap(entry -> disambiguateNonUniquePlaceholderNames(entry.getKey(), |
| 142 | + entry.getValue())) |
| 143 | + .collect(Collectors.toMap(Pair::left, Pair::right))); |
| 144 | + } |
| 145 | + |
| 146 | + private static Stream<Pair<String, String>> disambiguateNonUniquePlaceholderNames(String placeholder, List<String> values) { |
| 147 | + if (values.size() == 1) { |
| 148 | + return Stream.of(Pair.of(placeholder, values.get(0))); |
| 149 | + } |
| 150 | + return IntStream.range(0, values.size()) |
| 151 | + .mapToObj(index -> Pair.of(addDisambiguator(placeholder, index), values.get(index))); |
| 152 | + } |
| 153 | + |
| 154 | + private static String addDisambiguator(String placeholder, int index) { |
| 155 | + return AMZN_MAPPED + index + "_" + placeholder.substring(AMZN_MAPPED.length()); |
| 156 | + } |
| 157 | + |
| 158 | + /** |
| 159 | + * The projection expression contains only placeholder names, and is based on the list if nested attribute names, which |
| 160 | + * are converted into string representations with each attribute name replaced by its placeholder name as specified |
| 161 | + * in the expressionAttributeNames map. Because we need to find the placeholder value of an attribute, the |
| 162 | + * expressionAttributeNames map must be reversed before doing a lookup. |
| 163 | + */ |
| 164 | + private static Optional<String> buildProjectionExpression(List<NestedAttributeName> nestedAttributeNames, |
| 165 | + Map<String, String> expressionAttributeNames) { |
| 166 | + if (CollectionUtils.isNullOrEmpty(nestedAttributeNames)) { |
| 167 | + return Optional.empty(); |
| 168 | + } |
| 169 | + |
| 170 | + Map<String, String> attributeToPlaceholderNames = CollectionUtils.inverseMap(expressionAttributeNames); |
| 171 | + |
| 172 | + return Optional.of(nestedAttributeNames.stream() |
| 173 | + .map(attributeName -> convertToNameExpression(attributeName, |
| 174 | + attributeToPlaceholderNames)) |
| 175 | + .distinct() |
| 176 | + .collect(Collectors.joining(","))); |
| 177 | + } |
| 178 | + |
| 179 | + private static String convertToNameExpression(NestedAttributeName nestedAttributeName, |
| 180 | + Map<String, String> attributeToSanitizedMap) { |
| 181 | + return nestedAttributeName.elements() |
| 182 | + .stream() |
| 183 | + .map(attributeToSanitizedMap::get) |
| 184 | + .collect(Collectors.joining(".")); |
| 185 | + } |
| 186 | + |
| 187 | +} |
0 commit comments