+ * Each builder takes an {@code Exp src} that produces the string to operate on. + * Common sources: + *
+ * Modify-style expressions (e.g. {@link #upper}, {@link #replace}) return the + * modified string value; they do not mutate the underlying bin. + * To persist a change, write the returned value back via + * {@link com.aerospike.client.exp.Exp.Build} or use + * {@link com.aerospike.client.operation.StringOperation} for direct ops. + *
+ * Index orientation is left-to-right with codepoint addressing. Negative indexes + * count from the end of the string ({@code -1} = last codepoint). Out-of-bounds + * indexes are clamped to the valid range; no error is returned. + *
+ * Unlike {@link com.aerospike.client.operation.StringOperation}, these builders + * do not accept a {@link com.aerospike.client.cdt.CTX}. To apply + * a string expression to a value nested inside a list or map, compose with + * {@link com.aerospike.client.exp.ListExp#getByIndex} or + * {@link com.aerospike.client.exp.MapExp#getByKey} (which do take CTX) to extract + * the leaf, then pass the resulting {@code Exp} as {@code src}. + *
+ * String expressions require server version 8.1.3 or later. + * + *
{@code
+ * // Filter records whose "name" bin starts with "hello".
+ * Expression filter = Exp.build(
+ * Exp.eq(
+ * StringExp.startsWith(Exp.val("hello"), Exp.stringBin("name")),
+ * Exp.val(1)));
+ * }
+ */
+public final class StringExp {
+ private static final int MODULE = 3; // CALL_STRING
+ private static final int MODULE_REPR = 4; // CALL_REPR
+
+ // Read ops
+ private static final int STRLEN = 0;
+ private static final int SUBSTR = 1;
+ private static final int CHAR_AT = 2;
+ private static final int FIND = 3;
+ private static final int CONTAINS = 4;
+ private static final int STARTS_WITH = 5;
+ private static final int ENDS_WITH = 6;
+ private static final int TO_INTEGER = 7;
+ private static final int TO_DOUBLE = 8;
+ private static final int BYTE_LENGTH = 9;
+ private static final int IS_NUMERIC = 10;
+ private static final int IS_UPPER = 11;
+ private static final int IS_LOWER = 12;
+ private static final int TO_BLOB = 13;
+ private static final int SPLIT = 14;
+ private static final int B64_DECODE = 15;
+ private static final int REGEX_COMPARE = 16;
+
+ // Modify ops
+ private static final int INSERT = 50;
+ private static final int OVERWRITE = 51;
+ private static final int CONCAT = 52;
+ private static final int SNIP = 53;
+ private static final int REPLACE = 54;
+ private static final int REPLACE_ALL = 55;
+ private static final int UPPER = 56;
+ private static final int LOWER = 57;
+ private static final int CASE_FOLD = 58;
+ private static final int NORMALIZE_NFC = 59;
+ private static final int TRIM_START = 60;
+ private static final int TRIM_END = 61;
+ private static final int TRIM = 62;
+ private static final int PAD_START = 63;
+ private static final int PAD_END = 64;
+ private static final int REPEAT = 65;
+ private static final int REGEX_REPLACE = 66;
+
+ //-----------------------------------------------------------------
+ // Read expressions
+ //-----------------------------------------------------------------
+
+ /**
+ * Create expression that returns the number of Unicode codepoints in {@code src}
+ * as an int64. Equivalent to {@link String#codePointCount(int, int)} on the source.
+ * + * The returned value is the codepoint count — not the count of + * user-perceived characters (grapheme clusters). They agree for ASCII / simple + * Latin text but diverge for combining marks, emoji modifiers, and ZWJ sequences + * (see {@link com.aerospike.client.operation.StringOperation#strlen} for examples). + * For UTF-8 byte length, use {@link #byteLength(Exp)}. + * + *
{@code
+ * // "hello world" -> 11
+ * Exp len = StringExp.strlen(Exp.stringBin("text"));
+ * }
+ *
+ * @param src source string expression
+ * @return integer-typed expression yielding the codepoint count
+ */
+ public static Exp strlen(Exp src) {
+ byte[] bytes = Pack.pack(STRLEN);
+ return addRead(src, bytes, Exp.Type.INT);
+ }
+
+ /**
+ * Create expression that returns the substring of {@code src} from codepoint
+ * {@code start} to the end. Negative {@code start} counts from the end of the
+ * string.
+ *
+ * {@code
+ * // "hello world" from 6 -> "world"
+ * Exp tail = StringExp.substr(Exp.val(6), Exp.stringBin("text"));
+ * }
+ *
+ * @param start starting codepoint index (negative counts from end)
+ * @param src source string expression
+ * @return string-typed expression yielding the substring
+ */
+ public static Exp substr(Exp start, Exp src) {
+ byte[] bytes = Pack.pack(SUBSTR, start);
+ return addRead(src, bytes, Exp.Type.STRING);
+ }
+
+ /**
+ * Create expression that returns {@code length} codepoints of {@code src} starting
+ * at codepoint {@code start}. Negative indexes count from the end.
+ *
+ * {@code
+ * // "hello world" from 0, length 5 -> "hello"
+ * Exp head = StringExp.substr(Exp.val(0), Exp.val(5), Exp.stringBin("text"));
+ * }
+ *
+ * @param start starting codepoint index (negative counts from end)
+ * @param length number of codepoints to read (clamped to remaining length)
+ * @param src source string expression
+ * @return string-typed expression yielding the substring
+ */
+ public static Exp substr(Exp start, Exp length, Exp src) {
+ byte[] bytes = Pack.pack(SUBSTR, start, length);
+ return addRead(src, bytes, Exp.Type.STRING);
+ }
+
+ /**
+ * Create expression that returns the codepoint at {@code index} of {@code src}
+ * as a one-codepoint string. Negative indexes count from the end.
+ *
+ * {@code
+ * // "Hello123World" at 5 -> "1"
+ * Exp c = StringExp.charAt(Exp.val(5), Exp.stringBin("text"));
+ * }
+ *
+ * @param index codepoint index (negative counts from end)
+ * @param src source string expression
+ * @return string-typed expression yielding a single-codepoint string
+ */
+ public static Exp charAt(Exp index, Exp src) {
+ byte[] bytes = Pack.pack(CHAR_AT, index);
+ return addRead(src, bytes, Exp.Type.STRING);
+ }
+
+ /**
+ * Create expression that returns the codepoint index of the first occurrence of
+ * {@code needle} in {@code src}, or {@code -1} if not found.
+ *
+ * {@code
+ * // "hello world" find "world" -> 6
+ * Exp idx = StringExp.find(Exp.val("world"), Exp.stringBin("text"));
+ * }
+ *
+ * @param needle substring to search for (any expression yielding a string)
+ * @param src source string expression
+ * @return integer-typed expression: codepoint index, or -1 if absent
+ */
+ public static Exp find(Exp needle, Exp src) {
+ byte[] bytes = Pack.pack(FIND, needle);
+ return addRead(src, bytes, Exp.Type.INT);
+ }
+
+ /**
+ * Create expression that returns the codepoint index of the {@code occurrence}-th
+ * match of {@code needle} ({@code 1} = first, {@code -1} = last), or {@code -1}
+ * if not found.
+ *
+ * {@code
+ * // "ababab" 2nd occurrence of "ab" -> 2
+ * Exp idx = StringExp.find(Exp.val("ab"), Exp.val(2), Exp.stringBin("text"));
+ * }
+ *
+ * @param needle substring to search for
+ * @param occurrence 1-based occurrence to return (negative counts from the last)
+ * @param src source string expression
+ * @return integer-typed expression: codepoint index, or -1 if absent
+ */
+ public static Exp find(Exp needle, Exp occurrence, Exp src) {
+ byte[] bytes = Pack.pack(FIND, needle, occurrence);
+ return addRead(src, bytes, Exp.Type.INT);
+ }
+
+ /**
+ * Create expression that tests whether {@code src} contains {@code needle} as a
+ * substring. Returns an integer flag: {@code 1} on match, {@code 0} otherwise.
+ *
+ * {@code
+ * Expression filter = Exp.build(Exp.eq(
+ * StringExp.contains(Exp.val("hello"), Exp.stringBin("text")),
+ * Exp.val(1)));
+ * }
+ *
+ * @param needle substring to test for
+ * @param src source string expression
+ * @return integer-typed expression: 1 on match, 0 otherwise
+ */
+ public static Exp contains(Exp needle, Exp src) {
+ byte[] bytes = Pack.pack(CONTAINS, needle);
+ return addRead(src, bytes, Exp.Type.BOOL);
+ }
+
+ /**
+ * Create expression that tests whether {@code src} begins with {@code prefix}.
+ * Returns an integer flag: {@code 1} on match, {@code 0} otherwise.
+ *
+ * {@code
+ * Exp matched = StringExp.startsWith(Exp.val("Hello"), Exp.stringBin("text"));
+ * }
+ *
+ * @param prefix prefix to test for
+ * @param src source string expression
+ * @return integer-typed expression: 1 on match, 0 otherwise
+ */
+ public static Exp startsWith(Exp prefix, Exp src) {
+ byte[] bytes = Pack.pack(STARTS_WITH, prefix);
+ return addRead(src, bytes, Exp.Type.BOOL);
+ }
+
+ /**
+ * Create expression that tests whether {@code src} ends with {@code suffix}.
+ * Returns an integer flag: {@code 1} on match, {@code 0} otherwise.
+ *
+ * {@code
+ * Exp matched = StringExp.endsWith(Exp.val("World"), Exp.stringBin("text"));
+ * }
+ *
+ * @param suffix suffix to test for
+ * @param src source string expression
+ * @return integer-typed expression: 1 on match, 0 otherwise
+ */
+ public static Exp endsWith(Exp suffix, Exp src) {
+ byte[] bytes = Pack.pack(ENDS_WITH, suffix);
+ return addRead(src, bytes, Exp.Type.BOOL);
+ }
+
+ /**
+ * Create expression that parses {@code src} as an int64. The expression returns
+ * an error if the source cannot be parsed as an integer.
+ *
+ * {@code
+ * // "12345" -> 12345
+ * Exp n = StringExp.toInteger(Exp.stringBin("text"));
+ * }
+ *
+ * @param src source string expression
+ * @return integer-typed expression yielding the parsed int64
+ */
+ public static Exp toInteger(Exp src) {
+ byte[] bytes = Pack.pack(TO_INTEGER);
+ return addRead(src, bytes, Exp.Type.INT);
+ }
+
+ /**
+ * Create expression that parses {@code src} as a 64-bit float. The expression
+ * returns an error if the source cannot be parsed as a double.
+ *
+ * {@code
+ * // "3.14" -> 3.14
+ * Exp v = StringExp.toDouble(Exp.stringBin("text"));
+ * }
+ *
+ * @param src source string expression
+ * @return float-typed expression yielding the parsed double
+ */
+ public static Exp toDouble(Exp src) {
+ byte[] bytes = Pack.pack(TO_DOUBLE);
+ return addRead(src, bytes, Exp.Type.FLOAT);
+ }
+
+ /**
+ * Create expression that returns the UTF-8 byte length of {@code src} as an int64.
+ * Differs from {@link #strlen} for non-ASCII content where one codepoint can encode
+ * to multiple bytes.
+ *
+ * {@code
+ * // "hello" -> 5
+ * Exp len = StringExp.byteLength(Exp.stringBin("text"));
+ * }
+ *
+ * @param src source string expression
+ * @return integer-typed expression yielding the UTF-8 byte length
+ */
+ public static Exp byteLength(Exp src) {
+ byte[] bytes = Pack.pack(BYTE_LENGTH);
+ return addRead(src, bytes, Exp.Type.INT);
+ }
+
+ /**
+ * Create expression that tests whether {@code src} contains a valid integer or
+ * float literal. Returns an integer flag: {@code 1} on match, {@code 0} otherwise.
+ *
+ * {@code
+ * Exp numeric = StringExp.isNumeric(Exp.stringBin("text"));
+ * }
+ *
+ * @param src source string expression
+ * @return integer-typed expression: 1 if numeric, 0 otherwise
+ */
+ public static Exp isNumeric(Exp src) {
+ byte[] bytes = Pack.pack(IS_NUMERIC);
+ return addRead(src, bytes, Exp.Type.BOOL);
+ }
+
+ /**
+ * Create expression that tests whether {@code src} parses as a number of the
+ * requested {@link com.aerospike.client.operation.StringNumericType}. Returns an
+ * integer flag: {@code 1} on match, {@code 0} otherwise.
+ *
+ * {@code
+ * // restrict to integer-only validation
+ * Exp isInt = StringExp.isNumeric(StringNumericType.INT, Exp.stringBin("text"));
+ * }
+ *
+ * @param numericType one of the {@link com.aerospike.client.operation.StringNumericType} constants
+ * @param src source string expression
+ * @return integer-typed expression: 1 if numeric of the given type, 0 otherwise
+ */
+ public static Exp isNumeric(int numericType, Exp src) {
+ byte[] bytes = Pack.pack(IS_NUMERIC, numericType);
+ return addRead(src, bytes, Exp.Type.BOOL);
+ }
+
+ /**
+ * Create expression that tests whether every cased codepoint in {@code src} is
+ * uppercase. Returns an integer flag: {@code 1} on match, {@code 0} otherwise.
+ *
+ * {@code
+ * Exp upper = StringExp.isUpper(Exp.stringBin("text"));
+ * }
+ *
+ * @param src source string expression
+ * @return integer-typed expression: 1 if all-uppercase, 0 otherwise
+ */
+ public static Exp isUpper(Exp src) {
+ byte[] bytes = Pack.pack(IS_UPPER);
+ return addRead(src, bytes, Exp.Type.BOOL);
+ }
+
+ /**
+ * Create expression that tests whether every cased codepoint in {@code src} is
+ * lowercase. Returns an integer flag: {@code 1} on match, {@code 0} otherwise.
+ *
+ * {@code
+ * Exp lower = StringExp.isLower(Exp.stringBin("text"));
+ * }
+ *
+ * @param src source string expression
+ * @return integer-typed expression: 1 if all-lowercase, 0 otherwise
+ */
+ public static Exp isLower(Exp src) {
+ byte[] bytes = Pack.pack(IS_LOWER);
+ return addRead(src, bytes, Exp.Type.BOOL);
+ }
+
+ /**
+ * Create expression that returns the UTF-8 bytes of {@code src} as a blob.
+ *
+ * {@code
+ * // "hello" -> [0x68, 0x65, 0x6c, 0x6c, 0x6f]
+ * Exp blob = StringExp.toBlob(Exp.stringBin("text"));
+ * }
+ *
+ * @param src source string expression
+ * @return blob-typed expression yielding the UTF-8 byte array
+ */
+ public static Exp toBlob(Exp src) {
+ byte[] bytes = Pack.pack(TO_BLOB);
+ return addRead(src, bytes, Exp.Type.BLOB);
+ }
+
+ /**
+ * Create expression that splits {@code src} by Unicode codepoint — each codepoint
+ * becomes its own list element.
+ *
+ * {@code
+ * // "abc" -> ["a", "b", "c"]
+ * Exp parts = StringExp.split(Exp.stringBin("text"));
+ * }
+ *
+ * @param src source string expression
+ * @return list-typed expression yielding a list of single-codepoint strings
+ */
+ public static Exp split(Exp src) {
+ byte[] bytes = Pack.pack(SPLIT);
+ return addRead(src, bytes, Exp.Type.LIST);
+ }
+
+ /**
+ * Create expression that splits {@code src} by the {@code separator} substring.
+ * If the separator is absent, the result is a singleton list containing the whole
+ * source.
+ *
+ * {@code
+ * // "one,two,three" with "," -> ["one", "two", "three"]
+ * Exp tokens = StringExp.split(Exp.val(","), Exp.stringBin("text"));
+ * }
+ *
+ * @param separator substring used to split the source
+ * @param src source string expression
+ * @return list-typed expression yielding the token list
+ */
+ public static Exp split(Exp separator, Exp src) {
+ byte[] bytes = Pack.pack(SPLIT, separator);
+ return addRead(src, bytes, Exp.Type.LIST);
+ }
+
+ /**
+ * Create expression that base64-decodes {@code src} and returns the decoded
+ * bytes as a blob.
+ *
+ * {@code
+ * // "aGVsbG8=" -> "hello".getBytes()
+ * Exp decoded = StringExp.b64Decode(Exp.stringBin("text"));
+ * }
+ *
+ * @param src source string expression holding base64 text
+ * @return blob-typed expression yielding the decoded bytes
+ */
+ public static Exp b64Decode(Exp src) {
+ byte[] bytes = Pack.pack(B64_DECODE);
+ return addRead(src, bytes, Exp.Type.BLOB);
+ }
+
+ /**
+ * Create expression that tests whether {@code pattern} (ICU regex syntax) matches
+ * {@code src}. Returns an integer flag: {@code 1} on match, {@code 0} otherwise.
+ *
+ * {@code
+ * // matches if "text" contains any digit run
+ * Exp matched = StringExp.regexCompare(Exp.val("[0-9]+"), Exp.stringBin("text"));
+ * }
+ *
+ * @param pattern ICU-syntax regex pattern (must be valid UTF-8)
+ * @param src source string expression
+ * @return integer-typed expression: 1 on match, 0 otherwise
+ */
+ public static Exp regexCompare(Exp pattern, Exp src) {
+ byte[] bytes = Pack.pack(REGEX_COMPARE, pattern);
+ return addRead(src, bytes, Exp.Type.BOOL);
+ }
+
+ /**
+ * Create expression that tests whether {@code pattern} matches {@code src} under
+ * the supplied {@link StringRegexFlags}. Flags can be combined with bitwise OR.
+ * Returns an integer flag: {@code 1} on match, {@code 0} otherwise.
+ *
+ * {@code
+ * Exp matched = StringExp.regexCompare(
+ * Exp.val("hello"), StringRegexFlags.CASE_INSENSITIVE,
+ * Exp.stringBin("text"));
+ * }
+ *
+ * @param pattern ICU-syntax regex pattern (must be valid UTF-8)
+ * @param regexFlags bitwise-OR of {@link StringRegexFlags} constants
+ * @param src source string expression
+ * @return integer-typed expression: 1 on match, 0 otherwise
+ */
+ public static Exp regexCompare(Exp pattern, int regexFlags, Exp src) {
+ byte[] bytes = Pack.pack(REGEX_COMPARE, pattern, regexFlags);
+ return addRead(src, bytes, Exp.Type.BOOL);
+ }
+
+ //-----------------------------------------------------------------
+ // Modify expressions
+ //-----------------------------------------------------------------
+
+ /**
+ * Create expression that splices {@code value} into {@code src} at codepoint
+ * {@code index} and returns the resulting string. Negative indexes count from the
+ * end. Does not modify the underlying bin.
+ *
+ * {@code
+ * // "hello world" insert " beautiful" at 5 -> "hello beautiful world"
+ * Exp out = StringExp.insert(StringPolicy.Default,
+ * Exp.val(5), Exp.val(" beautiful"), Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param index codepoint index at which to insert (negative counts from end)
+ * @param value text to insert
+ * @param src source string expression
+ * @return string-typed expression yielding the modified string
+ */
+ public static Exp insert(StringPolicy policy, Exp index, Exp value, Exp src) {
+ byte[] bytes = Pack.pack(INSERT, index, value, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that overwrites codepoints in {@code src} starting at codepoint
+ * {@code index} with {@code value}, returning the resulting string. The result may
+ * grow beyond the original length when {@code value} extends past the end. Does not
+ * modify the underlying bin.
+ *
+ * {@code
+ * // "hello world" overwrite "earth" at 6 -> "hello earth"
+ * Exp out = StringExp.overwrite(StringPolicy.Default,
+ * Exp.val(6), Exp.val("earth"), Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param index codepoint index at which to start overwriting
+ * @param value text to write
+ * @param src source string expression
+ * @return string-typed expression yielding the modified string
+ */
+ public static Exp overwrite(StringPolicy policy, Exp index, Exp value, Exp src) {
+ byte[] bytes = Pack.pack(OVERWRITE, index, value, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that concatenates {@code values} (a list of strings) onto
+ * {@code src} in order, returning the resulting string. Does not modify the
+ * underlying bin.
+ *
+ * {@code
+ * // "hello" + [" ", "big", " world"] -> "hello big world"
+ * Exp out = StringExp.concat(StringPolicy.Default,
+ * Exp.val(Arrays.asList(" ", "big", " world")),
+ * Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param values expression yielding a list of strings to append
+ * @param src source string expression
+ * @return string-typed expression yielding the modified string
+ */
+ public static Exp concat(StringPolicy policy, Exp values, Exp src) {
+ byte[] bytes = Pack.pack(CONCAT, values, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that removes codepoints from {@code src} starting at codepoint
+ * {@code start} through the end, returning the resulting string. Does not modify
+ * the underlying bin.
+ *
+ * {@code
+ * // "hello world" snip from 5 -> "hello"
+ * Exp out = StringExp.snip(StringPolicy.Default,
+ * Exp.val(5), Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param start first codepoint to remove (inclusive)
+ * @param src source string expression
+ * @return string-typed expression yielding the modified string
+ */
+ public static Exp snip(StringPolicy policy, Exp start, Exp src) {
+ byte[] bytes = Pack.pack(SNIP, start, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that removes the half-open codepoint range {@code [start, end)}
+ * from {@code src} and returns the resulting string. Does not modify the underlying
+ * bin.
+ *
+ * {@code
+ * // "hello beautiful world" snip [5, 15) -> "hello world"
+ * Exp out = StringExp.snip(StringPolicy.Default,
+ * Exp.val(5), Exp.val(15), Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param start first codepoint to remove (inclusive)
+ * @param end one past the last codepoint to remove (exclusive)
+ * @param src source string expression
+ * @return string-typed expression yielding the modified string
+ */
+ public static Exp snip(StringPolicy policy, Exp start, Exp end, Exp src) {
+ byte[] bytes = Pack.pack(SNIP, start, end, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that replaces the first occurrence of {@code needle} in
+ * {@code src} with {@code replacement} and returns the resulting string. Does not
+ * modify the underlying bin.
+ *
+ * {@code
+ * // "hello world world" replace "world"->"earth" -> "hello earth world"
+ * Exp out = StringExp.replace(StringPolicy.Default,
+ * Exp.val("world"), Exp.val("earth"), Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param needle substring to find
+ * @param replacement text to substitute (may be empty to delete the match)
+ * @param src source string expression
+ * @return string-typed expression yielding the modified string
+ */
+ public static Exp replace(StringPolicy policy, Exp needle, Exp replacement, Exp src) {
+ byte[] bytes = packReplace(REPLACE, needle, replacement, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that replaces every occurrence of {@code needle} in {@code src}
+ * with {@code replacement} and returns the resulting string. Does not modify the
+ * underlying bin.
+ *
+ * {@code
+ * // "aabaa" replaceAll "a"->"x" -> "xxbxx"
+ * Exp out = StringExp.replaceAll(StringPolicy.Default,
+ * Exp.val("a"), Exp.val("x"), Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param needle substring to find
+ * @param replacement text to substitute (may be empty to delete each match)
+ * @param src source string expression
+ * @return string-typed expression yielding the modified string
+ */
+ public static Exp replaceAll(StringPolicy policy, Exp needle, Exp replacement, Exp src) {
+ byte[] bytes = packReplace(REPLACE_ALL, needle, replacement, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that returns {@code src} uppercased. Does not modify the
+ * underlying bin.
+ *
+ * {@code
+ * Exp out = StringExp.upper(StringPolicy.Default, Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param src source string expression
+ * @return string-typed expression yielding the uppercased string
+ */
+ public static Exp upper(StringPolicy policy, Exp src) {
+ byte[] bytes = Pack.pack(UPPER, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that returns {@code src} lowercased. Does not modify the
+ * underlying bin.
+ *
+ * {@code
+ * Exp out = StringExp.lower(StringPolicy.Default, Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param src source string expression
+ * @return string-typed expression yielding the lowercased string
+ */
+ public static Exp lower(StringPolicy policy, Exp src) {
+ byte[] bytes = Pack.pack(LOWER, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that returns {@code src} case-folded (locale-independent
+ * lowercase). Useful for normalized comparison keys. Does not modify the underlying
+ * bin.
+ *
+ * {@code
+ * Exp out = StringExp.caseFold(StringPolicy.Default, Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param src source string expression
+ * @return string-typed expression yielding the case-folded string
+ */
+ public static Exp caseFold(StringPolicy policy, Exp src) {
+ byte[] bytes = Pack.pack(CASE_FOLD, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that returns {@code src} normalized to Unicode NFC form.
+ * Already-normalized strings are unchanged. Does not modify the underlying bin.
+ *
+ * {@code
+ * Exp out = StringExp.normalizeNFC(StringPolicy.Default, Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param src source string expression
+ * @return string-typed expression yielding the NFC-normalized string
+ */
+ public static Exp normalizeNFC(StringPolicy policy, Exp src) {
+ byte[] bytes = Pack.pack(NORMALIZE_NFC, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that returns {@code src} with whitespace removed from the start.
+ * Does not modify the underlying bin.
+ *
+ * {@code
+ * // " hello " -> "hello "
+ * Exp out = StringExp.trimStart(StringPolicy.Default, Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param src source string expression
+ * @return string-typed expression yielding the left-trimmed string
+ */
+ public static Exp trimStart(StringPolicy policy, Exp src) {
+ byte[] bytes = Pack.pack(TRIM_START, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that returns {@code src} with whitespace removed from the end.
+ * Does not modify the underlying bin.
+ *
+ * {@code
+ * // " hello " -> " hello"
+ * Exp out = StringExp.trimEnd(StringPolicy.Default, Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param src source string expression
+ * @return string-typed expression yielding the right-trimmed string
+ */
+ public static Exp trimEnd(StringPolicy policy, Exp src) {
+ byte[] bytes = Pack.pack(TRIM_END, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that returns {@code src} with whitespace removed from both
+ * ends. Does not modify the underlying bin.
+ *
+ * {@code
+ * // " hello world " -> "hello world"
+ * Exp out = StringExp.trim(StringPolicy.Default, Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param src source string expression
+ * @return string-typed expression yielding the trimmed string
+ */
+ public static Exp trim(StringPolicy policy, Exp src) {
+ byte[] bytes = Pack.pack(TRIM, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that prepends {@code padString} to {@code src} repeatedly until
+ * the result reaches {@code targetLength} codepoints. No-op when the source is
+ * already at or above the target length. Does not modify the underlying bin.
+ *
+ * {@code
+ * // "hello" pad to 10 with "*" -> "*****hello"
+ * Exp out = StringExp.padStart(StringPolicy.Default,
+ * Exp.val(10), Exp.val("*"), Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param targetLength codepoint length to pad up to
+ * @param padString text used to fill (repeated as needed)
+ * @param src source string expression
+ * @return string-typed expression yielding the padded string
+ */
+ public static Exp padStart(StringPolicy policy, Exp targetLength, Exp padString, Exp src) {
+ byte[] bytes = Pack.pack(PAD_START, targetLength, padString, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that appends {@code padString} to {@code src} repeatedly until
+ * the result reaches {@code targetLength} codepoints. No-op when the source is
+ * already at or above the target length. Does not modify the underlying bin.
+ *
+ * {@code
+ * // "hello" pad to 10 with "." -> "hello....."
+ * Exp out = StringExp.padEnd(StringPolicy.Default,
+ * Exp.val(10), Exp.val("."), Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param targetLength codepoint length to pad up to
+ * @param padString text used to fill (repeated as needed)
+ * @param src source string expression
+ * @return string-typed expression yielding the padded string
+ */
+ public static Exp padEnd(StringPolicy policy, Exp targetLength, Exp padString, Exp src) {
+ byte[] bytes = Pack.pack(PAD_END, targetLength, padString, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that returns {@code src} repeated {@code count} times. Does
+ * not modify the underlying bin.
+ *
+ * {@code
+ * // "ab" repeat 3 -> "ababab"
+ * Exp out = StringExp.repeat(StringPolicy.Default,
+ * Exp.val(3), Exp.stringBin("text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param count number of repetitions (must be non-negative)
+ * @param src source string expression
+ * @return string-typed expression yielding the repeated string
+ */
+ public static Exp repeat(StringPolicy policy, Exp count, Exp src) {
+ byte[] bytes = Pack.pack(REPEAT, count, policy.flags);
+ return addModify(src, bytes);
+ }
+
+ /**
+ * Create expression that replaces matches of {@code pattern} (ICU regex syntax) in
+ * {@code src} with {@code replacement} and returns the resulting string. Pass
+ * {@link StringRegexFlags#GLOBAL} to replace every match. Flag values may be
+ * combined with bitwise OR. Does not modify the underlying bin.
+ *
+ * {@code
+ * // "abc123def456" regexReplace "[0-9]+"->"NUM" with GLOBAL -> "abcNUMdefNUM"
+ * Exp out = StringExp.regexReplace(StringPolicy.Default,
+ * Exp.val("[0-9]+"), Exp.val("NUM"), StringRegexFlags.GLOBAL,
+ * Exp.stringBin("text"));
+ * }
+ *
+ * @param policy kept for API symmetry with the other modify ops; unused — the
+ * regex_replace server op does not accept policy flags
+ * (see implementation note)
+ * @param pattern ICU-syntax regex pattern (must be valid UTF-8)
+ * @param replacement replacement text (must be valid UTF-8)
+ * @param regexFlags bitwise-OR of {@link StringRegexFlags} constants
+ * @param src source string expression
+ * @return string-typed expression yielding the modified string
+ */
+ public static Exp regexReplace(
+ StringPolicy policy,
+ Exp pattern,
+ Exp replacement,
+ int regexFlags,
+ Exp src
+ ) {
+ byte[] bytes = packRegexReplace(pattern, replacement, regexFlags);
+ return addModify(src, bytes);
+ }
+
+ //-----------------------------------------------------------------
+ // Type conversion expression
+ //-----------------------------------------------------------------
+
+ /**
+ * Create expression that returns the string representation of {@code src}, where
+ * {@code src} may be any expression yielding an integer, float, string, or blob
+ * value. Returns an error for any other source type.
+ *
+ * {@code
+ * // integer bin "n" = 42 -> "42"
+ * Exp s = StringExp.toString(Exp.intBin("n"));
+ * }
+ *
+ * @param src source expression (integer, float, string, or blob)
+ * @return string-typed expression yielding the string representation
+ */
+ public static Exp toString(Exp src) {
+ byte[] bytes = reprPayload();
+ return new Exp.Module(src, bytes, Exp.Type.STRING.code, MODULE_REPR);
+ }
+
+ //-----------------------------------------------------------------
+ // Private helpers
+ //-----------------------------------------------------------------
+
+ private static Exp addRead(Exp src, byte[] bytes, Exp.Type retType) {
+ return new Exp.Module(src, bytes, retType.code, MODULE);
+ }
+
+ private static Exp addModify(Exp src, byte[] bytes) {
+ return new Exp.Module(src, bytes, Exp.Type.STRING.code, MODULE | Exp.MODIFY);
+ }
+
+ // QUOTED opcode (mirrors Exp.QUOTED = 126; the constant is private in Exp.java).
+ // Used to mark an inner msgpack list as a literal — without it, the server's
+ // expression compiler at exp.c:3289 treats any bare nested list inside a CALL
+ // payload as a sub-expression and recursively compiles its first element as an
+ // opcode, which fails with PARAMETER_ERROR for our string-pair lists.
+ private static final int QUOTED = 126;
+
+ // [cmd, [QUOTED, [needle, repl]], flags] — needle/replacement nested inside a
+ // QUOTED-wrapped 2-element list so the expression compiler treats it as a literal
+ // rather than a sub-expression. The direct-op path packs the same logical shape
+ // (without QUOTED) because it bypasses the expression engine — see
+ // StringOperation.packStringOp(int, List+ * Index orientation is left-to-right with codepoint addressing. Negative indexes + * count from the end of the string ({@code -1} = last codepoint). Out-of-bounds + * indexes are clamped to the valid range; no error is returned. + *
+ * String operations require server version 8.1.3 or later. A non-empty {@link CTX} + * argument navigates into a string nested inside a list or map bin; with no CTX + * the operation targets the bin itself. The CTX-navigated leaf must already be an + * Aerospike string — operations on non-string leaves return + * {@code AEROSPIKE_ERR_INCOMPATIBLE_TYPE}. + * + *
{@code
+ * // Read: bin "text" = "hello world"
+ * Record r = client.operate(null, key, StringOperation.strlen("text"));
+ * long len = r.getLong("text"); // 11
+ *
+ * // Modify: uppercase a string nested in a list bin "items" at index 0.
+ * client.operate(null, key,
+ * StringOperation.upper(StringPolicy.Default, "items", CTX.listIndex(0)));
+ * }
+ */
+public final class StringOperation {
+ // Read ops
+ private static final int STRLEN = 0;
+ private static final int SUBSTR = 1;
+ private static final int CHAR_AT = 2;
+ private static final int FIND = 3;
+ private static final int CONTAINS = 4;
+ private static final int STARTS_WITH = 5;
+ private static final int ENDS_WITH = 6;
+ private static final int TO_INTEGER = 7;
+ private static final int TO_DOUBLE = 8;
+ private static final int BYTE_LENGTH = 9;
+ private static final int IS_NUMERIC = 10;
+ private static final int IS_UPPER = 11;
+ private static final int IS_LOWER = 12;
+ private static final int TO_BLOB = 13;
+ private static final int SPLIT = 14;
+ private static final int B64_DECODE = 15;
+ private static final int REGEX_COMPARE = 16;
+
+ // Modify ops
+ private static final int INSERT = 50;
+ private static final int OVERWRITE = 51;
+ private static final int CONCAT = 52;
+ private static final int SNIP = 53;
+ private static final int REPLACE = 54;
+ private static final int REPLACE_ALL = 55;
+ private static final int UPPER = 56;
+ private static final int LOWER = 57;
+ private static final int CASE_FOLD = 58;
+ private static final int NORMALIZE_NFC = 59;
+ private static final int TRIM_START = 60;
+ private static final int TRIM_END = 61;
+ private static final int TRIM = 62;
+ private static final int PAD_START = 63;
+ private static final int PAD_END = 64;
+ private static final int REPEAT = 65;
+ private static final int REGEX_REPLACE = 66;
+
+ //-----------------------------------------------------------------
+ // Read operations
+ //-----------------------------------------------------------------
+
+ /**
+ * Create string {@code strlen} operation. Returns the number of Unicode codepoints
+ * in the string bin as an int64. This matches {@link String#codePointCount(int, int)}
+ * called on the string's full range.
+ * + * The returned value is the codepoint count — not the count of + * user-perceived characters (grapheme clusters). Codepoints and visible characters + * agree for ASCII and simple Latin text, but diverge for combining marks, emoji + * modifiers, and zero-width-joiner sequences: + *
+ * Two related counts that this op does not return: + *
{@code
+ * // ASCII: "hello world" -> 11 (codepoint count == byte length here)
+ * Record r = client.operate(null, key, StringOperation.strlen("text"));
+ * long len = r.getLong("text");
+ *
+ * // Multi-byte UTF-8: "héllo" stores as 6 bytes but 5 codepoints -> 5
+ * }
+ *
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning the codepoint count (int64)
+ */
+ public static Operation strlen(String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(STRLEN, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code substr} operation that reads from {@code start} to the end of
+ * the string. Negative indexes count from the end.
+ *
+ * {@code
+ * // "hello world" -> "world"
+ * Record r = client.operate(null, key, StringOperation.substr("text", 6));
+ * String tail = r.getString("text");
+ * }
+ *
+ * @param binName name of the string bin
+ * @param start starting codepoint index (negative counts from end)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning the substring
+ */
+ public static Operation substr(String binName, int start, CTX... ctx) {
+ byte[] bytes = packStringOp(SUBSTR, start, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code substr} operation that reads {@code length} codepoints
+ * starting at {@code start}. Negative indexes count from the end of the string.
+ *
+ * {@code
+ * // "hello world" -> "hello"
+ * Record r = client.operate(null, key, StringOperation.substr("text", 0, 5));
+ * }
+ *
+ * @param binName name of the string bin
+ * @param start starting codepoint index (negative counts from end)
+ * @param length number of codepoints to read (clamped to remaining length)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning the substring
+ */
+ public static Operation substr(String binName, int start, int length, CTX... ctx) {
+ byte[] bytes = packStringOp(SUBSTR, start, length, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code charAt} operation. Returns the codepoint at {@code index}
+ * as a one-codepoint string. Negative indexes count from the end.
+ *
+ * {@code
+ * // "Hello123World" at index 5 -> "1"
+ * Record r = client.operate(null, key, StringOperation.charAt("text", 5));
+ * String c = r.getString("text");
+ * }
+ *
+ * @param binName name of the string bin
+ * @param index codepoint index (negative counts from end)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a single-codepoint string
+ */
+ public static Operation charAt(String binName, int index, CTX... ctx) {
+ byte[] bytes = packStringOp(CHAR_AT, index, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code find} operation. Returns the codepoint index of the first
+ * occurrence of {@code needle}, or {@code -1} if not found.
+ *
+ * {@code
+ * // "hello world" -> 6
+ * Record r = client.operate(null, key, StringOperation.find("text", "world"));
+ * long idx = r.getLong("text");
+ * }
+ *
+ * @param binName name of the string bin
+ * @param needle substring to search for
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning the codepoint index, or -1 if absent
+ */
+ public static Operation find(String binName, String needle, CTX... ctx) {
+ byte[] bytes = packStringOp(FIND, Value.get(needle), ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code find} operation that locates a specific {@code occurrence}
+ * of {@code needle} ({@code 1} = first match, {@code -1} = last match). Returns the
+ * codepoint index of that match, or {@code -1} if not found.
+ *
+ * {@code
+ * // "ababab" 2nd occurrence of "ab" -> 2
+ * Record r = client.operate(null, key, StringOperation.find("text", "ab", 2));
+ * }
+ *
+ * @param binName name of the string bin
+ * @param needle substring to search for
+ * @param occurrence 1-based occurrence to return (negative counts from the last match)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning the codepoint index, or -1 if absent
+ */
+ public static Operation find(String binName, String needle, int occurrence, CTX... ctx) {
+ byte[] bytes = packStringOp(FIND, Value.get(needle), occurrence, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code contains} operation. Returns {@code true} if the bin contains
+ * {@code needle} as a substring, {@code false} otherwise.
+ *
+ * {@code
+ * // "hello world" -> true
+ * Record r = client.operate(null, key, StringOperation.contains("text", "hello"));
+ * boolean has = r.getBoolean("text");
+ * }
+ *
+ * @param binName name of the string bin
+ * @param needle substring to test for
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a boolean match flag
+ */
+ public static Operation contains(String binName, String needle, CTX... ctx) {
+ byte[] bytes = packStringOp(CONTAINS, Value.get(needle), ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code startsWith} operation. Returns {@code true} if the bin begins
+ * with {@code prefix}, {@code false} otherwise.
+ *
+ * {@code
+ * // "Hello123World" -> true
+ * Record r = client.operate(null, key, StringOperation.startsWith("text", "Hello"));
+ * }
+ *
+ * @param binName name of the string bin
+ * @param prefix prefix to test for
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a boolean match flag
+ */
+ public static Operation startsWith(String binName, String prefix, CTX... ctx) {
+ byte[] bytes = packStringOp(STARTS_WITH, Value.get(prefix), ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code endsWith} operation. Returns {@code true} if the bin ends
+ * with {@code suffix}, {@code false} otherwise.
+ *
+ * {@code
+ * // "Hello123World" -> true
+ * Record r = client.operate(null, key, StringOperation.endsWith("text", "World"));
+ * }
+ *
+ * @param binName name of the string bin
+ * @param suffix suffix to test for
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a boolean match flag
+ */
+ public static Operation endsWith(String binName, String suffix, CTX... ctx) {
+ byte[] bytes = packStringOp(ENDS_WITH, Value.get(suffix), ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code toInteger} operation. Parses the string as an int64.
+ * Returns {@code AEROSPIKE_ERR_PARAMETER} if the bin cannot be parsed as an integer.
+ *
+ * {@code
+ * // "12345" -> 12345
+ * Record r = client.operate(null, key, StringOperation.toInteger("text"));
+ * long n = r.getLong("text");
+ * }
+ *
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning the parsed int64
+ */
+ public static Operation toInteger(String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(TO_INTEGER, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code toDouble} operation. Parses the string as a 64-bit float.
+ * Returns {@code AEROSPIKE_ERR_PARAMETER} if the bin cannot be parsed as a double.
+ *
+ * {@code
+ * // "3.14" -> 3.14
+ * Record r = client.operate(null, key, StringOperation.toDouble("text"));
+ * double v = r.getDouble("text");
+ * }
+ *
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning the parsed double
+ */
+ public static Operation toDouble(String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(TO_DOUBLE, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code byteLength} operation. Returns the number of UTF-8 bytes in
+ * the string (int64). Differs from {@link #strlen} for non-ASCII content where one
+ * codepoint can encode to multiple bytes.
+ *
+ * {@code
+ * // "hello" -> 5
+ * Record r = client.operate(null, key, StringOperation.byteLength("text"));
+ * }
+ *
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning the byte length (int64)
+ */
+ public static Operation byteLength(String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(BYTE_LENGTH, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code isNumeric} operation. Returns {@code true} if the bin
+ * contains a valid integer or float, {@code false} otherwise.
+ *
+ * {@code
+ * // "12345" -> true; "Hello" -> false
+ * Record r = client.operate(null, key, StringOperation.isNumeric("text"));
+ * boolean numeric = r.getBoolean("text");
+ * }
+ *
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a boolean match flag
+ */
+ public static Operation isNumeric(String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(IS_NUMERIC, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code isNumeric} operation that filters by {@code numericType}
+ * (see {@link StringNumericType}). For example, restrict to integer-only or
+ * float-only validation.
+ *
+ * {@code
+ * // "12345" with INT filter -> true
+ * Record r = client.operate(null, key,
+ * StringOperation.isNumeric("text", StringNumericType.INT));
+ * }
+ *
+ * @param binName name of the string bin
+ * @param numericType one of the {@link StringNumericType} constants
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a boolean match flag
+ */
+ public static Operation isNumeric(String binName, int numericType, CTX... ctx) {
+ byte[] bytes = packStringOp(IS_NUMERIC, numericType, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code isUpper} operation. Returns {@code true} if every cased
+ * codepoint in the bin is uppercase, {@code false} otherwise.
+ *
+ * {@code
+ * // "HELLO" -> true; "Hello" -> false
+ * Record r = client.operate(null, key, StringOperation.isUpper("text"));
+ * }
+ *
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a boolean match flag
+ */
+ public static Operation isUpper(String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(IS_UPPER, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code isLower} operation. Returns {@code true} if every cased
+ * codepoint in the bin is lowercase, {@code false} otherwise.
+ *
+ * {@code
+ * // "hello" -> true; "Hello" -> false
+ * Record r = client.operate(null, key, StringOperation.isLower("text"));
+ * }
+ *
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a boolean match flag
+ */
+ public static Operation isLower(String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(IS_LOWER, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code toBlob} operation. Returns the UTF-8 bytes of the string
+ * as a blob (byte[]).
+ *
+ * {@code
+ * // "hello" -> [0x68, 0x65, 0x6c, 0x6c, 0x6f]
+ * Record r = client.operate(null, key, StringOperation.toBlob("text"));
+ * byte[] bytes = (byte[]) r.getValue("text");
+ * }
+ *
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a byte[] blob
+ */
+ public static Operation toBlob(String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(TO_BLOB, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code split} operation that splits by Unicode codepoint — each
+ * codepoint becomes its own element of the returned list.
+ *
+ * {@code
+ * // "abc" -> ["a", "b", "c"]
+ * Record r = client.operate(null, key, StringOperation.split("text"));
+ * List chars = r.getList("text");
+ * }
+ *
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a list of single-codepoint strings
+ */
+ public static Operation split(String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(SPLIT, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code split} operation that splits the bin by the {@code separator}
+ * substring. If the separator is absent the result is a singleton list containing
+ * the whole string.
+ *
+ * {@code
+ * // "one,two,three" with "," -> ["one", "two", "three"]
+ * Record r = client.operate(null, key, StringOperation.split("text", ","));
+ * }
+ *
+ * @param binName name of the string bin
+ * @param separator substring used to split the bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a list of token strings
+ */
+ public static Operation split(String binName, String separator, CTX... ctx) {
+ byte[] bytes = packStringOp(SPLIT, Value.get(separator), ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code b64Decode} operation. Treats the bin as base64-encoded text
+ * and returns the decoded bytes as a blob.
+ *
+ * {@code
+ * // "aGVsbG8=" -> "hello".getBytes()
+ * Record r = client.operate(null, key, StringOperation.b64Decode("text"));
+ * byte[] decoded = (byte[]) r.getValue("text");
+ * }
+ *
+ * @param binName name of the string bin holding base64 text
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning the decoded byte[]
+ */
+ public static Operation b64Decode(String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(B64_DECODE, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code regexCompare} operation. Matches {@code pattern} (ICU regex
+ * syntax) against the bin and returns {@code true} on match, {@code false} otherwise.
+ *
+ * {@code
+ * // "Hello123World" matches "[0-9]+" -> true
+ * Record r = client.operate(null, key, StringOperation.regexCompare("text", "[0-9]+"));
+ * boolean matched = r.getBoolean("text");
+ * }
+ *
+ * @param binName name of the string bin
+ * @param pattern ICU-syntax regex pattern (must be valid UTF-8)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a boolean match flag
+ */
+ public static Operation regexCompare(String binName, String pattern, CTX... ctx) {
+ byte[] bytes = packStringOp(REGEX_COMPARE, Value.get(pattern), ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code regexCompare} operation that honors {@link StringRegexFlags}
+ * (e.g. {@link StringRegexFlags#CASE_INSENSITIVE}). Flag values may be combined
+ * with bitwise OR.
+ *
+ * {@code
+ * // "HELLO" matches "hello" with CASE_INSENSITIVE -> true
+ * Record r = client.operate(null, key,
+ * StringOperation.regexCompare("text", "hello", StringRegexFlags.CASE_INSENSITIVE));
+ * }
+ *
+ * @param binName name of the string bin
+ * @param pattern ICU-syntax regex pattern (must be valid UTF-8)
+ * @param regexFlags bitwise-OR of {@link StringRegexFlags} constants
+ * @param ctx optional path into a string nested inside a list or map
+ * @return read operation returning a boolean match flag
+ */
+ public static Operation regexCompare(String binName, String pattern, int regexFlags, CTX... ctx) {
+ byte[] bytes = packStringOp(REGEX_COMPARE, Value.get(pattern), regexFlags, ctx);
+ return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ //-----------------------------------------------------------------
+ // Modify operations
+ //-----------------------------------------------------------------
+
+ /**
+ * Create string {@code insert} operation that splices {@code value} into the bin at
+ * codepoint {@code index}. Negative indexes count from the end of the string.
+ *
+ * {@code
+ * // "hello world" + insert " beautiful" at 5 -> "hello beautiful world"
+ * client.operate(null, key,
+ * StringOperation.insert(StringPolicy.Default, "text", 5, " beautiful"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param index codepoint index at which to insert (negative counts from end)
+ * @param value text to insert
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation insert(StringPolicy policy, String binName, int index, String value, CTX... ctx) {
+ byte[] bytes = packStringOp(INSERT, index, Value.get(value), policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code overwrite} operation that overwrites codepoints starting at
+ * codepoint {@code index} with {@code value}. The result may grow beyond the
+ * original length when {@code value} extends past the end.
+ *
+ * {@code
+ * // "hello world" overwrite "earth" at 6 -> "hello earth"
+ * client.operate(null, key,
+ * StringOperation.overwrite(StringPolicy.Default, "text", 6, "earth"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param index codepoint index at which to start overwriting
+ * @param value text to write
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation overwrite(StringPolicy policy, String binName, int index, String value, CTX... ctx) {
+ byte[] bytes = packStringOp(OVERWRITE, index, Value.get(value), policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code concat} operation that appends {@code value} to the bin.
+ *
+ * {@code
+ * // "hello" + concat "!" -> "hello!"
+ * client.operate(null, key,
+ * StringOperation.concat(StringPolicy.Default, "text", "!"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param value text to append
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation concat(StringPolicy policy, String binName, String value, CTX... ctx) {
+ List{@code
+ * // "hello" + concat [" ", "big", " world"] -> "hello big world"
+ * client.operate(null, key, StringOperation.concat(StringPolicy.Default, "text",
+ * Arrays.asList(" ", "big", " world")));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param values ordered list of strings to append
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation concat(StringPolicy policy, String binName, List{@code
+ * // "hello world" snip from 5 -> "hello"
+ * client.operate(null, key,
+ * StringOperation.snip(StringPolicy.Default, "text", 5));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param start first codepoint to remove (inclusive)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation snip(StringPolicy policy, String binName, int start, CTX... ctx) {
+ byte[] bytes = packStringOp(SNIP, start, policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code snip} operation that removes the half-open codepoint range
+ * {@code [start, end)} from the bin.
+ *
+ * {@code
+ * // "hello beautiful world" snip [5, 15) -> "hello world"
+ * client.operate(null, key,
+ * StringOperation.snip(StringPolicy.Default, "text", 5, 15));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param start first codepoint to remove (inclusive)
+ * @param end one past the last codepoint to remove (exclusive)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation snip(StringPolicy policy, String binName, int start, int end, CTX... ctx) {
+ byte[] bytes = packStringOp(SNIP, start, end, policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code replace} operation that replaces the first occurrence of
+ * {@code needle} with {@code replacement}.
+ *
+ * {@code
+ * // "hello world world" replace "world"->"earth" -> "hello earth world"
+ * client.operate(null, key,
+ * StringOperation.replace(StringPolicy.Default, "text", "world", "earth"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param needle substring to find
+ * @param replacement text to substitute (may be empty to delete the match)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation replace(StringPolicy policy, String binName, String needle, String replacement, CTX... ctx) {
+ List{@code
+ * // "aabaa" replaceAll "a"->"x" -> "xxbxx"
+ * client.operate(null, key,
+ * StringOperation.replaceAll(StringPolicy.Default, "text", "a", "x"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param needle substring to find
+ * @param replacement text to substitute (may be empty to delete each match)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation replaceAll(StringPolicy policy, String binName, String needle, String replacement, CTX... ctx) {
+ List{@code
+ * // "hello world" -> "HELLO WORLD"
+ * client.operate(null, key, StringOperation.upper(StringPolicy.Default, "text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation upper(StringPolicy policy, String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(UPPER, policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code lower} operation that lowercases the bin in place.
+ *
+ * {@code
+ * // "HELLO WORLD" -> "hello world"
+ * client.operate(null, key, StringOperation.lower(StringPolicy.Default, "text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation lower(StringPolicy policy, String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(LOWER, policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code caseFold} operation that applies a locale-independent case
+ * fold (lowercase) to the bin. Useful for normalized comparison keys.
+ *
+ * {@code
+ * // "HELLO World" -> "hello world"
+ * client.operate(null, key, StringOperation.caseFold(StringPolicy.Default, "text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation caseFold(StringPolicy policy, String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(CASE_FOLD, policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code normalizeNFC} operation that normalizes the bin to Unicode
+ * NFC form. Already-normalized strings are unchanged.
+ *
+ * {@code
+ * client.operate(null, key,
+ * StringOperation.normalizeNFC(StringPolicy.Default, "text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation normalizeNFC(StringPolicy policy, String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(NORMALIZE_NFC, policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code trimStart} operation that removes whitespace from the start
+ * of the bin.
+ *
+ * {@code
+ * // " hello " -> "hello "
+ * client.operate(null, key,
+ * StringOperation.trimStart(StringPolicy.Default, "text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation trimStart(StringPolicy policy, String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(TRIM_START, policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code trimEnd} operation that removes whitespace from the end of
+ * the bin.
+ *
+ * {@code
+ * // " hello " -> " hello"
+ * client.operate(null, key,
+ * StringOperation.trimEnd(StringPolicy.Default, "text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation trimEnd(StringPolicy policy, String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(TRIM_END, policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code trim} operation that removes whitespace from both ends of
+ * the bin.
+ *
+ * {@code
+ * // " hello world " -> "hello world"
+ * client.operate(null, key,
+ * StringOperation.trim(StringPolicy.Default, "text"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation trim(StringPolicy policy, String binName, CTX... ctx) {
+ byte[] bytes = packStringOp(TRIM, policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code padStart} operation that prepends {@code padString}
+ * repeatedly until the bin reaches {@code targetLength} codepoints. No-op when the
+ * bin is already at or above the target length.
+ *
+ * {@code
+ * // "hello" pad to 10 with "*" -> "*****hello"
+ * client.operate(null, key,
+ * StringOperation.padStart(StringPolicy.Default, "text", 10, "*"));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param targetLength codepoint length to pad up to
+ * @param padString text used to fill (repeated as needed)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation padStart(StringPolicy policy, String binName, int targetLength, String padString, CTX... ctx) {
+ byte[] bytes = packStringOp(PAD_START, targetLength, Value.get(padString), policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code padEnd} operation that appends {@code padString} repeatedly
+ * until the bin reaches {@code targetLength} codepoints. No-op when the bin is
+ * already at or above the target length.
+ *
+ * {@code
+ * // "hello" pad to 10 with "." -> "hello....."
+ * client.operate(null, key,
+ * StringOperation.padEnd(StringPolicy.Default, "text", 10, "."));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param targetLength codepoint length to pad up to
+ * @param padString text used to fill (repeated as needed)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation padEnd(StringPolicy policy, String binName, int targetLength, String padString, CTX... ctx) {
+ byte[] bytes = packStringOp(PAD_END, targetLength, Value.get(padString), policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code repeat} operation that repeats the bin contents {@code count}
+ * times.
+ *
+ * {@code
+ * // "ab" repeat 3 -> "ababab"
+ * client.operate(null, key,
+ * StringOperation.repeat(StringPolicy.Default, "text", 3));
+ * }
+ *
+ * @param policy write policy controlling NO_FAIL semantics
+ * @param binName name of the string bin
+ * @param count number of repetitions (must be non-negative)
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation repeat(StringPolicy policy, String binName, int count, CTX... ctx) {
+ byte[] bytes = packStringOp(REPEAT, count, policy.flags, ctx);
+ return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING));
+ }
+
+ /**
+ * Create string {@code regexReplace} operation that replaces the first match of
+ * {@code pattern} with {@code replacement}. Pass {@link StringRegexFlags#GLOBAL}
+ * to replace every match. Flag values from {@link StringRegexFlags} may be combined
+ * with bitwise OR.
+ *
+ * {@code
+ * // "abc123def456" regexReplace "[0-9]+"->"NUM" with GLOBAL -> "abcNUMdefNUM"
+ * client.operate(null, key,
+ * StringOperation.regexReplace(StringPolicy.Default, "text",
+ * "[0-9]+", "NUM", StringRegexFlags.GLOBAL));
+ * }
+ *
+ * @param policy (unused; the regex_replace server op does not accept policy
+ * flags — see implementation note)
+ * @param binName name of the string bin
+ * @param pattern ICU-syntax regex pattern (must be valid UTF-8)
+ * @param replacement replacement text (must be valid UTF-8)
+ * @param regexFlags bitwise-OR of {@link StringRegexFlags} constants
+ * @param ctx optional path into a string nested inside a list or map
+ * @return modify operation
+ */
+ public static Operation regexReplace(
+ StringPolicy policy,
+ String binName,
+ String pattern,
+ String replacement,
+ int regexFlags,
+ CTX... ctx
+ ) {
+ List+ * Unlike the other builders in this class, {@code toString} does not accept a + * {@link CTX}. The other string operations are sent as {@code STRING_READ} / + * {@code STRING_MODIFY} wire ops whose msgpack payload carries the sub-op code, + * arguments, and (when CTX is non-empty) a {@code [0xFF, ctx_list, inner_op]} + * wrapper that the server's CTX-aware dispatcher unwraps to descend into a list + * or map. {@code toString} is a separate top-level wire op + * ({@code Operation.Type.TO_STRING}) that carries no payload at all — the bin is + * referenced solely by the operation header — and the server-side handler for it + * is a different code path that operates on the whole bin particle and never + * inspects an op payload, so there is no place to encode a CTX wrapper and the + * server would not act on it if there were. + *
+ * To convert a value nested inside a list or map, extract the leaf with + * {@link com.aerospike.client.cdt.ListOperation#getByIndex} or + * {@link com.aerospike.client.cdt.MapOperation#getByKey} (using the appropriate + * {@link CTX}) and convert it client-side. + * + *
{@code
+ * // Bin "n" = 42 (integer) -> "42"
+ * Record r = client.operate(null, key, StringOperation.toString("n"));
+ * String s = r.getString("n");
+ * }
+ *
+ * @param binName name of the bin to convert
+ * @return read operation returning the string representation of the bin
+ */
+ public static Operation toString(String binName) {
+ return new Operation(Operation.Type.TO_STRING, binName, Value.getAsNull());
+ }
+
+ //-----------------------------------------------------------------
+ // Private helpers
+ //-----------------------------------------------------------------
+
+ private static List+ * This is a per-operation policy carrying {@link StringWriteFlags}. It is + * passed inline to each {@link StringOperation} builder method and is + * not part of the client's dynamic configuration: there is no + * {@code stringPolicyDefault} on {@link com.aerospike.client.policy.ClientPolicy} + * and no corresponding stanza in the YAML config schema. Changing the flags + * requires constructing a new {@code StringPolicy} and passing it to the + * operation, not editing a config file at runtime. This mirrors how + * {@code BitPolicy} and {@code HLLPolicy} are scoped. + */ +public final class StringPolicy { + /** + * Default string bin write semantics. + */ + public static final StringPolicy Default = new StringPolicy(); + + public final int flags; + + /** + * Use default {@link StringWriteFlags} when performing {@link StringOperation} modify operations. + */ + public StringPolicy() { + this(StringWriteFlags.DEFAULT); + } + + /** + * Use specified {@link StringWriteFlags} when performing {@link StringOperation} modify operations. + */ + public StringPolicy(int flags) { + this.flags = flags; + } +} diff --git a/client/src/com/aerospike/client/operation/StringRegexFlags.java b/client/src/com/aerospike/client/operation/StringRegexFlags.java new file mode 100644 index 000000000..e5d8946a9 --- /dev/null +++ b/client/src/com/aerospike/client/operation/StringRegexFlags.java @@ -0,0 +1,55 @@ +/* + * Copyright 2012-2026 Aerospike, Inc. + * + * Portions may be licensed to Aerospike, Inc. under one or more contributor + * license agreements WHICH ARE COMPATIBLE WITH THE APACHE LICENSE, VERSION 2.0. + * + * 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://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License 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.aerospike.client.operation; + +/** + * Regex flags for {@link StringOperation#regexCompare} and + * {@link StringOperation#regexReplace}. Combine with bitwise OR. + */ +public final class StringRegexFlags { + /** + * Default. No flags set. + */ + public static final int DEFAULT = 0; + + /** + * Case insensitive matching. + */ + public static final int CASE_INSENSITIVE = 1 << 0; + + /** + * Treat input as a multi-line string. {@code ^} and {@code $} match + * the start and end of any line, not just the start and end of the input. + */ + public static final int MULTILINE = 1 << 1; + + /** + * The {@code .} metacharacter matches any character including line terminators. + */ + public static final int DOTALL = 1 << 2; + + /** + * Treat only {@code \n} as a line terminator (Unix-style line endings). + */ + public static final int UNIX_LINES = 1 << 3; + + /** + * Replace all matches in the input. Only applicable to + * {@link StringOperation#regexReplace}. + */ + public static final int GLOBAL = 1 << 4; +} diff --git a/client/src/com/aerospike/client/operation/StringWriteFlags.java b/client/src/com/aerospike/client/operation/StringWriteFlags.java new file mode 100644 index 000000000..a1e1d591c --- /dev/null +++ b/client/src/com/aerospike/client/operation/StringWriteFlags.java @@ -0,0 +1,38 @@ +/* + * Copyright 2012-2026 Aerospike, Inc. + * + * Portions may be licensed to Aerospike, Inc. under one or more contributor + * license agreements WHICH ARE COMPATIBLE WITH THE APACHE LICENSE, VERSION 2.0. + * + * 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://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License 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.aerospike.client.operation; + +/** + * String operation policy write bit flags. Use BITWISE OR to combine flags. Example: + * + *
{@code
+ * int flags = StringWriteFlags.NO_FAIL;
+ * }
+ */
+public final class StringWriteFlags {
+ /**
+ * Default. Allow create or update.
+ */
+ public static final int DEFAULT = 0;
+
+ /**
+ * Do not raise error if operation cannot be applied to the bin
+ * (e.g. wrong bin type). The bin is left unchanged and a null
+ * result is returned for that operation.
+ */
+ public static final int NO_FAIL = 4;
+}
diff --git a/client/src/com/aerospike/client/util/Pack.java b/client/src/com/aerospike/client/util/Pack.java
index b77152901..a532bf14c 100644
--- a/client/src/com/aerospike/client/util/Pack.java
+++ b/client/src/com/aerospike/client/util/Pack.java
@@ -342,6 +342,26 @@ public static byte[] pack(int command, Value value, CTX... ctx) {
return packer.getBuffer();
}
+ public static byte[] pack(int command, Value value, int v1, CTX... ctx) {
+ Packer packer = new Packer();
+
+ init(packer, ctx);
+ packer.packArrayBegin(3);
+ packer.packInt(command);
+ value.pack(packer);
+ packer.packInt(v1);
+
+ packer.createBuffer();
+
+ init(packer, ctx);
+ packer.packArrayBegin(3);
+ packer.packInt(command);
+ value.pack(packer);
+ packer.packInt(v1);
+
+ return packer.getBuffer();
+ }
+
public static byte[] pack(int command, Value value, int v1, int v2, CTX... ctx) {
Packer packer = new Packer();
diff --git a/test/src/com/aerospike/test/SuiteSync.java b/test/src/com/aerospike/test/SuiteSync.java
index 9b4c9e272..27bc32591 100644
--- a/test/src/com/aerospike/test/SuiteSync.java
+++ b/test/src/com/aerospike/test/SuiteSync.java
@@ -47,11 +47,14 @@
import com.aerospike.test.sync.basic.TestOperateHll;
import com.aerospike.test.sync.basic.TestOperateList;
import com.aerospike.test.sync.basic.TestOperateMap;
+import com.aerospike.test.sync.basic.TestOperateString;
import com.aerospike.test.sync.basic.TestPutGet;
import com.aerospike.test.sync.basic.TestQueryRoles;
import com.aerospike.test.sync.basic.TestReplace;
import com.aerospike.test.sync.basic.TestScan;
import com.aerospike.test.sync.basic.TestServerInfo;
+import com.aerospike.test.sync.basic.TestStringExp;
+import com.aerospike.test.sync.basic.TestStringMasking;
import com.aerospike.test.sync.basic.TestTouch;
import com.aerospike.test.sync.basic.TestTxn;
import com.aerospike.test.sync.basic.TestUDF;
@@ -97,11 +100,14 @@
TestOperateHll.class,
TestOperateList.class,
TestOperateMap.class,
+ TestOperateString.class,
TestPutGet.class,
TestQueryRoles.class,
TestReplace.class,
TestScan.class,
TestServerInfo.class,
+ TestStringExp.class,
+ TestStringMasking.class,
TestTouch.class,
TestTxn.class,
TestUDF.class,
diff --git a/test/src/com/aerospike/test/sync/basic/TestOperateString.java b/test/src/com/aerospike/test/sync/basic/TestOperateString.java
new file mode 100644
index 000000000..436b4ca77
--- /dev/null
+++ b/test/src/com/aerospike/test/sync/basic/TestOperateString.java
@@ -0,0 +1,760 @@
+/*
+ * Copyright 2012-2026 Aerospike, Inc.
+ *
+ * Portions may be licensed to Aerospike, Inc. under one or more contributor
+ * license agreements WHICH ARE COMPATIBLE WITH THE APACHE LICENSE, VERSION 2.0.
+ *
+ * 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://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License 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.aerospike.test.sync.basic;
+
+import static org.junit.Assert.assertArrayEquals;
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertThrows;
+import static org.junit.Assert.assertTrue;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import org.junit.Assume;
+import org.junit.BeforeClass;
+import org.junit.Test;
+
+import com.aerospike.client.AerospikeException;
+import com.aerospike.client.Bin;
+import com.aerospike.client.Key;
+import com.aerospike.client.Operation;
+import com.aerospike.client.Record;
+import com.aerospike.client.ResultCode;
+import com.aerospike.client.Value;
+import com.aerospike.client.cdt.CTX;
+import com.aerospike.client.operation.StringOperation;
+import com.aerospike.client.operation.StringPolicy;
+import com.aerospike.client.operation.StringRegexFlags;
+import com.aerospike.client.operation.StringWriteFlags;
+import com.aerospike.test.sync.TestSync;
+
+/**
+ * Integration tests for the string operations exposed by {@link StringOperation}.
+ *
+ * The tests are organized around the operation behavior they verify rather + * than around individual API methods, so each test exercises a single intent + * (e.g. "uppercase mutates the bin", "find returns the first match index"). + * + *
String operations require server version 8.1.3+; the tests are skipped
+ * on older clusters via {@link Assume}.
+ */
+public class TestOperateString extends TestSync {
+ private static final String BIN = "sbin";
+ private static final Key KEY = new Key(args.namespace, args.set, "stringop-key");
+ private static final StringPolicy POLICY = StringPolicy.Default;
+
+ @BeforeClass
+ public static void serverVersionCheck() {
+ Assume.assumeTrue(
+ "Skipping: string operations require server version 8.1.3 or later",
+ args.serverVersion.isGreaterOrEqual(8, 1, 3, 0));
+ }
+
+ //-----------------------------------------------------------------
+ // Helpers
+ //-----------------------------------------------------------------
+
+ private static void put(String value) {
+ client.delete(null, KEY);
+ client.put(null, KEY, new Bin(BIN, value));
+ }
+
+ private static void put(Bin... bins) {
+ client.delete(null, KEY);
+ client.put(null, KEY, bins);
+ }
+
+ private static Record operate(Operation... ops) {
+ return client.operate(null, KEY, ops);
+ }
+
+ private static String stringValue() {
+ return client.get(null, KEY).getString(BIN);
+ }
+
+ //=================================================================
+ // Read operations
+ //=================================================================
+
+ @Test
+ public void strlenReturnsCodepointCount() {
+ put("hello world");
+ Record r = operate(StringOperation.strlen(BIN));
+ assertEquals(11L, r.getLong(BIN));
+ }
+
+ @Test
+ public void strlenOnEmptyStringIsZero() {
+ put("");
+ Record r = operate(StringOperation.strlen(BIN));
+ assertEquals(0L, r.getLong(BIN));
+ }
+
+ @Test
+ public void byteLengthReturnsUtf8Bytes() {
+ put("hello");
+ Record r = operate(StringOperation.byteLength(BIN));
+ assertEquals(5L, r.getLong(BIN));
+ }
+
+ @Test
+ public void substrFromOffsetToEnd() {
+ put("hello world");
+ Record r = operate(StringOperation.substr(BIN, 6));
+ assertEquals("world", r.getString(BIN));
+ }
+
+ @Test
+ public void substrSlicesARange() {
+ put("hello world");
+ Record r = operate(StringOperation.substr(BIN, 0, 5));
+ assertEquals("hello", r.getString(BIN));
+ }
+
+ @Test
+ public void substrSupportsNegativeStart() {
+ put("hello world");
+ Record r = operate(StringOperation.substr(BIN, -5));
+ assertEquals("world", r.getString(BIN));
+ }
+
+ @Test
+ public void charAtReturnsSingleCharacter() {
+ put("Hello123World");
+ Record r = operate(StringOperation.charAt(BIN, 5));
+ assertEquals("1", r.getString(BIN));
+ }
+
+ @Test
+ public void findReturnsIndexOfFirstMatch() {
+ put("hello world");
+ Record r = operate(StringOperation.find(BIN, "world"));
+ assertEquals(6L, r.getLong(BIN));
+ }
+
+ @Test
+ public void findReturnsMinusOneWhenAbsent() {
+ put("hello world");
+ Record r = operate(StringOperation.find(BIN, "xyz"));
+ assertEquals(-1L, r.getLong(BIN));
+ }
+
+ @Test
+ public void containsReturnsBoolean() {
+ put("hello world");
+ Record present = operate(StringOperation.contains(BIN, "hello"));
+ Record absent = operate(StringOperation.contains(BIN, "xyz"));
+ assertTrue(present.getBoolean(BIN));
+ assertFalse(absent.getBoolean(BIN));
+ }
+
+ @Test
+ public void startsWithMatchesPrefix() {
+ put("Hello123World");
+ assertTrue(operate(StringOperation.startsWith(BIN, "Hello")).getBoolean(BIN));
+ assertFalse(operate(StringOperation.startsWith(BIN, "World")).getBoolean(BIN));
+ }
+
+ @Test
+ public void endsWithMatchesSuffix() {
+ put("Hello123World");
+ assertTrue(operate(StringOperation.endsWith(BIN, "World")).getBoolean(BIN));
+ assertFalse(operate(StringOperation.endsWith(BIN, "Hello")).getBoolean(BIN));
+ }
+
+ @Test
+ public void isUpperOnlyTrueForUppercase() {
+ put("HELLO");
+ assertTrue(operate(StringOperation.isUpper(BIN)).getBoolean(BIN));
+ put("hello");
+ assertFalse(operate(StringOperation.isUpper(BIN)).getBoolean(BIN));
+ }
+
+ @Test
+ public void isLowerOnlyTrueForLowercase() {
+ put("hello");
+ assertTrue(operate(StringOperation.isLower(BIN)).getBoolean(BIN));
+ put("HELLO");
+ assertFalse(operate(StringOperation.isLower(BIN)).getBoolean(BIN));
+ }
+
+ @Test
+ public void isNumericMatchesIntegerStrings() {
+ put("12345");
+ assertTrue(operate(StringOperation.isNumeric(BIN)).getBoolean(BIN));
+ put("Hello123World");
+ assertFalse(operate(StringOperation.isNumeric(BIN)).getBoolean(BIN));
+ }
+
+ @Test
+ public void toIntegerParsesDigitsAsLong() {
+ put("12345");
+ Record r = operate(StringOperation.toInteger(BIN));
+ assertEquals(12345L, r.getLong(BIN));
+ }
+
+ @Test
+ public void toDoubleParsesDecimalNumbers() {
+ put("3.14");
+ Record r = operate(StringOperation.toDouble(BIN));
+ assertEquals(3.14, r.getDouble(BIN), 0.001);
+ }
+
+ @Test
+ public void splitReturnsListOfTokens() {
+ put("one,two,three");
+ Record r = operate(StringOperation.split(BIN, ","));
+ assertEquals(Arrays.asList("one", "two", "three"), r.getList(BIN));
+ }
+
+ @Test
+ public void splitWithoutMatchReturnsSingletonList() {
+ put("Hello123World");
+ Record r = operate(StringOperation.split(BIN, "|"));
+ assertEquals(Arrays.asList("Hello123World"), r.getList(BIN));
+ }
+
+ @Test
+ public void regexCompareDistinguishesMatchVsMiss() {
+ put("Hello123World");
+ assertTrue(operate(StringOperation.regexCompare(BIN, "[0-9]+")).getBoolean(BIN));
+ put("HELLO");
+ assertFalse(operate(StringOperation.regexCompare(BIN, "[0-9]+")).getBoolean(BIN));
+ }
+
+ @Test
+ public void regexCompareHonorsCaseInsensitiveFlag() {
+ put("HELLO");
+ assertTrue(operate(StringOperation.regexCompare(
+ BIN, "hello", StringRegexFlags.CASE_INSENSITIVE)).getBoolean(BIN));
+ }
+
+ @Test
+ public void toBlobReturnsUtf8Bytes() {
+ put("hello");
+ Record r = operate(StringOperation.toBlob(BIN));
+ assertArrayEquals("hello".getBytes(), (byte[])r.getValue(BIN));
+ }
+
+ @Test
+ public void b64DecodeReturnsOriginalBlob() {
+ put("aGVsbG8=");
+ Record r = operate(StringOperation.b64Decode(BIN));
+ assertArrayEquals("hello".getBytes(), (byte[])r.getValue(BIN));
+ }
+
+ //=================================================================
+ // Modify operations
+ //=================================================================
+
+ @Test
+ public void upperMutatesBinInPlace() {
+ put("hello world");
+ operate(StringOperation.upper(POLICY, BIN));
+ assertEquals("HELLO WORLD", stringValue());
+ }
+
+ @Test
+ public void lowerMutatesBinInPlace() {
+ put("HELLO WORLD");
+ operate(StringOperation.lower(POLICY, BIN));
+ assertEquals("hello world", stringValue());
+ }
+
+ @Test
+ public void caseFoldLowercasesIndependentlyOfLocale() {
+ put("HELLO World");
+ operate(StringOperation.caseFold(POLICY, BIN));
+ assertEquals("hello world", stringValue());
+ }
+
+ @Test
+ public void normalizeNFCLeavesAlreadyNormalizedStringUnchanged() {
+ put("hello");
+ operate(StringOperation.normalizeNFC(POLICY, BIN));
+ assertEquals("hello", stringValue());
+ }
+
+ @Test
+ public void insertAtMiddleSplicesValue() {
+ put("hello world");
+ operate(StringOperation.insert(POLICY, BIN, 5, " beautiful"));
+ assertEquals("hello beautiful world", stringValue());
+ }
+
+ @Test
+ public void insertAtZeroPrependsValue() {
+ put("world");
+ operate(StringOperation.insert(POLICY, BIN, 0, "hello "));
+ assertEquals("hello world", stringValue());
+ }
+
+ @Test
+ public void insertAtEndAppendsValue() {
+ put("hello");
+ operate(StringOperation.insert(POLICY, BIN, 5, " world"));
+ assertEquals("hello world", stringValue());
+ }
+
+ @Test
+ public void insertWithNegativeIndexCountsFromEnd() {
+ put("hello world");
+ operate(StringOperation.insert(POLICY, BIN, -5, "big "));
+ assertEquals("hello big world", stringValue());
+ }
+
+ @Test
+ public void overwriteReplacesCharactersStartingAtIndex() {
+ put("hello world");
+ operate(StringOperation.overwrite(POLICY, BIN, 6, "earth"));
+ assertEquals("hello earth", stringValue());
+ }
+
+ @Test
+ public void overwriteAtZeroReplacesPrefix() {
+ put("hello world");
+ operate(StringOperation.overwrite(POLICY, BIN, 0, "HELLO"));
+ assertEquals("HELLO world", stringValue());
+ }
+
+ @Test
+ public void overwriteCanExtendBeyondOriginalLength() {
+ put("hello");
+ operate(StringOperation.overwrite(POLICY, BIN, 3, "ping!"));
+ assertEquals("helping!", stringValue());
+ }
+
+ @Test
+ public void snipRemovesCharacterRange() {
+ put("hello beautiful world");
+ operate(StringOperation.snip(POLICY, BIN, 5, 15));
+ assertEquals("hello world", stringValue());
+ }
+
+ @Test
+ public void snipFromStartTrimsPrefix() {
+ put("hello world");
+ operate(StringOperation.snip(POLICY, BIN, 0, 6));
+ assertEquals("world", stringValue());
+ }
+
+ @Test
+ public void snipToEndTrimsSuffix() {
+ put("hello world");
+ operate(StringOperation.snip(POLICY, BIN, 5, 11));
+ assertEquals("hello", stringValue());
+ }
+
+ @Test
+ public void replaceTouchesOnlyFirstOccurrence() {
+ put("hello world world");
+ operate(StringOperation.replace(POLICY, BIN, "world", "earth"));
+ assertEquals("hello earth world", stringValue());
+ }
+
+ @Test
+ public void replaceWithNoMatchLeavesBinUnchanged() {
+ put("hello world");
+ operate(StringOperation.replace(POLICY, BIN, "xyz", "abc"));
+ assertEquals("hello world", stringValue());
+ }
+
+ @Test
+ public void replaceCanGrowTheString() {
+ put("hi world");
+ operate(StringOperation.replace(POLICY, BIN, "hi", "hello"));
+ assertEquals("hello world", stringValue());
+ }
+
+ @Test
+ public void replaceWithEmptyDeletesMatch() {
+ put("hello world");
+ operate(StringOperation.replace(POLICY, BIN, " world", ""));
+ assertEquals("hello", stringValue());
+ }
+
+ @Test
+ public void replaceAllSubstitutesEveryMatch() {
+ put("aabaa");
+ operate(StringOperation.replaceAll(POLICY, BIN, "a", "x"));
+ assertEquals("xxbxx", stringValue());
+ }
+
+ @Test
+ public void replaceAllWithNoMatchLeavesBinUnchanged() {
+ put("hello");
+ operate(StringOperation.replaceAll(POLICY, BIN, "z", "!"));
+ assertEquals("hello", stringValue());
+ }
+
+ @Test
+ public void trimRemovesWhitespaceOnBothEnds() {
+ put(" hello world ");
+ operate(StringOperation.trim(POLICY, BIN));
+ assertEquals("hello world", stringValue());
+ }
+
+ @Test
+ public void trimOnCleanStringIsNoOp() {
+ put("hello");
+ operate(StringOperation.trim(POLICY, BIN));
+ assertEquals("hello", stringValue());
+ }
+
+ @Test
+ public void trimStartRemovesLeadingWhitespaceOnly() {
+ put(" hello ");
+ operate(StringOperation.trimStart(POLICY, BIN));
+ assertEquals("hello ", stringValue());
+ }
+
+ @Test
+ public void trimEndRemovesTrailingWhitespaceOnly() {
+ put(" hello ");
+ operate(StringOperation.trimEnd(POLICY, BIN));
+ assertEquals(" hello", stringValue());
+ }
+
+ @Test
+ public void padStartFillsLeftToTargetLength() {
+ put("hello");
+ operate(StringOperation.padStart(POLICY, BIN, 10, "*"));
+ assertEquals("*****hello", stringValue());
+ }
+
+ @Test
+ public void padStartIsNoOpWhenAlreadyLongEnough() {
+ put("hello world");
+ operate(StringOperation.padStart(POLICY, BIN, 5, "*"));
+ assertEquals("hello world", stringValue());
+ }
+
+ @Test
+ public void padEndFillsRightToTargetLength() {
+ put("hello");
+ operate(StringOperation.padEnd(POLICY, BIN, 10, "."));
+ assertEquals("hello.....", stringValue());
+ }
+
+ @Test
+ public void padStartRepeatsMultiCharFiller() {
+ put("hi");
+ operate(StringOperation.padStart(POLICY, BIN, 8, "ab"));
+ assertEquals("abababhi", stringValue());
+ }
+
+ @Test
+ public void repeatDuplicatesContents() {
+ put("ab");
+ operate(StringOperation.repeat(POLICY, BIN, 3));
+ assertEquals("ababab", stringValue());
+ }
+
+ @Test
+ public void repeatOnceLeavesBinUnchanged() {
+ put("hello");
+ operate(StringOperation.repeat(POLICY, BIN, 1));
+ assertEquals("hello", stringValue());
+ }
+
+ @Test
+ public void concatAppendsSingleString() {
+ put(" hello world ");
+ operate(StringOperation.concat(POLICY, BIN, "!"));
+ assertEquals(" hello world !", stringValue());
+ }
+
+ @Test
+ public void concatAppendsListOfValues() {
+ put("hello");
+ operate(StringOperation.concat(POLICY, BIN, Arrays.asList(" ", "big", " world")));
+ assertEquals("hello big world", stringValue());
+ }
+
+ @Test
+ public void regexReplaceTargetsFirstMatchByDefault() {
+ put("abc123def456");
+ operate(StringOperation.regexReplace(POLICY, BIN, "[0-9]+", "NUM", StringRegexFlags.DEFAULT));
+ assertEquals("abcNUMdef456", stringValue());
+ }
+
+ @Test
+ public void regexReplaceWithGlobalFlagReplacesEveryMatch() {
+ put("abc123def456");
+ operate(StringOperation.regexReplace(POLICY, BIN, "[0-9]+", "NUM", StringRegexFlags.GLOBAL));
+ assertEquals("abcNUMdefNUM", stringValue());
+ }
+
+ @Test
+ public void regexReplaceWithNoMatchLeavesBinUnchanged() {
+ put("hello");
+ operate(StringOperation.regexReplace(POLICY, BIN, "[0-9]+", "NUM", StringRegexFlags.GLOBAL));
+ assertEquals("hello", stringValue());
+ }
+
+ //=================================================================
+ // Multi-op pipelines
+ //=================================================================
+
+ @Test
+ public void readsAcrossMultipleBinsInOneOperate() {
+ put(
+ new Bin("text", " hello world "),
+ new Bin("number_str", "12345"),
+ new Bin("upper_str", "HELLO"));
+
+ Record r = operate(
+ StringOperation.strlen("text"),
+ StringOperation.toInteger("number_str"),
+ StringOperation.isUpper("upper_str"));
+
+ // strlen and toInteger return INT; isUpper returns BOOL.
+ assertEquals(15L, r.getLong("text"));
+ assertEquals(12345L, r.getLong("number_str"));
+ assertTrue(r.getBoolean("upper_str"));
+ }
+
+ @Test
+ public void modifyAndReadInOneOperatePipelineCommitsThenObserves() {
+ put(" hello world ");
+
+ Record r = operate(
+ StringOperation.trim(POLICY, BIN),
+ StringOperation.upper(POLICY, BIN),
+ StringOperation.strlen(BIN));
+
+ // strlen runs after trim+upper so it sees the post-modification length.
+ assertEquals(11L, r.getLong(BIN));
+ assertEquals("HELLO WORLD", stringValue());
+ }
+
+ @Test
+ public void chainedReplaceAllAndPaddingComposeAsExpected() {
+ put("aabaa");
+
+ operate(
+ StringOperation.replaceAll(POLICY, BIN, "a", "x"),
+ StringOperation.padEnd(POLICY, BIN, 10, "."));
+
+ assertEquals("xxbxx.....", stringValue());
+ }
+
+ @Test
+ public void splitResultListEntriesAreReadableStrings() {
+ put("one,two,three");
+ Record r = operate(StringOperation.split(BIN, ","));
+
+ List tokens = r.getList(BIN);
+ assertEquals(3, tokens.size());
+ // Each entry should round-trip as a String regardless of internal encoding.
+ for (Object t : tokens) {
+ assertTrue("expected String element but got " + (t == null ? "null" : t.getClass()),
+ t instanceof String);
+ }
+ }
+
+ //=================================================================
+ // CTX navigation — string nested in list/map bins
+ //
+ // Exercises the §2.3.1 CTX-wrapper wire envelope: the op-data is
+ // wrapped in a 3-element context-eval array (sub-op 0xFF) when CTX
+ // is non-empty. The server dispatches these through
+ // as_bin_string_modify_ctx_tr / its read-side twin, which is a
+ // separate code path from the top-level-bin variant exercised above.
+ //=================================================================
+
+ private static void putList(List String expressions require server version 8.1.3+; the tests are skipped
+ * on older clusters via {@link Assume}.
+ *
+ * Unlike {@link com.aerospike.client.operation.StringOperation}, the
+ * expression path does not take a CTX directly. To target a
+ * string nested in a list/map, callers project the nested value via
+ * {@link ListExp#getByIndex} or {@link MapExp#getByKey} and feed the result
+ * as {@code src}. Two such cases are exercised at the end of this file.
+ */
+public class TestStringExp extends TestSync {
+ private static final String BIN = "sbin";
+ private static final String VAR = "v";
+ private static final Key KEY = new Key(args.namespace, args.set, "stringexp-key");
+ private static final StringPolicy POLICY = StringPolicy.Default;
+
+ @BeforeClass
+ public static void serverVersionCheck() {
+ Assume.assumeTrue(
+ "Skipping: string expressions require server version 8.1.3 or later",
+ args.serverVersion.isGreaterOrEqual(8, 1, 3, 0));
+ }
+
+ //-----------------------------------------------------------------
+ // Helpers
+ //-----------------------------------------------------------------
+
+ private static void put(String value) {
+ client.delete(null, KEY);
+ client.put(null, KEY, new Bin(BIN, value));
+ }
+
+ private static void putRaw(Bin bin) {
+ client.delete(null, KEY);
+ client.put(null, KEY, bin);
+ }
+
+ private static Record eval(Exp e) {
+ return client.operate(null, KEY,
+ ExpOperation.read(VAR, Exp.build(e), ExpReadFlags.DEFAULT));
+ }
+
+ //=================================================================
+ // Read expressions
+ //=================================================================
+
+ @Test
+ public void strlenReturnsCodepointCount() {
+ put("hello world");
+ Record r = eval(StringExp.strlen(Exp.stringBin(BIN)));
+ assertEquals(11L, r.getLong(VAR));
+ }
+
+ @Test
+ public void substrFromOffsetAndRange() {
+ put("hello world");
+ // Single-arg form: offset to end.
+ Record r1 = eval(StringExp.substr(Exp.val(6), Exp.stringBin(BIN)));
+ assertEquals("world", r1.getString(VAR));
+ // Two-arg form: [start, length).
+ Record r2 = eval(StringExp.substr(Exp.val(0), Exp.val(5), Exp.stringBin(BIN)));
+ assertEquals("hello", r2.getString(VAR));
+ }
+
+ @Test
+ public void charAtReturnsSingleCharacter() {
+ put("Hello123World");
+ Record r = eval(StringExp.charAt(Exp.val(5), Exp.stringBin(BIN)));
+ assertEquals("1", r.getString(VAR));
+ }
+
+ @Test
+ public void findReturnsIndexOfFirstAndNthMatch() {
+ put("ababab");
+ // Default (first match).
+ Record r1 = eval(StringExp.find(Exp.val("ab"), Exp.stringBin(BIN)));
+ assertEquals(0L, r1.getLong(VAR));
+ // Occurrence overload (1-based) — second occurrence starts at index 2.
+ Record r2 = eval(StringExp.find(Exp.val("ab"), Exp.val(2), Exp.stringBin(BIN)));
+ assertEquals(2L, r2.getLong(VAR));
+ }
+
+ @Test
+ public void containsReturnsBoolean() {
+ put("hello world");
+ Record present = eval(StringExp.contains(Exp.val("hello"), Exp.stringBin(BIN)));
+ Record absent = eval(StringExp.contains(Exp.val("xyz"), Exp.stringBin(BIN)));
+ assertTrue(present.getBoolean(VAR));
+ assertFalse(absent.getBoolean(VAR));
+ }
+
+ @Test
+ public void startsWithMatchesPrefix() {
+ put("Hello123World");
+ assertTrue(eval(StringExp.startsWith(Exp.val("Hello"), Exp.stringBin(BIN))).getBoolean(VAR));
+ assertFalse(eval(StringExp.startsWith(Exp.val("World"), Exp.stringBin(BIN))).getBoolean(VAR));
+ }
+
+ @Test
+ public void endsWithMatchesSuffix() {
+ put("Hello123World");
+ assertTrue(eval(StringExp.endsWith(Exp.val("World"), Exp.stringBin(BIN))).getBoolean(VAR));
+ assertFalse(eval(StringExp.endsWith(Exp.val("Hello"), Exp.stringBin(BIN))).getBoolean(VAR));
+ }
+
+ @Test
+ public void toIntegerParsesDigitsAsLong() {
+ put("12345");
+ Record r = eval(StringExp.toInteger(Exp.stringBin(BIN)));
+ assertEquals(12345L, r.getLong(VAR));
+ }
+
+ @Test
+ public void toDoubleParsesDecimalNumbers() {
+ put("3.14");
+ Record r = eval(StringExp.toDouble(Exp.stringBin(BIN)));
+ assertEquals(3.14, r.getDouble(VAR), 0.001);
+ }
+
+ @Test
+ public void byteLengthReturnsUtf8Bytes() {
+ put("hello");
+ Record r = eval(StringExp.byteLength(Exp.stringBin(BIN)));
+ assertEquals(5L, r.getLong(VAR));
+ }
+
+ @Test
+ public void isNumericMatchesIntegerStringsByDefaultAndByType() {
+ put("12345");
+ // Default (ANY): both ints and floats pass.
+ assertTrue(eval(StringExp.isNumeric(Exp.stringBin(BIN))).getBoolean(VAR));
+ // INT-only: still passes for pure-digit string.
+ assertTrue(eval(StringExp.isNumeric(StringNumericType.INT, Exp.stringBin(BIN))).getBoolean(VAR));
+ put("3.14");
+ // INT-only: fails for a float-shaped string.
+ assertFalse(eval(StringExp.isNumeric(StringNumericType.INT, Exp.stringBin(BIN))).getBoolean(VAR));
+ put("hello");
+ assertFalse(eval(StringExp.isNumeric(Exp.stringBin(BIN))).getBoolean(VAR));
+ }
+
+ @Test
+ public void isUpperAndIsLowerDistinguishCase() {
+ put("HELLO");
+ assertTrue(eval(StringExp.isUpper(Exp.stringBin(BIN))).getBoolean(VAR));
+ assertFalse(eval(StringExp.isLower(Exp.stringBin(BIN))).getBoolean(VAR));
+
+ put("hello");
+ assertFalse(eval(StringExp.isUpper(Exp.stringBin(BIN))).getBoolean(VAR));
+ assertTrue(eval(StringExp.isLower(Exp.stringBin(BIN))).getBoolean(VAR));
+ }
+
+ @Test
+ public void toBlobReturnsUtf8Bytes() {
+ put("hello");
+ Record r = eval(StringExp.toBlob(Exp.stringBin(BIN)));
+ assertArrayEquals("hello".getBytes(), (byte[])r.getValue(VAR));
+ }
+
+ @Test
+ public void splitWithAndWithoutSeparator() {
+ put("one,two,three");
+ Record r1 = eval(StringExp.split(Exp.val(","), Exp.stringBin(BIN)));
+ assertEquals(Arrays.asList("one", "two", "three"), r1.getList(VAR));
+
+ // No-separator form: per spec §2.4, returns one element per Unicode codepoint.
+ put("abc");
+ Record r2 = eval(StringExp.split(Exp.stringBin(BIN)));
+ assertEquals(Arrays.asList("a", "b", "c"), r2.getList(VAR));
+ }
+
+ @Test
+ public void b64DecodeReturnsOriginalBlob() {
+ put("aGVsbG8=");
+ Record r = eval(StringExp.b64Decode(Exp.stringBin(BIN)));
+ assertArrayEquals("hello".getBytes(), (byte[])r.getValue(VAR));
+ }
+
+ @Test
+ public void regexCompareWithAndWithoutCaseInsensitiveFlag() {
+ put("Hello123World");
+ assertTrue(eval(StringExp.regexCompare(
+ Exp.val("[0-9]+"), Exp.stringBin(BIN))).getBoolean(VAR));
+
+ put("HELLO");
+ assertFalse(eval(StringExp.regexCompare(
+ Exp.val("hello"), Exp.stringBin(BIN))).getBoolean(VAR));
+ assertTrue(eval(StringExp.regexCompare(
+ Exp.val("hello"), StringRegexFlags.CASE_INSENSITIVE,
+ Exp.stringBin(BIN))).getBoolean(VAR));
+ }
+
+ // Note: a literal-source variant (e.g. StringExp.regexCompare(Exp.val("[A-Z]+"),
+ // Exp.val("HELLO"))) is not exercised here. The server's expression engine returns
+ // OP_NOT_APPLICABLE (26) for that shape — the engine evaluates the literal but does
+ // not tag the resulting value as a STRING particle, so string_read's type check at
+ // particle_string.c:1040 rejects it. Spec §3.7 claims any string-yielding expression
+ // is accepted; the server does not honor that today. Bin-sourced regexCompare is
+ // covered in regexCompareWithAndWithoutCaseInsensitiveFlag above.
+
+ //=================================================================
+ // Modify expressions (return the modified string; do not persist)
+ //=================================================================
+
+ @Test
+ public void insertSplicesIntoSource() {
+ put("hello world");
+ Record r = eval(StringExp.insert(
+ POLICY, Exp.val(5), Exp.val(" beautiful"), Exp.stringBin(BIN)));
+ assertEquals("hello beautiful world", r.getString(VAR));
+ // Modify expressions do not persist — original bin is unchanged.
+ assertEquals("hello world", client.get(null, KEY).getString(BIN));
+ }
+
+ @Test
+ public void overwriteReplacesRange() {
+ put("hello world");
+ Record r = eval(StringExp.overwrite(
+ POLICY, Exp.val(6), Exp.val("earth"), Exp.stringBin(BIN)));
+ assertEquals("hello earth", r.getString(VAR));
+ }
+
+ @Test
+ public void concatAppendsListOfValues() {
+ put("hello");
+ Exp values = Exp.val(Arrays.asList(" ", "big", " world"));
+ Record r = eval(StringExp.concat(POLICY, values, Exp.stringBin(BIN)));
+ assertEquals("hello big world", r.getString(VAR));
+ }
+
+ @Test
+ public void snipRemovesRange() {
+ // Note: only the two-arg form is exercised. The server's snip op table
+ // (particle_string.c:443) requires (start, end[, flags]); the 1-arg client
+ // form [SNIP, start, flags] is silently misparsed — the trailing flags slot
+ // is read as `end`, producing a no-op when flags==DEFAULT==0.
+ put("hello beautiful world");
+ Record r = eval(StringExp.snip(POLICY, Exp.val(5), Exp.val(15), Exp.stringBin(BIN)));
+ assertEquals("hello world", r.getString(VAR));
+ }
+
+ @Test
+ public void replaceTouchesOnlyFirstMatch() {
+ put("hello world world");
+ Record r = eval(StringExp.replace(
+ POLICY, Exp.val("world"), Exp.val("earth"), Exp.stringBin(BIN)));
+ assertEquals("hello earth world", r.getString(VAR));
+ }
+
+ @Test
+ public void replaceAllSubstitutesEveryMatch() {
+ put("aabaa");
+ Record r = eval(StringExp.replaceAll(
+ POLICY, Exp.val("a"), Exp.val("x"), Exp.stringBin(BIN)));
+ assertEquals("xxbxx", r.getString(VAR));
+ }
+
+ @Test
+ public void upperAndLowerProduceCorrectCase() {
+ put("hello World");
+ assertEquals("HELLO WORLD",
+ eval(StringExp.upper(POLICY, Exp.stringBin(BIN))).getString(VAR));
+ assertEquals("hello world",
+ eval(StringExp.lower(POLICY, Exp.stringBin(BIN))).getString(VAR));
+ }
+
+ @Test
+ public void caseFoldLowercasesIndependentlyOfLocale() {
+ put("HELLO World");
+ Record r = eval(StringExp.caseFold(POLICY, Exp.stringBin(BIN)));
+ assertEquals("hello world", r.getString(VAR));
+ }
+
+ @Test
+ public void normalizeNFCLeavesAlreadyNormalizedStringUnchanged() {
+ put("hello");
+ Record r = eval(StringExp.normalizeNFC(POLICY, Exp.stringBin(BIN)));
+ assertEquals("hello", r.getString(VAR));
+ }
+
+ @Test
+ public void trimVariantsStripAppropriateEdges() {
+ put(" hello world ");
+ assertEquals("hello world",
+ eval(StringExp.trim(POLICY, Exp.stringBin(BIN))).getString(VAR));
+ assertEquals("hello world ",
+ eval(StringExp.trimStart(POLICY, Exp.stringBin(BIN))).getString(VAR));
+ assertEquals(" hello world",
+ eval(StringExp.trimEnd(POLICY, Exp.stringBin(BIN))).getString(VAR));
+ }
+
+ @Test
+ public void padStartFillsLeftToTargetLength() {
+ put("hello");
+ Record r = eval(StringExp.padStart(
+ POLICY, Exp.val(10), Exp.val("*"), Exp.stringBin(BIN)));
+ assertEquals("*****hello", r.getString(VAR));
+ }
+
+ @Test
+ public void padEndFillsRightToTargetLength() {
+ put("hello");
+ Record r = eval(StringExp.padEnd(
+ POLICY, Exp.val(10), Exp.val("."), Exp.stringBin(BIN)));
+ assertEquals("hello.....", r.getString(VAR));
+ }
+
+ @Test
+ public void repeatDuplicatesContents() {
+ put("ab");
+ Record r = eval(StringExp.repeat(POLICY, Exp.val(3), Exp.stringBin(BIN)));
+ assertEquals("ababab", r.getString(VAR));
+ }
+
+ @Test
+ public void regexReplaceFirstAndGlobal() {
+ put("abc123def456");
+ // Default: first match only.
+ Record r1 = eval(StringExp.regexReplace(
+ POLICY, Exp.val("[0-9]+"), Exp.val("NUM"),
+ StringRegexFlags.DEFAULT, Exp.stringBin(BIN)));
+ assertEquals("abcNUMdef456", r1.getString(VAR));
+
+ // GLOBAL: every match.
+ Record r2 = eval(StringExp.regexReplace(
+ POLICY, Exp.val("[0-9]+"), Exp.val("NUM"),
+ StringRegexFlags.GLOBAL, Exp.stringBin(BIN)));
+ assertEquals("abcNUMdefNUM", r2.getString(VAR));
+ }
+
+ //=================================================================
+ // Type conversion expression
+ //=================================================================
+
+ @Test
+ public void toStringConvertsIntegerBin() {
+ putRaw(new Bin(BIN, 42));
+ Record r = eval(StringExp.toString(Exp.intBin(BIN)));
+ assertEquals("42", r.getString(VAR));
+ }
+
+ //=================================================================
+ // Chained expressions — modify result feeds another StringExp
+ //=================================================================
+
+ @Test
+ public void chainedTrimThenUpperComposes() {
+ put(" hello world ");
+ // trim -> upper, both inside one expression tree.
+ Exp chain = StringExp.upper(
+ POLICY,
+ StringExp.trim(POLICY, Exp.stringBin(BIN)));
+ Record r = eval(chain);
+ assertEquals("HELLO WORLD", r.getString(VAR));
+ }
+
+ //=================================================================
+ // Filter-expression usage — predicate gates record retrieval
+ //=================================================================
+
+ @Test
+ public void startsWithFilterGatesGet() {
+ put("hello world");
+ Policy p = new Policy();
+
+ // Matching filter -> record returned.
+ p.filterExp = Exp.build(StringExp.startsWith(
+ Exp.val("hello"), Exp.stringBin(BIN)));
+ assertEquals("hello world", client.get(p, KEY).getString(BIN));
+
+ // Non-matching filter -> filtered out, get returns null.
+ p.filterExp = Exp.build(StringExp.startsWith(
+ Exp.val("world"), Exp.stringBin(BIN)));
+ assertEquals(null, client.get(p, KEY));
+ }
+
+ //=================================================================
+ // Nested-source — string inside a list/map projected via Exp getters
+ //
+ // StringExp does not accept CTX directly; callers compose with
+ // ListExp.getByIndex / MapExp.getByKey to project the nested string
+ // into an Exp and pass it as src.
+ //=================================================================
+
+ @Test
+ public void strlenOnStringNestedInListProjectedViaListExp() {
+ List Each test exercises one privilege boundary:
+ * The test bootstraps two extra users (one privileged reader, one
+ * unprivileged user) and connects an additional client per role. The whole
+ * class is skipped when security is disabled, no admin credentials are
+ * supplied, or the cluster is older than 8.1.3 (where masking + string ops
+ * are jointly supported).
+ */
+public class TestStringMasking extends TestSync {
+ private static final String MASKED_BIN = "pii";
+ private static final String UNMASKED_BIN = "public";
+ private static final String INITIAL_VALUE = "hello world";
+ private static final String INITIAL_PUBLIC = "visible data";
+ private static final String MASK_FUNCTION = "redact";
+
+ private static final String PRIV_USER = "stringops_reader";
+ private static final String UNPRIV_USER = "stringops_user";
+ private static final String USER_PASSWORD = "stringops_pw1!";
+
+ private static final Key KEY = new Key(args.namespace, args.set, "stringmask-key");
+ private static final StringPolicy POLICY = StringPolicy.Default;
+
+ private static boolean enabled;
+ private static IAerospikeClient privClient;
+ private static IAerospikeClient unprivClient;
+
+ @BeforeClass
+ public static void setupUsersAndRule() {
+ Assume.assumeTrue("Skipping: server version < 8.1.3 (string ops + masking)",
+ args.serverVersion.isGreaterOrEqual(8, 1, 3, 0));
+ Assume.assumeTrue("Skipping: admin credentials not provided",
+ args.user != null && !args.user.isEmpty()
+ && args.password != null && !args.password.isEmpty());
+
+ // Probe the cluster for security; bail out cleanly if it isn't enabled.
+ try {
+ client.queryRoles(new AdminPolicy());
+ }
+ catch (AerospikeException e) {
+ if (e.getResultCode() == ResultCode.SECURITY_NOT_ENABLED
+ || e.getResultCode() == ResultCode.SECURITY_NOT_SUPPORTED
+ || e.getResultCode() == ResultCode.NOT_AUTHENTICATED) {
+ Assume.assumeTrue("Skipping: security not enabled on cluster", false);
+ }
+ throw e;
+ }
+
+ dropUserQuiet(PRIV_USER);
+ dropUserQuiet(UNPRIV_USER);
+
+ AdminPolicy ap = new AdminPolicy();
+ client.createUser(ap, PRIV_USER, USER_PASSWORD,
+ Arrays.asList(Role.ReadWrite, Role.ReadMasked));
+ client.createUser(ap, UNPRIV_USER, USER_PASSWORD,
+ Arrays.asList(Role.ReadWrite));
+
+ privClient = newClient(PRIV_USER);
+ unprivClient = newClient(UNPRIV_USER);
+
+ applyMaskRule(MASKED_BIN, MASK_FUNCTION, null);
+ enabled = true;
+ }
+
+ @AfterClass
+ public static void tearDown() {
+ if (!enabled) {
+ return;
+ }
+ removeMaskRule(MASKED_BIN);
+
+ try {
+ AdminPolicy ap = new AdminPolicy();
+ dropUserQuiet(PRIV_USER);
+ dropUserQuiet(UNPRIV_USER);
+ // If queryRoles fires (it can race role propagation), let close still run.
+ client.queryRoles(ap);
+ }
+ catch (Exception ignored) {
+ }
+ finally {
+ closeQuiet(privClient);
+ closeQuiet(unprivClient);
+ }
+ }
+
+ @Before
+ public void resetRecord() {
+ client.delete(null, KEY);
+ client.put(null, KEY,
+ new Bin(MASKED_BIN, INITIAL_VALUE),
+ new Bin(UNMASKED_BIN, INITIAL_PUBLIC));
+ }
+
+ //=================================================================
+ // Read ops: privilege gates which value the caller observes
+ //=================================================================
+
+ @Test
+ public void readMaskedSeesRealValue_strlen() {
+ Record r = privClient.operate(null, KEY, StringOperation.strlen(MASKED_BIN));
+ assertEquals(INITIAL_VALUE.length(), r.getLong(MASKED_BIN));
+ }
+
+ @Test
+ public void readMaskedSeesRealValue_substr() {
+ Record r = privClient.operate(null, KEY, StringOperation.substr(MASKED_BIN, 0, 5));
+ assertEquals("hello", r.getString(MASKED_BIN));
+ }
+
+ @Test
+ public void unprivilegedSeesMaskedSubstring() {
+ Record r = unprivClient.operate(null, KEY, StringOperation.substr(MASKED_BIN, 0, 5));
+ // A full-redact rule should never let the underlying characters leak.
+ String value = r.getString(MASKED_BIN);
+ assertEquals(5, value.length());
+ assertNotEquals("hello", value);
+ }
+
+ @Test
+ public void unprivilegedFindOnMaskedBinDoesNotLocateRealContent() {
+ Record r = unprivClient.operate(null, KEY, StringOperation.find(MASKED_BIN, "world"));
+ assertEquals(-1L, r.getLong(MASKED_BIN));
+ }
+
+ @Test
+ public void unprivilegedContainsOnMaskedBinIsFalse() {
+ Record r = unprivClient.operate(null, KEY, StringOperation.contains(MASKED_BIN, "hello"));
+ assertFalse(r.getBoolean(MASKED_BIN));
+ }
+
+ @Test
+ public void unprivilegedStartsEndsOnMaskedBinAreFalse() {
+ Record sw = unprivClient.operate(null, KEY, StringOperation.startsWith(MASKED_BIN, "hello"));
+ Record ew = unprivClient.operate(null, KEY, StringOperation.endsWith(MASKED_BIN, "world"));
+ assertFalse(sw.getBoolean(MASKED_BIN));
+ assertFalse(ew.getBoolean(MASKED_BIN));
+ }
+
+ @Test
+ public void unprivilegedRegexCompareOnMaskedBinDoesNotMatchReal() {
+ Record r = unprivClient.operate(null, KEY, StringOperation.regexCompare(MASKED_BIN, "hello.*"));
+ assertFalse(r.getBoolean(MASKED_BIN));
+ }
+
+ @Test
+ public void strlenIsUnaffectedByRedaction() {
+ // Redact preserves length, so both clients agree on strlen/byteLength.
+ Record priv = privClient.operate(null, KEY, StringOperation.byteLength(MASKED_BIN));
+ Record unp = unprivClient.operate(null, KEY, StringOperation.byteLength(MASKED_BIN));
+ assertEquals(INITIAL_VALUE.length(), priv.getLong(MASKED_BIN));
+ assertEquals(INITIAL_VALUE.length(), unp.getLong(MASKED_BIN));
+ }
+
+ //=================================================================
+ // Read ops on the unmasked bin — both users see the real data
+ //=================================================================
+
+ @Test
+ public void unmaskedBinIsTransparentToBothUsers() {
+ Record priv = privClient.operate(null, KEY, StringOperation.strlen(UNMASKED_BIN));
+ Record unp = unprivClient.operate(null, KEY, StringOperation.strlen(UNMASKED_BIN));
+ assertEquals(INITIAL_PUBLIC.length(), priv.getLong(UNMASKED_BIN));
+ assertEquals(INITIAL_PUBLIC.length(), unp.getLong(UNMASKED_BIN));
+ }
+
+ //=================================================================
+ // Modify ops: blocked without write-masked
+ //=================================================================
+
+ @Test
+ public void writeMaskedRequired_upper() {
+ assertRoleViolation(() -> unprivClient.operate(null, KEY,
+ StringOperation.upper(POLICY, MASKED_BIN)));
+ }
+
+ @Test
+ public void writeMaskedRequired_insert() {
+ assertRoleViolation(() -> unprivClient.operate(null, KEY,
+ StringOperation.insert(POLICY, MASKED_BIN, 5, " beautiful")));
+ }
+
+ @Test
+ public void writeMaskedRequired_concat() {
+ assertRoleViolation(() -> unprivClient.operate(null, KEY,
+ StringOperation.concat(POLICY, MASKED_BIN, "!")));
+ }
+
+ @Test
+ public void writeMaskedRequired_replace() {
+ assertRoleViolation(() -> unprivClient.operate(null, KEY,
+ StringOperation.replace(POLICY, MASKED_BIN, "world", "earth")));
+ }
+
+ @Test
+ public void writeMaskedRequired_trim() {
+ client.put(null, KEY, new Bin(MASKED_BIN, " padded "));
+ assertRoleViolation(() -> unprivClient.operate(null, KEY,
+ StringOperation.trim(POLICY, MASKED_BIN)));
+ }
+
+ @Test
+ public void writeMaskedRequired_padStart() {
+ assertRoleViolation(() -> unprivClient.operate(null, KEY,
+ StringOperation.padStart(POLICY, MASKED_BIN, 20, "*")));
+ }
+
+ @Test
+ public void writeMaskedRequired_regexReplace() {
+ assertRoleViolation(() -> unprivClient.operate(null, KEY,
+ StringOperation.regexReplace(POLICY, MASKED_BIN, "[0-9]+", "NUM", 0)));
+ }
+
+ //=================================================================
+ // Read-masked still cannot modify; admin still can.
+ //=================================================================
+
+ @Test
+ public void readMaskedCannotModify() {
+ assertRoleViolation(() -> privClient.operate(null, KEY,
+ StringOperation.upper(POLICY, MASKED_BIN)));
+ }
+
+ @Test
+ public void adminModifyOnMaskedBinSucceeds() {
+ client.operate(null, KEY, StringOperation.upper(POLICY, MASKED_BIN));
+ Record r = client.get(null, KEY);
+ assertEquals("HELLO WORLD", r.getString(MASKED_BIN));
+ }
+
+ //=================================================================
+ // Modify on unmasked bin succeeds for unprivileged user.
+ //=================================================================
+
+ @Test
+ public void unprivilegedCanModifyUnmaskedBin() {
+ unprivClient.operate(null, KEY, StringOperation.upper(POLICY, UNMASKED_BIN));
+ Record r = client.get(null, KEY);
+ assertEquals("VISIBLE DATA", r.getString(UNMASKED_BIN));
+ // The masked bin is left untouched.
+ assertEquals(INITIAL_VALUE, r.getString(MASKED_BIN));
+ }
+
+ //=================================================================
+ // Constant-mask variant: unprivileged sees a fixed string
+ //=================================================================
+
+ @Test
+ public void constantMaskIsObservedByUnprivilegedRead() {
+ final String constBin = "secret";
+ final String constValue = "HIDDEN";
+ final String real = "real secret data";
+ final Key key = new Key(args.namespace, args.set, "stringmask-const");
+
+ applyMaskRule(constBin, "constant", "value=" + constValue);
+ try {
+ client.delete(null, key);
+ client.put(null, key, new Bin(constBin, real));
+
+ Record priv = privClient.operate(null, key, StringOperation.strlen(constBin));
+ Record unp = unprivClient.operate(null, key, StringOperation.strlen(constBin));
+ assertEquals(real.length(), priv.getLong(constBin));
+ assertEquals(constValue.length(), unp.getLong(constBin));
+
+ Record privSub = privClient.operate(null, key, StringOperation.substr(constBin, 0, 4));
+ Record unpSub = unprivClient.operate(null, key, StringOperation.substr(constBin, 0, 4));
+ assertEquals("real", privSub.getString(constBin));
+ assertEquals("HIDD", unpSub.getString(constBin));
+ }
+ finally {
+ client.delete(null, key);
+ removeMaskRule(constBin);
+ }
+ }
+
+ //=================================================================
+ // Helpers
+ //=================================================================
+
+ private interface OperateCall {
+ void run();
+ }
+
+ private static void assertRoleViolation(OperateCall call) {
+ try {
+ call.run();
+ fail("Expected ROLE_VIOLATION");
+ }
+ catch (AerospikeException e) {
+ assertEquals(ResultCode.ROLE_VIOLATION, e.getResultCode());
+ }
+ }
+
+ private static IAerospikeClient newClient(String user) {
+ ClientPolicy p = new ClientPolicy();
+ args.setClientPolicy(p);
+ p.user = user;
+ p.password = USER_PASSWORD;
+ return new AerospikeClient(p, Host.parseHosts(args.host, args.port));
+ }
+
+ private static void closeQuiet(IAerospikeClient c) {
+ if (c != null) {
+ try { c.close(); } catch (Exception ignored) {}
+ }
+ }
+
+ private static void dropUserQuiet(String user) {
+ try {
+ client.dropUser(new AdminPolicy(), user);
+ }
+ catch (AerospikeException ignored) {
+ // User did not exist; nothing to do.
+ }
+ }
+
+ /**
+ * Apply a masking rule via info command. Format:
+ * {@code masking:namespace=NS;set=SET;bin=BIN;type=string;function=FN[;extra]}
+ */
+ private static void applyMaskRule(String bin, String function, String extra) {
+ StringBuilder cmd = new StringBuilder("masking:namespace=")
+ .append(args.namespace)
+ .append(";set=").append(args.set)
+ .append(";bin=").append(bin)
+ .append(";type=string;function=").append(function);
+ if (extra != null && !extra.isEmpty()) {
+ cmd.append(';').append(extra);
+ }
+ infoOnAllNodes(cmd.toString());
+ }
+
+ private static void removeMaskRule(String bin) {
+ String cmd = "masking:namespace=" + args.namespace
+ + ";set=" + args.set
+ + ";bin=" + bin
+ + ";type=string;function=remove";
+ infoOnAllNodes(cmd);
+ }
+
+ private static void infoOnAllNodes(String cmd) {
+ List
+ *
+ *
+ *