Java tutorial
/* * Copyright 2015-2019 Amazon Technologies, Inc. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at: * * http://aws.amazon.com/apache2.0 * * This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES * OR CONDITIONS OF ANY KIND, either express or implied. See the * License for the specific language governing permissions and * limitations under the License. */ package com.amazonaws.services.dynamodbv2.xspec; import java.nio.ByteBuffer; import java.util.LinkedHashMap; import java.util.LinkedHashSet; import java.util.LinkedList; import java.util.List; import java.util.Map; import java.util.Set; import com.amazonaws.annotation.Beta; /** * A request-centric Expression Specification Builder that can be used to * construct valid expressions, and the respective name maps and value maps, for * various DynamoDB requests in a typeful manner. This includes <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >Update expression</a>, <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html" * >Condition expression</a> (including Filter expression and Key Condition * expression), and <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.AccessingItemAttributes.html" * >Projection expression</a>. This class is the API entry point to this * library. * <p> * This builder object is not thread-safe but you can reuse or build on (the * specific states of) a builder by cloning it into separate instances for use * in a concurrent environment. * * <h3>Sample Usage 1: Conditional Updates with Expressions</h3> * * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * Table table = dynamo.getTable(TABLE_NAME); * * UpdateItemExpressionSpec xspec = new ExpressionSpecBuilder() * // SET num1 = num1 + 20 * .addUpdate( * N("num1").set(N("num1").plus(20))) * // SET string-attr = "string-value" * .addUpdate( * S("string-attr").set("string-value") * ) * // num2 BETWEEN 0 AND 100 * .withCondition( * N("num2").between(0, 100) * ).buildForUpdate(); * * table.updateItem(HASH_KEY_NAME, "hashKeyValue", RANGE_KEY_NAME, 0, xspec); * </pre> * * <h3>Sample Usage 2: Conditional Updates with complex Condition Expression</h3> * <p> * Let's say you want to include a complex condition expression such as: * * <pre> * (attribute_not_exists(item_version) AND attribute_not_exists(config_id) AND attribute_not_exists(config_version)) OR * (item_version < 123) OR * (item_version = 123 AND config_id < 456) OR * (item_version = 123 AND config_id = 456 AND config_version < 999) * </pre> * * Here is how: * <p> * * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * Table table = dynamo.getTable(TABLE_NAME); * * UpdateItemExpressionSpec xspec = new ExpressionSpecBuilder() * // SET num1 = num1 + 20 * .addUpdate( * N("num1").set(N("num1").plus(20))) * // SET string-attr = "string-value" * .addUpdate( * S("string-attr").set("string-value") * ) * // a complex condition expression (as shown above) * .withCondition( * // add explicit parenthesis * parenthesize( attribute_not_exists("item_version") * .and( attribute_not_exists("config_id") ) * .and( attribute_not_exists("config_version") ) * ).or( N("item_version").lt(123) ) * .or( N("item_version").eq(123) * .and( N("config_id").lt(456) ) ) * .or( N("item_version").eq(123) * .and( N("config_id").eq(456) ) * .and( N("config_version").lt(999) )) * ).buildForUpdate(); * * table.updateItem(HASH_KEY_NAME, "hashKeyValue", RANGE_KEY_NAME, 0, xspec); * </pre> * * <h3>Sample Usage 3: Scan with Filter Expression</h3> * <p> * Without ExpressionSpecBuilder, the code (using the DynamoDB Document API) * could be something like: * * <pre class="brush: java"> * ItemCollection<?> col = table.scan( * "(#hk = :hashkeyAttrValue) AND (#rk BETWEEN :lo AND :hi)", * new NameMap().with("#hk", HASH_KEY_NAME).with("#rk", RANGE_KEY_NAME), * new ValueMap().withString(":hashkeyAttrValue", "allDataTypes") * .withInt(":lo", 1).withInt(":hi", 10)); * </pre> * * In contrast, using ExpressionSpecBuilder: * <p> * * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * ScanExpressionSpec xspec = new ExpressionSpecBuilder() * .withCondition( * S(HASH_KEY_NAME).eq("allDataTypes") * .and(N(RANGE_KEY_NAME).between(1, 10)) * ).buildForScan(); * * ItemCollection<?> col = table.scan(xspec); * </pre> * * <h3>Sample Usage 4: Updates with SET, ADD, DELETE and REMOVE</h3> * * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * Table table = dynamo.getTable(TABLE_NAME); * * UpdateItemExpressionSpec xspec = new ExpressionSpecBuilder() * .addUpdate(S("mapAttr.colors[0]").set("red")) * .addUpdate(S("mapAttr.colors[1]").set("blue")) * .addUpdate(L("mapAttr.members").set( * L("mapAttr.members").listAppend("marry", "liza"))) * .addUpdate(SS("mapAttr.countries").append("cn", "uk")) * .addUpdate(SS("mapAttr.brands").delete("Facebook", "LinkedIn")) * .addUpdate(attribute("mapAttr.foo").remove()) * .buildForUpdate(); * * assertEquals("SET #0.#1[0] = :0, #0.#1[1] = :1, #0.#2 = list_append(#0.#2, :2) ADD #0.#3 :3 DELETE #0.#4 :4 REMOVE #0.#5", * xspec.getUpdateExpression()); * * final String hashkey = "addRemoveDeleteColors"; * table.updateItem(HASH_KEY_NAME, hashkey, RANGE_KEY_NAME, 0, xspec); * </pre> * * @see PathOperand */ @Beta public final class ExpressionSpecBuilder implements Cloneable { private final Map<String, List<UpdateAction>> updates; private Condition keyCondition; private Condition condition; private final Set<PathOperand> projections; /** * Constructs a request-centric Expression Specification Builder that can be used to * construct valid expressions, and the respective name maps and value maps, for * various DynamoDB requests in a typeful manner. This includes <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >Update expression</a>, <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html" * >Condition expression</a> (including Filter expression and Key Condition * expression), and <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.AccessingItemAttributes.html" * >Projection expression</a>. This class is the API entry point to this * library. * <p> * This builder object is not thread-safe but you can reuse or build on (the * specific states of) a builder by cloning it into separate instances for use * in a concurrent environment. * <h3>Sample Usage: Query with Filter Expression</h3> * <p> * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * Table table = dynamo.getTable(TABLE_NAME); * * QueryExpressionSpec xspec = new ExpressionSpecBuilder() * .addProjections("numberAttr", "stringAttr") * .withCondition(BOOL("booleanTrue").eq(true) * .and(S("mapAttr.key1").eq("value1")) * ).buildForQuery(); * * ItemCollection<?> col = table.query(HASH_KEY_NAME, "allDataTypes", * new RangeKeyCondition("range_key_name").between(1, 10), xspec); * </pre> * * <h3>Sample Usage: Conditional Updates with Expressions</h3> * * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * Table table = dynamo.getTable(TABLE_NAME); * * UpdateItemExpressionSpec xspec = new ExpressionSpecBuilder() * // SET num1 = num1 + 20 * .addUpdate( * N("num1").set(N("num1").plus(20))) * // SET string-attr = "string-value" * .addUpdate( * S("string-attr").set("string-value") * ) * // num2 BETWEEN 0 AND 100 * .withCondition( * N("num2").between(0, 100) * ).buildForUpdate(); * * table.updateItem(HASH_KEY_NAME, "hashKeyValue", RANGE_KEY_NAME, 0, xspec); * </pre> * <h3>Sample Usage: Scan with Filter Expression</h3> * <p> * Without ExpressionSpecBuilder, the code (using the DynamoDB Document API) * could be something like: * * <pre class="brush: java"> * ItemCollection<?> col = table.scan( * "(#hk = :hashkeyAttrValue) AND (#rk BETWEEN :lo AND :hi)", * new NameMap().with("#hk", HASH_KEY_NAME).with("#rk", RANGE_KEY_NAME), * new ValueMap().withString(":hashkeyAttrValue", "allDataTypes") * .withInt(":lo", 1).withInt(":hi", 10)); * </pre> * * In contrast, using ExpressionSpecBuilder: * <p> * * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * ScanExpressionSpec xspec = new ExpressionSpecBuilder() * .withCondition( * S(HASH_KEY_NAME).eq("allDataTypes") * .and(N(RANGE_KEY_NAME).between(1, 10)) * ).buildForScan(); * * ItemCollection<?> col = table.scan(xspec); * </pre> * * <h3>Sample Usage: Conditional Updates with Expressions</h3> * * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * Table table = dynamo.getTable(TABLE_NAME); * * UpdateItemExpressionSpec xspec = new ExpressionSpecBuilder() * // SET num1 = num1 + 20 * .addUpdate( * N("num1").set(N("num1").plus(20))) * // SET string-attr = "string-value" * .addUpdate( * S("string-attr").set("string-value") * ) * // num2 BETWEEN 0 AND 100 * .withCondition( * N("num2").between(0, 100) * ).buildForUpdate(); * * table.updateItem(HASH_KEY_NAME, "hashKeyValue", RANGE_KEY_NAME, 0, xspec); * </pre> * * <h3>Sample Usage: Conditional Updates with complex Condition Expression</h3> * <p> * Let's say you want to include a complex condition expression such as: * * <pre> * (attribute_not_exists(item_version) AND attribute_not_exists(config_id) AND attribute_not_exists(config_version)) OR * (item_version < 123) OR * (item_version = 123 AND config_id < 456) OR * (item_version = 123 AND config_id = 456 AND config_version < 999) * </pre> * * Here is how: * <p> * * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * Table table = dynamo.getTable(TABLE_NAME); * * UpdateItemExpressionSpec xspec = new ExpressionSpecBuilder() * // SET num1 = num1 + 20 * .addUpdate( * N("num1").set(N("num1").plus(20))) * // SET string-attr = "string-value" * .addUpdate( * S("string-attr").set("string-value") * ) * // a complex condition expression (as shown above) * .withCondition( * // add explicit parenthesis * parenthesize( attribute_not_exists("item_version") * .and( attribute_not_exists("config_id") ) * .and( attribute_not_exists("config_version") ) * ).or( N("item_version").lt(123) ) * .or( N("item_version").eq(123) * .and( N("config_id").lt(456) ) ) * .or( N("item_version").eq(123) * .and( N("config_id").eq(456) ) * .and( N("config_version").lt(999) )) * ).buildForUpdate(); * * table.updateItem(HASH_KEY_NAME, "hashKeyValue", RANGE_KEY_NAME, 0, xspec); * </pre> * * <h3>Sample Usage: Updates with SET, ADD, DELETE and REMOVE</h3> * * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * Table table = dynamo.getTable(TABLE_NAME); * * UpdateItemExpressionSpec xspec = new ExpressionSpecBuilder() * .addUpdate(S("mapAttr.colors[0]").set("red")) * .addUpdate(S("mapAttr.colors[1]").set("blue")) * .addUpdate(L("mapAttr.members").set( * L("mapAttr.members").listAppend("marry", "liza"))) * .addUpdate(SS("mapAttr.countries").append("cn", "uk")) * .addUpdate(SS("mapAttr.brands").delete("Facebook", "LinkedIn")) * .addUpdate(attribute("mapAttr.foo").remove()) * .buildForUpdate(); * * assertEquals("SET #0.#1[0] = :0, #0.#1[1] = :1, #0.#2 = list_append(#0.#2, :2) ADD #0.#3 :3 DELETE #0.#4 :4 REMOVE #0.#5", * xspec.getUpdateExpression()); * * final String hashkey = "addRemoveDeleteColors"; * table.updateItem(HASH_KEY_NAME, hashkey, RANGE_KEY_NAME, 0, xspec); * </pre> * * @see PathOperand */ public ExpressionSpecBuilder() { this.updates = new LinkedHashMap<String, List<UpdateAction>>(); this.projections = new LinkedHashSet<PathOperand>(); } private ExpressionSpecBuilder(ExpressionSpecBuilder from) { this.updates = new LinkedHashMap<String, List<UpdateAction>>(from.updates); this.projections = new LinkedHashSet<PathOperand>(from.projections); this.keyCondition = from.keyCondition; this.condition = from.condition; } /** * Fluent API to add the given Update expression for a request. * <p> * For example: * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * builder * // SET num1 = num1 + 20 * .addUpdate( * N("num1").set(N("num1").plus(20))) * // SET string-attr = "string-value" * .addUpdate( * S("string-attr").set("string-value") * ) */ public ExpressionSpecBuilder addUpdate(UpdateAction updateAction) { final String operator = updateAction.getOperator(); List<UpdateAction> list = updates.get(operator); if (list == null) { list = new LinkedList<UpdateAction>(); updates.put(operator, list); } list.add(updateAction); return this; } /** * Fluent API to set the condition expression for a request. * <p> * For example: * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * builder.withCondition( * // num2 BETWEEN 0 AND 100 * ExpressionSpecBuilder.N("num2").between(0, 100) * ) * ... * </pre> * Example of specifying a complex condition: * <pre class="brush: java"> * import static com.amazonaws.services.dynamodbv2.xspec.ExpressionSpecBuilder.*; * ... * // A complex condition expression: * // * // (attribute_not_exists(item_version) AND attribute_not_exists(config_id) AND attribute_not_exists(config_version)) OR * // (item_version < 123) OR * // (item_version = 123 AND config_id < 456) OR * // (item_version = 123 AND config_id = 456 AND config_version < 999) * // * builder.withCondition( * // add explicit parenthesis * parenthesize( attribute_not_exists("item_version") * .and( attribute_not_exists("config_id") ) * .and( attribute_not_exists("config_version") ) * ).or( N("item_version").lt(123) ) * .or( N("item_version").eq(123) * .and( N("config_id").lt(456) ) ) * .or( N("item_version").eq(123) * .and( N("config_id").eq(456) ) * .and( N("config_version").lt(999) )) * ) * ... * </pre> */ public ExpressionSpecBuilder withCondition(Condition condition) { this.condition = condition; return this; } public ExpressionSpecBuilder withKeyCondition(Condition keyCondition) { this.keyCondition = keyCondition; return this; } /** * Fluent API to add the given attribute to the list of projection of a request. * For example: * <pre class="brush: java"> * builder.addProjection("binarySetAttribute") * .addProjection("listAttr[0]") * .addProjection("mapAttr.name") * .addProjection("stringSetAttr") * ; * </pre> */ public ExpressionSpecBuilder addProjection(String path) { projections.add(new PathOperand(path)); return this; } /** * Fluent API to add the given attributes to the list of projection of a request. * For example: * <pre class="brush: java"> * builder.addProjections("binarySetAttribute", "listAttr[0]", "mapAttr.name", "stringSetAttr"); * </pre> */ public ExpressionSpecBuilder addProjections(String... paths) { for (String path : paths) addProjection(path); return this; } /** * Returns an expression specification for use in a <code>DeleteItem</code> * request to DynamoDB. */ public DeleteItemExpressionSpec buildForDeleteItem() { return new DeleteItemExpressionSpec(this); } /** * Returns an expression specification for use in a <code>GetItem</code> * request to DynamoDB. */ public GetItemExpressionSpec buildForGetItem() { return new GetItemExpressionSpec(this); } /** * Returns an expression specification for use in a query * request to DynamoDB. */ public QueryExpressionSpec buildForQuery() { return new QueryExpressionSpec(this); } /** * Returns an expression specification for use in a scan * request to DynamoDB. */ public ScanExpressionSpec buildForScan() { return new ScanExpressionSpec(this); } /** * Returns an expression specification for use in an <code>UpdateItem</code> * request to DynamoDB. */ public UpdateItemExpressionSpec buildForUpdate() { return new UpdateItemExpressionSpec(this); } /** * Returns an expression specification for use in a <code>PutItem</code> * request to DynamoDB. */ public PutItemExpressionSpec buildForPut() { return new PutItemExpressionSpec(this); } /** * Builds and returns the update expression to be used in a dynamodb * request; or null if there is none. */ String buildUpdateExpression(SubstitutionContext context) { StringBuilder sb = new StringBuilder(); for (Map.Entry<String, List<UpdateAction>> e : updates.entrySet()) { boolean firstOfUpdateType = true; for (UpdateAction expr : e.getValue()) { if (firstOfUpdateType) { firstOfUpdateType = false; final String operator = e.getKey(); if (sb.length() > 0) sb.append(" "); sb.append(operator).append(" "); } else { sb.append(", "); } sb.append(expr.asSubstituted(context)); } } return sb.toString(); } /** * Builds and returns the projection expression to be used in a dynamodb * GetItem request; or null if there is none. */ String buildProjectionExpression(SubstitutionContext context) { if (projections.size() == 0) return null; StringBuilder sb = new StringBuilder(); for (PathOperand projection : projections) { if (sb.length() > 0) sb.append(", "); sb.append(projection.asSubstituted(context)); } return sb.toString(); } /** * Builds and returns the condition expression to be used in a dynamodb * request; or null if there is none. */ String buildConditionExpression(SubstitutionContext context) { return condition == null ? null : condition.asSubstituted(context); } /** * Builds and returns the key condition expression to be used in a dynamodb * query request; or null if there is none. */ String buildKeyConditionExpression(SubstitutionContext context) { return keyCondition == null ? null : keyCondition.asSubstituted(context); } @Override public ExpressionSpecBuilder clone() { return new ExpressionSpecBuilder(this); } ////////////// static factory methods ////////////// /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param pathOperand * path operand that refers to the attribute * @param operand * default value if the attribute doesn't exist */ static <T> IfNotExistsFunction<T> if_not_exists(PathOperand pathOperand, Operand operand) { return new IfNotExistsFunction<T>(pathOperand, operand); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for number (N) attribute. */ public static IfNotExistsFunction<N> if_not_exists(String path, Number defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for binary (B) attribute. */ public static IfNotExistsFunction<B> if_not_exists(String path, byte[] defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for binary (B) attribute. */ public static IfNotExistsFunction<B> if_not_exists(String path, ByteBuffer defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for boolean (BOOL) attribute. */ public static IfNotExistsFunction<BOOL> if_not_exists(String path, boolean defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for binary set (BS) attribute. */ public static IfNotExistsFunction<BS> if_not_exists(String path, byte[]... defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for binary set (BS) attribute. */ public static IfNotExistsFunction<BS> if_not_exists(String path, ByteBuffer... defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for list (L) attribute. */ public static IfNotExistsFunction<L> if_not_exists(String path, List<?> defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for map (M) attribute. */ public static IfNotExistsFunction<M> if_not_exists(String path, Map<String, ?> defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for number set (NS) attribute. */ public static IfNotExistsFunction<NS> if_not_exists(String path, Number... defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for string (S) attribute. */ public static IfNotExistsFunction<S> if_not_exists(String path, String defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns an <code>IfNotExists</code> object which represents an <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >if_not_exists(path, operand)</a> function call; used for building * expression. * * <pre> * "if_not_exists (path, operand) If the item does not contain an attribute * at the specified path, then if_not_exists evaluates to operand; otherwise, * it evaluates to path. You can use this function to avoid overwriting an * attribute already present in the item." * </pre> * * @param path * document path to an attribute * @param defaultValue * default value if the attribute doesn't exist * * @return an <code>IfNotExists</code> object for string set (SS) attribute. */ public static IfNotExistsFunction<SS> if_not_exists(String path, String... defaultValue) { return if_not_exists(new PathOperand(path), new LiteralOperand(defaultValue)); } /** * Returns a <code>ListAppend</code> object which represents a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >list_append(operand, operand)</a> function call; used for building * expression. * * <pre> * "list_append(operand, operand) This function evaluates to a list with a * new element added to it. You can append the new element to the start or * the end of the list by reversing the order of the operands." * </pre> * * @param path * document path to a list attribute * @param value * single value to be appended to the list attribute */ public static <T> ListAppendFunction list_append(String path, T value) { LinkedList<T> list = new LinkedList<T>(); list.add(value); return list_append(path, list); } /** * Returns a <code>ListAppend</code> object which represents a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >list_append(operand, operand)</a> function call; used for building * expression. * * <pre> * "list_append(operand, operand) This function evaluates to a list with a * new element added to it. You can append the new element to the start or * the end of the list by reversing the order of the operands." * </pre> * * @param path * document path to a list attribute * @param value * list of values to be appended to the list attribute */ public static <T> ListAppendFunction list_append(String path, List<? extends T> value) { return new ListAppendFunction(L(path), new ListLiteralOperand(new LinkedList<T>(value))); } /** * Returns a <code>ListAppend</code> object which represents a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Modifying.html" * >list_append(operand, operand)</a> function call; used for building * expression. * * <pre> * "list_append(operand, operand) This function evaluates to a list with a * new element added to it. You can append the new element to the start or * the end of the list by reversing the order of the operands." * </pre> * * @param value * list of values to be appended to * @param path * document path to a list attribute */ public static <T> ListAppendFunction list_append(List<? extends T> value, String path) { return new ListAppendFunction(new ListLiteralOperand(new LinkedList<T>(value)), L(path)); } // ///////////////////////// FunctionCondition factory methods /** * Returns a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html#ConditionExpressionReference.Functions" * >function condition</a> (that evaluates to true if the attribute of the * specified path operand exists) for building condition expression. */ public static <T> FunctionCondition attribute_exists(PathOperand pathOperand) { return new FunctionCondition("attribute_exists", pathOperand); } /** * Returns a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html#ConditionExpressionReference.Functions" * >function condition</a> (that evaluates to true if the attribute at the * specified path exists) for building condition expression. */ public static <T> FunctionCondition attribute_exists(String path) { return attribute_exists(new PathOperand(path)); } /** * Returns a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html#ConditionExpressionReference.Functions" * >function condition</a> (that evaluates to true if the attribute of the * specified path operand does not exist) for building condition expression. */ public static FunctionCondition attribute_not_exists(PathOperand pathOperand) { return new FunctionCondition("attribute_not_exists", pathOperand); } /** * Returns a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html#ConditionExpressionReference.Functions" * >function condition</a> (that evaluates to true if the attribute at the * specified path does not exist) for building condition expression. */ public static FunctionCondition attribute_not_exists(String path) { return attribute_not_exists(new PathOperand(path)); } /** * Returns a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html#ConditionExpressionReference.Functions" * >negation</a> of the specified condition; used for building condition * expression. */ public static <T> NegationCondition not(Condition cond) { return new NegationCondition(cond); } /** * Returns a <code>RemoveAction</code> for removing the attribute with the * specified path from an item; used for building update expression. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static RemoveAction remove(String path) { return new PathOperand(path).remove(); } /** * Returns a path operand that refers to an attribute of some unspecified * <a href="http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html">data type</a>; used for building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static PathOperand attribute(String path) { return new PathOperand(path); } /** * Creates a path operand that refers to a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html" * >boolean attribute</a> for the purpose of building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static BOOL BOOL(String path) { return new BOOL(path); } /** * Creates a path operand that refers to a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html" * >NULL attribute</a> for the purpose of building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static NULL NULL(String path) { return new NULL(path); } /** * Creates a path operand that refers to a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html" * >binary attribute</a> for the purpose of building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static B B(String path) { return new B(path); } /** * Creates a path operand that refers to a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html" * >number attribute</a> for the purpose of building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static N N(String path) { return new N(path); } /** * Creates a path operand that refers to a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html" * >string attribute</a> for the purpose of building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static S S(String path) { return new S(path); } /** * Creates a path operand that refers to a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html" * >binary-set attribute</a> for the purpose of building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static BS BS(String path) { return new BS(path); } /** * Creates a path operand that refers to a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html" * >number-set attribute</a> for the purpose of building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static NS NS(String path) { return new NS(path); } /** * Creates a path operand that refers to a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html" * >string-set attribute</a> for the purpose of building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static SS SS(String path) { return new SS(path); } /** * Creates a path operand that refers to a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html" * >list attribute</a> for the purpose of building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static L L(String path) { return new L(path); } /** * Creates a path operand that refers to a <a href= * "http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html" * >map attribute</a> for the purpose of building expressions. * * @param path * the document path to the attribute, where nested path elements * are assumed to be delimited by either "." or array indexing * such as "[1]". */ public static M M(String path) { return new M(path); } /** * Returns an explicitly parenthesized condition, ie '(' condition ')' used * in building condition expressions. * * @see #_(Condition) */ public static <T> ParenthesizedCondition parenthesize(Condition condition) { return ParenthesizedCondition.getInstance(condition); } /** * A short hand for calling {@link #parenthesize(Condition)} to explicitly * parenthesize a given condition for building condition expressions. */ public static <T> ParenthesizedCondition _(Condition condition) { return parenthesize(condition); } }