From 82f279f179207f09088d863fb1857e27386fe661 Mon Sep 17 00:00:00 2001 From: Mirza Karacic Date: Tue, 5 May 2026 12:19:47 -0700 Subject: [PATCH 1/9] Changes for string operations --- .../src/com/aerospike/client/Operation.java | 5 +- .../com/aerospike/client/exp/StringExp.java | 499 +++++++++++++++ .../client/operation/StringNumericType.java | 37 ++ .../client/operation/StringOperation.java | 523 ++++++++++++++++ .../client/operation/StringPolicy.java | 52 ++ .../client/operation/StringRegexFlags.java | 55 ++ .../client/operation/StringWriteFlags.java | 38 ++ test/src/com/aerospike/test/SuiteSync.java | 4 + .../test/sync/basic/TestOperateString.java | 571 ++++++++++++++++++ .../test/sync/basic/TestStringMasking.java | 407 +++++++++++++ 10 files changed, 2190 insertions(+), 1 deletion(-) create mode 100644 client/src/com/aerospike/client/exp/StringExp.java create mode 100644 client/src/com/aerospike/client/operation/StringNumericType.java create mode 100644 client/src/com/aerospike/client/operation/StringOperation.java create mode 100644 client/src/com/aerospike/client/operation/StringPolicy.java create mode 100644 client/src/com/aerospike/client/operation/StringRegexFlags.java create mode 100644 client/src/com/aerospike/client/operation/StringWriteFlags.java create mode 100644 test/src/com/aerospike/test/sync/basic/TestOperateString.java create mode 100644 test/src/com/aerospike/test/sync/basic/TestStringMasking.java diff --git a/client/src/com/aerospike/client/Operation.java b/client/src/com/aerospike/client/Operation.java index 56400cb7e..977b0ea59 100644 --- a/client/src/com/aerospike/client/Operation.java +++ b/client/src/com/aerospike/client/Operation.java @@ -111,7 +111,10 @@ public static enum Type { BIT_MODIFY(13, true), DELETE(14, true), HLL_READ(15, false), - HLL_MODIFY(16, true); + HLL_MODIFY(16, true), + STRING_READ(17, false), + STRING_MODIFY(18, true), + TO_STRING(19, false); public final int protocolType; public final boolean isWrite; diff --git a/client/src/com/aerospike/client/exp/StringExp.java b/client/src/com/aerospike/client/exp/StringExp.java new file mode 100644 index 000000000..0b23a670e --- /dev/null +++ b/client/src/com/aerospike/client/exp/StringExp.java @@ -0,0 +1,499 @@ +/* + * 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.exp; + +import com.aerospike.client.operation.StringPolicy; +import com.aerospike.client.operation.StringRegexFlags; +import com.aerospike.client.util.Pack; +import com.aerospike.client.util.Packer; + +/** + * String expression generator. See {@link com.aerospike.client.exp.Exp}. + *

+ * The string source argument in these methods is any expression that yields a + * string: a bin reference (e.g. {@link Exp#stringBin(String)}), a string literal + * ({@link Exp#val(String)}), or a nested string expression. Expressions that + * modify a string value return the modified string; the bin is not changed. + *

+ * String expressions require server version 8.1.3 or later. + */ +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 B64_ENCODE = 16; + private static final int REGEX_COMPARE = 17; + + // 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 codepoint length of the source string. + */ + public static Exp strlen(Exp src) { + byte[] bytes = Pack.pack(STRLEN); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that returns the substring from {@code start} to the end of the source. + */ + 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 starting at {@code start}. + */ + 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 character at {@code index} as a 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 match of + * {@code needle} in the source, or -1 if not found. + */ + 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}, or -1 if not found. + */ + 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 returns 1 if the source contains {@code needle}, 0 otherwise. + */ + public static Exp contains(Exp needle, Exp src) { + byte[] bytes = Pack.pack(CONTAINS, needle); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that returns 1 if the source begins with {@code prefix}, 0 otherwise. + */ + public static Exp startsWith(Exp prefix, Exp src) { + byte[] bytes = Pack.pack(STARTS_WITH, prefix); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that returns 1 if the source ends with {@code suffix}, 0 otherwise. + */ + public static Exp endsWith(Exp suffix, Exp src) { + byte[] bytes = Pack.pack(ENDS_WITH, suffix); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that parses the source as int64. + */ + public static Exp toInteger(Exp src) { + byte[] bytes = Pack.pack(TO_INTEGER); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that parses the source as a 64-bit float. + */ + 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 the source. + */ + public static Exp byteLength(Exp src) { + byte[] bytes = Pack.pack(BYTE_LENGTH); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that returns 1 if the source parses as a number, 0 otherwise. + */ + public static Exp isNumeric(Exp src) { + byte[] bytes = Pack.pack(IS_NUMERIC); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that returns 1 if the source parses as a number of the requested + * {@link com.aerospike.client.operation.StringNumericType}, 0 otherwise. + */ + public static Exp isNumeric(int numericType, Exp src) { + byte[] bytes = Pack.pack(IS_NUMERIC, numericType); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that returns 1 if every cased character in the source is uppercase. + */ + public static Exp isUpper(Exp src) { + byte[] bytes = Pack.pack(IS_UPPER); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that returns 1 if every cased character in the source is lowercase. + */ + public static Exp isLower(Exp src) { + byte[] bytes = Pack.pack(IS_LOWER); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that returns the UTF-8 bytes of the source as a blob. + */ + public static Exp toBlob(Exp src) { + byte[] bytes = Pack.pack(TO_BLOB); + return addRead(src, bytes, Exp.Type.BLOB); + } + + /** + * Create expression that splits the source by Unicode codepoint and returns a list of strings. + */ + public static Exp split(Exp src) { + byte[] bytes = Pack.pack(SPLIT); + return addRead(src, bytes, Exp.Type.LIST); + } + + /** + * Create expression that splits the source by {@code separator} and returns a list of strings. + */ + 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 the source and returns a blob. + */ + public static Exp b64Decode(Exp src) { + byte[] bytes = Pack.pack(B64_DECODE); + return addRead(src, bytes, Exp.Type.BLOB); + } + + /** + * Create expression that base64-encodes a blob source as a string. + */ + public static Exp b64Encode(Exp src) { + byte[] bytes = Pack.pack(B64_ENCODE); + return addRead(src, bytes, Exp.Type.STRING); + } + + /** + * Create expression that returns 1 if {@code pattern} (ICU regex) matches the source, 0 otherwise. + */ + public static Exp regexCompare(Exp pattern, Exp src) { + byte[] bytes = Pack.pack(REGEX_COMPARE, pattern); + return addRead(src, bytes, Exp.Type.INT); + } + + /** + * Create expression that returns 1 if {@code pattern} (ICU regex) matches the source under + * {@link StringRegexFlags}, 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.INT); + } + + //----------------------------------------------------------------- + // Modify expressions + //----------------------------------------------------------------- + + /** + * Create expression that inserts {@code value} at codepoint {@code index} of the source + * and returns the resulting 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 characters starting at codepoint {@code index} with + * {@code value} and returns the resulting 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 the source + * and returns the resulting string. Single-string callers can wrap their value in a + * 1-element list via {@link Exp#val(java.util.List)}. + */ + 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 characters from codepoint {@code start} to the end of + * the source and returns the resulting 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 characters from codepoint {@code start} (inclusive) to + * {@code end} (exclusive) and returns the resulting 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} with {@code replacement} + * and returns the resulting 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} with {@code replacement} + * and returns the resulting 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 the source uppercased. + */ + public static Exp upper(StringPolicy policy, Exp src) { + byte[] bytes = Pack.pack(UPPER, policy.flags); + return addModify(src, bytes); + } + + /** + * Create expression that returns the source lowercased. + */ + public static Exp lower(StringPolicy policy, Exp src) { + byte[] bytes = Pack.pack(LOWER, policy.flags); + return addModify(src, bytes); + } + + /** + * Create expression that returns the source case-folded (locale-independent lowercase). + */ + public static Exp caseFold(StringPolicy policy, Exp src) { + byte[] bytes = Pack.pack(CASE_FOLD, policy.flags); + return addModify(src, bytes); + } + + /** + * Create expression that returns the source normalized to Unicode NFC form. + */ + public static Exp normalizeNFC(StringPolicy policy, Exp src) { + byte[] bytes = Pack.pack(NORMALIZE_NFC, policy.flags); + return addModify(src, bytes); + } + + /** + * Create expression that returns the source with whitespace removed from the start. + */ + public static Exp trimStart(StringPolicy policy, Exp src) { + byte[] bytes = Pack.pack(TRIM_START, policy.flags); + return addModify(src, bytes); + } + + /** + * Create expression that returns the source with whitespace removed from the end. + */ + public static Exp trimEnd(StringPolicy policy, Exp src) { + byte[] bytes = Pack.pack(TRIM_END, policy.flags); + return addModify(src, bytes); + } + + /** + * Create expression that returns the source with whitespace removed from both ends. + */ + public static Exp trim(StringPolicy policy, Exp src) { + byte[] bytes = Pack.pack(TRIM, policy.flags); + return addModify(src, bytes); + } + + /** + * Create expression that pads the start of the source to {@code targetLength} codepoints + * using {@code padString}. + */ + 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 pads the end of the source to {@code targetLength} codepoints + * using {@code padString}. + */ + 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 the source repeated {@code count} times. + */ + 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) with + * {@code replacement} and returns the resulting string. Use + * {@link StringRegexFlags#GLOBAL} to replace all matches. + */ + public static Exp regexReplace( + StringPolicy policy, + Exp pattern, + Exp replacement, + int regexFlags, + Exp src + ) { + byte[] bytes = packRegexReplace(pattern, replacement, regexFlags, policy.flags); + 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. + */ + public static Exp toString(Exp src) { + byte[] bytes = emptyArray(); + 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); + } + + // [cmd, [needle, repl], flags] — needle/replacement nested inside a 2-element list. + private static byte[] packReplace(int command, Exp needle, Exp replacement, int flags) { + Packer packer = new Packer(); + for (int i = 0; i < 2; i++) { + packer.packArrayBegin(3); + packer.packInt(command); + packer.packArrayBegin(2); + needle.pack(packer); + replacement.pack(packer); + packer.packInt(flags); + if (i == 0) packer.createBuffer(); + } + return packer.getBuffer(); + } + + // [REGEX_REPLACE, [pattern, repl], regexFlags, flags] + private static byte[] packRegexReplace(Exp pattern, Exp replacement, int regexFlags, int flags) { + Packer packer = new Packer(); + for (int i = 0; i < 2; i++) { + packer.packArrayBegin(4); + packer.packInt(REGEX_REPLACE); + packer.packArrayBegin(2); + pattern.pack(packer); + replacement.pack(packer); + packer.packInt(regexFlags); + packer.packInt(flags); + if (i == 0) packer.createBuffer(); + } + return packer.getBuffer(); + } + + private static byte[] emptyArray() { + Packer packer = new Packer(); + for (int i = 0; i < 2; i++) { + packer.packArrayBegin(0); + if (i == 0) packer.createBuffer(); + } + return packer.getBuffer(); + } +} diff --git a/client/src/com/aerospike/client/operation/StringNumericType.java b/client/src/com/aerospike/client/operation/StringNumericType.java new file mode 100644 index 000000000..d85626811 --- /dev/null +++ b/client/src/com/aerospike/client/operation/StringNumericType.java @@ -0,0 +1,37 @@ +/* + * 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; + +/** + * Numeric type filter for {@link StringOperation#isNumeric}. + */ +public final class StringNumericType { + /** + * Match either an integer or a floating-point number. + */ + public static final int ANY = 0; + + /** + * Match only integers. + */ + public static final int INT = 1; + + /** + * Match only floating-point numbers. + */ + public static final int FLOAT = 2; +} diff --git a/client/src/com/aerospike/client/operation/StringOperation.java b/client/src/com/aerospike/client/operation/StringOperation.java new file mode 100644 index 000000000..56336e91c --- /dev/null +++ b/client/src/com/aerospike/client/operation/StringOperation.java @@ -0,0 +1,523 @@ +/* + * 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; + +import java.util.ArrayList; +import java.util.List; + +import com.aerospike.client.Operation; +import com.aerospike.client.Value; +import com.aerospike.client.util.Pack; +import com.aerospike.client.util.Packer; + +/** + * String operations. Create string operations used by the client operate command. + *

+ * Index orientation is left-to-right with codepoint addressing. Negative indexes + * count from the end of the string ({@code -1} = last character). Out-of-bounds + * indexes are clamped to the valid range; no error is returned. + *

+ * String operations require server version 8.1.3 or later. Operations on string + * items nested in lists/maps are not currently supported by the server. + */ +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 B64_ENCODE = 16; + private static final int REGEX_COMPARE = 17; + + // 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. + * Server returns the number of unicode codepoints in the string bin (int64). + */ + public static Operation strlen(String binName) { + byte[] bytes = Pack.pack(STRLEN); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code substr} operation that reads from {@code start} to the end of the string. + * Negative indexes count from the end. + */ + public static Operation substr(String binName, int start) { + byte[] bytes = Pack.pack(SUBSTR, start); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code substr} operation that reads {@code length} codepoints starting at {@code start}. + * Negative indexes count from the end of the string. + */ + public static Operation substr(String binName, int start, int length) { + byte[] bytes = Pack.pack(SUBSTR, start, length); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code charAt} operation. Server returns the character at {@code index} as a string. + * Negative indexes count from the end of the string. + */ + public static Operation charAt(String binName, int index) { + byte[] bytes = Pack.pack(CHAR_AT, index); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code find} operation. Server returns the codepoint index of the first + * occurrence of {@code needle}, or -1 if not found. + */ + public static Operation find(String binName, String needle) { + byte[] bytes = Pack.pack(FIND, Value.get(needle)); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code find} operation. Server returns the codepoint index of the + * {@code occurrence}-th match of {@code needle} (1 = first match), or -1 if not found. + */ + public static Operation find(String binName, String needle, int occurrence) { + byte[] bytes = packCmdValueInt(FIND, Value.get(needle), occurrence); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code contains} operation. Server returns 1 if the bin contains + * {@code needle} as a substring, 0 otherwise. + */ + public static Operation contains(String binName, String needle) { + byte[] bytes = Pack.pack(CONTAINS, Value.get(needle)); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code startsWith} operation. Server returns 1 if the bin begins with + * {@code prefix}, 0 otherwise. + */ + public static Operation startsWith(String binName, String prefix) { + byte[] bytes = Pack.pack(STARTS_WITH, Value.get(prefix)); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code endsWith} operation. Server returns 1 if the bin ends with + * {@code suffix}, 0 otherwise. + */ + public static Operation endsWith(String binName, String suffix) { + byte[] bytes = Pack.pack(ENDS_WITH, Value.get(suffix)); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code toInteger} operation. Server parses the string as an int64. + * Returns AEROSPIKE_ERR_PARAMETER if the bin cannot be parsed as an integer. + */ + public static Operation toInteger(String binName) { + byte[] bytes = Pack.pack(TO_INTEGER); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code toDouble} operation. Server parses the string as a 64-bit float. + * Returns AEROSPIKE_ERR_PARAMETER if the bin cannot be parsed as a double. + */ + public static Operation toDouble(String binName) { + byte[] bytes = Pack.pack(TO_DOUBLE); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code byteLength} operation. Server returns the UTF-8 byte length + * of the string (int64). + */ + public static Operation byteLength(String binName) { + byte[] bytes = Pack.pack(BYTE_LENGTH); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code isNumeric} operation. Server returns 1 if the bin contains a valid + * integer or float, 0 otherwise. + */ + public static Operation isNumeric(String binName) { + byte[] bytes = Pack.pack(IS_NUMERIC); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code isNumeric} operation that filters by {@code numericType} + * (see {@link StringNumericType}). + */ + public static Operation isNumeric(String binName, int numericType) { + byte[] bytes = Pack.pack(IS_NUMERIC, numericType); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code isUpper} operation. Server returns 1 if every cased character + * in the bin is uppercase, 0 otherwise. + */ + public static Operation isUpper(String binName) { + byte[] bytes = Pack.pack(IS_UPPER); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code isLower} operation. Server returns 1 if every cased character + * in the bin is lowercase, 0 otherwise. + */ + public static Operation isLower(String binName) { + byte[] bytes = Pack.pack(IS_LOWER); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code toBlob} operation. Server returns the UTF-8 bytes of the string + * as a blob. + */ + public static Operation toBlob(String binName) { + byte[] bytes = Pack.pack(TO_BLOB); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code split} operation that splits by Unicode codepoint + * (each codepoint becomes its own list element). + */ + public static Operation split(String binName) { + byte[] bytes = Pack.pack(SPLIT); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code split} operation that splits by {@code separator}. + * Server returns a list of strings. + */ + public static Operation split(String binName, String separator) { + byte[] bytes = Pack.pack(SPLIT, Value.get(separator)); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code b64Decode} operation. Server base64-decodes the string and + * returns a blob. + */ + public static Operation b64Decode(String binName) { + byte[] bytes = Pack.pack(B64_DECODE); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code b64Encode} operation. Bin must be a blob; server returns the + * base64-encoded string. Returns AEROSPIKE_ERR_INCOMPATIBLE_TYPE if the bin is a string. + */ + public static Operation b64Encode(String binName) { + byte[] bytes = Pack.pack(B64_ENCODE); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code regexCompare} operation. Server matches {@code pattern} (ICU + * regex syntax) against the bin and returns 1 on match, 0 otherwise. + */ + public static Operation regexCompare(String binName, String pattern) { + byte[] bytes = Pack.pack(REGEX_COMPARE, Value.get(pattern)); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + /** + * Create string {@code regexCompare} operation with {@link StringRegexFlags}. + */ + public static Operation regexCompare(String binName, String pattern, int regexFlags) { + byte[] bytes = packCmdValueInt(REGEX_COMPARE, Value.get(pattern), regexFlags); + return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + } + + //----------------------------------------------------------------- + // Modify operations + //----------------------------------------------------------------- + + /** + * Create string {@code insert} operation that inserts {@code value} at codepoint + * {@code index}. Negative indexes count from the end of the string. + */ + public static Operation insert(StringPolicy policy, String binName, int index, String value) { + byte[] bytes = Pack.pack(INSERT, index, Value.get(value), policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code overwrite} operation that overwrites characters starting at + * codepoint {@code index} with {@code value}. + */ + public static Operation overwrite(StringPolicy policy, String binName, int index, String value) { + byte[] bytes = Pack.pack(OVERWRITE, index, Value.get(value), policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code concat} operation that appends {@code value} to the bin. + */ + public static Operation concat(StringPolicy policy, String binName, String value) { + List list = new ArrayList(1); + list.add(Value.get(value)); + byte[] bytes = Pack.pack(CONCAT, list, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code concat} operation that appends every element of {@code values} + * to the bin in order. + */ + public static Operation concat(StringPolicy policy, String binName, List values) { + List list = toValueList(values); + byte[] bytes = Pack.pack(CONCAT, list, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code snip} operation that removes characters starting at codepoint + * {@code start} through the end of the string. + */ + public static Operation snip(StringPolicy policy, String binName, int start) { + byte[] bytes = Pack.pack(SNIP, start, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code snip} operation that removes characters from codepoint + * {@code start} (inclusive) to {@code end} (exclusive). + */ + public static Operation snip(StringPolicy policy, String binName, int start, int end) { + byte[] bytes = Pack.pack(SNIP, start, end, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code replace} operation that replaces the first occurrence of + * {@code needle} with {@code replacement}. + */ + public static Operation replace(StringPolicy policy, String binName, String needle, String replacement) { + List list = pair(needle, replacement); + byte[] bytes = Pack.pack(REPLACE, list, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code replaceAll} operation that replaces every occurrence of + * {@code needle} with {@code replacement}. + */ + public static Operation replaceAll(StringPolicy policy, String binName, String needle, String replacement) { + List list = pair(needle, replacement); + byte[] bytes = Pack.pack(REPLACE_ALL, list, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code upper} operation that uppercases the bin in place. + */ + public static Operation upper(StringPolicy policy, String binName) { + byte[] bytes = Pack.pack(UPPER, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code lower} operation that lowercases the bin in place. + */ + public static Operation lower(StringPolicy policy, String binName) { + byte[] bytes = Pack.pack(LOWER, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code caseFold} operation. Server applies a locale-independent case + * fold (lowercase) to the bin. + */ + public static Operation caseFold(StringPolicy policy, String binName) { + byte[] bytes = Pack.pack(CASE_FOLD, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code normalizeNFC} operation. Server normalizes the bin to Unicode + * NFC form. + */ + public static Operation normalizeNFC(StringPolicy policy, String binName) { + byte[] bytes = Pack.pack(NORMALIZE_NFC, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code trimStart} operation that removes whitespace from the start + * of the bin. + */ + public static Operation trimStart(StringPolicy policy, String binName) { + byte[] bytes = Pack.pack(TRIM_START, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code trimEnd} operation that removes whitespace from the end of + * the bin. + */ + public static Operation trimEnd(StringPolicy policy, String binName) { + byte[] bytes = Pack.pack(TRIM_END, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code trim} operation that removes whitespace from both ends of + * the bin. + */ + public static Operation trim(StringPolicy policy, String binName) { + byte[] bytes = Pack.pack(TRIM, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code padStart} operation. Server prepends {@code padString} repeatedly + * until the bin reaches {@code targetLength} codepoints. No-op if already at or above + * target length. + */ + public static Operation padStart(StringPolicy policy, String binName, int targetLength, String padString) { + byte[] bytes = Pack.pack(PAD_START, targetLength, Value.get(padString), policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code padEnd} operation. Server appends {@code padString} repeatedly + * until the bin reaches {@code targetLength} codepoints. No-op if already at or above + * target length. + */ + public static Operation padEnd(StringPolicy policy, String binName, int targetLength, String padString) { + byte[] bytes = Pack.pack(PAD_END, targetLength, Value.get(padString), policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code repeat} operation that repeats the bin contents {@code count} + * times. + */ + public static Operation repeat(StringPolicy policy, String binName, int count) { + byte[] bytes = Pack.pack(REPEAT, count, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + /** + * Create string {@code regexReplace} operation that replaces the first match of + * {@code pattern} with {@code replacement}. Use {@link StringRegexFlags#GLOBAL} + * to replace all matches. + */ + public static Operation regexReplace( + StringPolicy policy, + String binName, + String pattern, + String replacement, + int regexFlags + ) { + List list = pair(pattern, replacement); + byte[] bytes = Pack.pack(REGEX_REPLACE, list, regexFlags, policy.flags); + return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + } + + //----------------------------------------------------------------- + // Type conversion + //----------------------------------------------------------------- + + /** + * Create {@code toString} operation that converts an integer, float, string, or blob + * bin to its string representation. Returns AEROSPIKE_ERR_INCOMPATIBLE_TYPE for any + * other bin type. + *

+ * The wire format for this op carries no payload; the bin is referenced solely by + * the operation header. + */ + public static Operation toString(String binName) { + return new Operation(Operation.Type.TO_STRING, binName, Value.getAsNull()); + } + + //----------------------------------------------------------------- + // Private helpers + //----------------------------------------------------------------- + + private static List pair(String a, String b) { + List list = new ArrayList(2); + list.add(Value.get(a)); + list.add(Value.get(b)); + return list; + } + + private static List toValueList(List strings) { + List list = new ArrayList(strings.size()); + for (String s : strings) { + list.add(Value.get(s)); + } + return list; + } + + private static byte[] packCmdValueInt(int command, Value value, int v) { + Packer packer = new Packer(); + for (int i = 0; i < 2; i++) { + packer.packArrayBegin(3); + packer.packInt(command); + value.pack(packer); + packer.packInt(v); + + if (i == 0) { + packer.createBuffer(); + } + } + return packer.getBuffer(); + } +} diff --git a/client/src/com/aerospike/client/operation/StringPolicy.java b/client/src/com/aerospike/client/operation/StringPolicy.java new file mode 100644 index 000000000..c3c82f861 --- /dev/null +++ b/client/src/com/aerospike/client/operation/StringPolicy.java @@ -0,0 +1,52 @@ +/* + * 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. + *

+ * 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/test/src/com/aerospike/test/SuiteSync.java b/test/src/com/aerospike/test/SuiteSync.java index 9b4c9e272..57512c085 100644 --- a/test/src/com/aerospike/test/SuiteSync.java +++ b/test/src/com/aerospike/test/SuiteSync.java @@ -47,11 +47,13 @@ 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.TestStringMasking; import com.aerospike.test.sync.basic.TestTouch; import com.aerospike.test.sync.basic.TestTxn; import com.aerospike.test.sync.basic.TestUDF; @@ -97,11 +99,13 @@ TestOperateHll.class, TestOperateList.class, TestOperateMap.class, + TestOperateString.class, TestPutGet.class, TestQueryRoles.class, TestReplace.class, TestScan.class, TestServerInfo.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..a29bbabed --- /dev/null +++ b/test/src/com/aerospike/test/sync/basic/TestOperateString.java @@ -0,0 +1,571 @@ +/* + * 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.assertTrue; + +import java.util.Arrays; +import java.util.List; + +import org.junit.Assume; +import org.junit.BeforeClass; +import org.junit.Test; + +import com.aerospike.client.Bin; +import com.aerospike.client.Key; +import com.aerospike.client.Operation; +import com.aerospike.client.Record; +import com.aerospike.client.operation.StringOperation; +import com.aerospike.client.operation.StringPolicy; +import com.aerospike.client.operation.StringRegexFlags; +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 containsReturnsBooleanIntegers() { + put("hello world"); + Record present = operate(StringOperation.contains(BIN, "hello")); + Record absent = operate(StringOperation.contains(BIN, "xyz")); + assertEquals(1L, present.getLong(BIN)); + assertEquals(0L, absent.getLong(BIN)); + } + + @Test + public void startsWithMatchesPrefix() { + put("Hello123World"); + assertEquals(1L, operate(StringOperation.startsWith(BIN, "Hello")).getLong(BIN)); + assertEquals(0L, operate(StringOperation.startsWith(BIN, "World")).getLong(BIN)); + } + + @Test + public void endsWithMatchesSuffix() { + put("Hello123World"); + assertEquals(1L, operate(StringOperation.endsWith(BIN, "World")).getLong(BIN)); + assertEquals(0L, operate(StringOperation.endsWith(BIN, "Hello")).getLong(BIN)); + } + + @Test + public void isUpperOnlyTrueForUppercase() { + put("HELLO"); + assertEquals(1L, operate(StringOperation.isUpper(BIN)).getLong(BIN)); + put("hello"); + assertEquals(0L, operate(StringOperation.isUpper(BIN)).getLong(BIN)); + } + + @Test + public void isLowerOnlyTrueForLowercase() { + put("hello"); + assertEquals(1L, operate(StringOperation.isLower(BIN)).getLong(BIN)); + put("HELLO"); + assertEquals(0L, operate(StringOperation.isLower(BIN)).getLong(BIN)); + } + + @Test + public void isNumericMatchesIntegerStrings() { + put("12345"); + assertEquals(1L, operate(StringOperation.isNumeric(BIN)).getLong(BIN)); + put("Hello123World"); + assertEquals(0L, operate(StringOperation.isNumeric(BIN)).getLong(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"); + assertEquals(1L, operate(StringOperation.regexCompare(BIN, "[0-9]+")).getLong(BIN)); + put("HELLO"); + assertEquals(0L, operate(StringOperation.regexCompare(BIN, "[0-9]+")).getLong(BIN)); + } + + @Test + public void regexCompareHonorsCaseInsensitiveFlag() { + put("HELLO"); + assertEquals(1L, operate(StringOperation.regexCompare( + BIN, "hello", StringRegexFlags.CASE_INSENSITIVE)).getLong(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)); + } + + @Test + public void b64EncodeOnBlobBinReturnsEncodedString() { + client.delete(null, KEY); + client.put(null, KEY, new Bin(BIN, "hello".getBytes())); + Record r = operate(StringOperation.b64Encode(BIN)); + assertEquals("aGVsbG8=", r.getString(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 0/1. + assertEquals(15L, r.getLong("text")); + assertEquals(12345L, r.getLong("number_str")); + assertEquals(1L, r.getLong("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); + } + } +} diff --git a/test/src/com/aerospike/test/sync/basic/TestStringMasking.java b/test/src/com/aerospike/test/sync/basic/TestStringMasking.java new file mode 100644 index 000000000..4948c9fc0 --- /dev/null +++ b/test/src/com/aerospike/test/sync/basic/TestStringMasking.java @@ -0,0 +1,407 @@ +/* + * 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.assertEquals; +import static org.junit.Assert.assertNotEquals; +import static org.junit.Assert.fail; + +import java.util.Arrays; +import java.util.List; + +import org.junit.AfterClass; +import org.junit.Assume; +import org.junit.Before; +import org.junit.BeforeClass; +import org.junit.Test; + +import com.aerospike.client.AerospikeClient; +import com.aerospike.client.AerospikeException; +import com.aerospike.client.Bin; +import com.aerospike.client.Host; +import com.aerospike.client.IAerospikeClient; +import com.aerospike.client.Info; +import com.aerospike.client.Key; +import com.aerospike.client.Record; +import com.aerospike.client.ResultCode; +import com.aerospike.client.admin.Role; +import com.aerospike.client.cluster.Node; +import com.aerospike.client.operation.StringOperation; +import com.aerospike.client.operation.StringPolicy; +import com.aerospike.client.policy.AdminPolicy; +import com.aerospike.client.policy.ClientPolicy; +import com.aerospike.test.sync.TestSync; + +/** + * Integration tests for string operations applied to bins protected by a + * server-side masking rule. + * + *

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")); + assertEquals(0L, r.getLong(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")); + assertEquals(0L, sw.getLong(MASKED_BIN)); + assertEquals(0L, ew.getLong(MASKED_BIN)); + } + + @Test + public void unprivilegedRegexCompareOnMaskedBinDoesNotMatchReal() { + Record r = unprivClient.operate(null, KEY, StringOperation.regexCompare(MASKED_BIN, "hello.*")); + assertEquals(0L, r.getLong(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 nodes = Arrays.asList(client.getNodes()); + for (Node node : nodes) { + Info.request(null, node, cmd); + } + // Give the rule time to propagate before exercising it. + try { Thread.sleep(500); } catch (InterruptedException ignored) {} + } + +} From 968e16167dda46e95e1d2cbefb8db0e6faec9bd3 Mon Sep 17 00:00:00 2001 From: Mirza Karacic Date: Wed, 6 May 2026 15:11:35 -0700 Subject: [PATCH 2/9] Updated protocol changes --- .../aerospike/client/command/OperateArgs.java | 2 + .../com/aerospike/client/exp/StringExp.java | 11 +-- .../client/operation/StringOperation.java | 95 +++++++++---------- .../test/sync/basic/TestOperateString.java | 10 +- 4 files changed, 47 insertions(+), 71 deletions(-) diff --git a/client/src/com/aerospike/client/command/OperateArgs.java b/client/src/com/aerospike/client/command/OperateArgs.java index 3a15a5150..64f9a1adc 100644 --- a/client/src/com/aerospike/client/command/OperateArgs.java +++ b/client/src/com/aerospike/client/command/OperateArgs.java @@ -54,6 +54,8 @@ public OperateArgs( // Fall through to read. case CDT_READ: case READ: + case STRING_READ: + case TO_STRING: rattr |= Command.INFO1_READ; // Read all bins if no bin is specified. diff --git a/client/src/com/aerospike/client/exp/StringExp.java b/client/src/com/aerospike/client/exp/StringExp.java index 0b23a670e..5c13d5ab2 100644 --- a/client/src/com/aerospike/client/exp/StringExp.java +++ b/client/src/com/aerospike/client/exp/StringExp.java @@ -52,8 +52,7 @@ public final class StringExp { private static final int TO_BLOB = 13; private static final int SPLIT = 14; private static final int B64_DECODE = 15; - private static final int B64_ENCODE = 16; - private static final int REGEX_COMPARE = 17; + private static final int REGEX_COMPARE = 16; // Modify ops private static final int INSERT = 50; @@ -241,14 +240,6 @@ public static Exp b64Decode(Exp src) { return addRead(src, bytes, Exp.Type.BLOB); } - /** - * Create expression that base64-encodes a blob source as a string. - */ - public static Exp b64Encode(Exp src) { - byte[] bytes = Pack.pack(B64_ENCODE); - return addRead(src, bytes, Exp.Type.STRING); - } - /** * Create expression that returns 1 if {@code pattern} (ICU regex) matches the source, 0 otherwise. */ diff --git a/client/src/com/aerospike/client/operation/StringOperation.java b/client/src/com/aerospike/client/operation/StringOperation.java index 56336e91c..893c1a1fa 100644 --- a/client/src/com/aerospike/client/operation/StringOperation.java +++ b/client/src/com/aerospike/client/operation/StringOperation.java @@ -21,6 +21,7 @@ import com.aerospike.client.Operation; import com.aerospike.client.Value; +import com.aerospike.client.command.ParticleType; import com.aerospike.client.util.Pack; import com.aerospike.client.util.Packer; @@ -52,8 +53,7 @@ public final class StringOperation { private static final int TO_BLOB = 13; private static final int SPLIT = 14; private static final int B64_DECODE = 15; - private static final int B64_ENCODE = 16; - private static final int REGEX_COMPARE = 17; + private static final int REGEX_COMPARE = 16; // Modify ops private static final int INSERT = 50; @@ -84,7 +84,7 @@ public final class StringOperation { */ public static Operation strlen(String binName) { byte[] bytes = Pack.pack(STRLEN); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -93,7 +93,7 @@ public static Operation strlen(String binName) { */ public static Operation substr(String binName, int start) { byte[] bytes = Pack.pack(SUBSTR, start); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -102,7 +102,7 @@ public static Operation substr(String binName, int start) { */ public static Operation substr(String binName, int start, int length) { byte[] bytes = Pack.pack(SUBSTR, start, length); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -111,7 +111,7 @@ public static Operation substr(String binName, int start, int length) { */ public static Operation charAt(String binName, int index) { byte[] bytes = Pack.pack(CHAR_AT, index); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -120,7 +120,7 @@ public static Operation charAt(String binName, int index) { */ public static Operation find(String binName, String needle) { byte[] bytes = Pack.pack(FIND, Value.get(needle)); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -129,7 +129,7 @@ public static Operation find(String binName, String needle) { */ public static Operation find(String binName, String needle, int occurrence) { byte[] bytes = packCmdValueInt(FIND, Value.get(needle), occurrence); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -138,7 +138,7 @@ public static Operation find(String binName, String needle, int occurrence) { */ public static Operation contains(String binName, String needle) { byte[] bytes = Pack.pack(CONTAINS, Value.get(needle)); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -147,7 +147,7 @@ public static Operation contains(String binName, String needle) { */ public static Operation startsWith(String binName, String prefix) { byte[] bytes = Pack.pack(STARTS_WITH, Value.get(prefix)); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -156,7 +156,7 @@ public static Operation startsWith(String binName, String prefix) { */ public static Operation endsWith(String binName, String suffix) { byte[] bytes = Pack.pack(ENDS_WITH, Value.get(suffix)); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -165,7 +165,7 @@ public static Operation endsWith(String binName, String suffix) { */ public static Operation toInteger(String binName) { byte[] bytes = Pack.pack(TO_INTEGER); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -174,7 +174,7 @@ public static Operation toInteger(String binName) { */ public static Operation toDouble(String binName) { byte[] bytes = Pack.pack(TO_DOUBLE); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -183,7 +183,7 @@ public static Operation toDouble(String binName) { */ public static Operation byteLength(String binName) { byte[] bytes = Pack.pack(BYTE_LENGTH); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -192,7 +192,7 @@ public static Operation byteLength(String binName) { */ public static Operation isNumeric(String binName) { byte[] bytes = Pack.pack(IS_NUMERIC); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -201,7 +201,7 @@ public static Operation isNumeric(String binName) { */ public static Operation isNumeric(String binName, int numericType) { byte[] bytes = Pack.pack(IS_NUMERIC, numericType); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -210,7 +210,7 @@ public static Operation isNumeric(String binName, int numericType) { */ public static Operation isUpper(String binName) { byte[] bytes = Pack.pack(IS_UPPER); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -219,7 +219,7 @@ public static Operation isUpper(String binName) { */ public static Operation isLower(String binName) { byte[] bytes = Pack.pack(IS_LOWER); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -228,7 +228,7 @@ public static Operation isLower(String binName) { */ public static Operation toBlob(String binName) { byte[] bytes = Pack.pack(TO_BLOB); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -237,7 +237,7 @@ public static Operation toBlob(String binName) { */ public static Operation split(String binName) { byte[] bytes = Pack.pack(SPLIT); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -246,7 +246,7 @@ public static Operation split(String binName) { */ public static Operation split(String binName, String separator) { byte[] bytes = Pack.pack(SPLIT, Value.get(separator)); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -255,16 +255,7 @@ public static Operation split(String binName, String separator) { */ public static Operation b64Decode(String binName) { byte[] bytes = Pack.pack(B64_DECODE); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); - } - - /** - * Create string {@code b64Encode} operation. Bin must be a blob; server returns the - * base64-encoded string. Returns AEROSPIKE_ERR_INCOMPATIBLE_TYPE if the bin is a string. - */ - public static Operation b64Encode(String binName) { - byte[] bytes = Pack.pack(B64_ENCODE); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -273,7 +264,7 @@ public static Operation b64Encode(String binName) { */ public static Operation regexCompare(String binName, String pattern) { byte[] bytes = Pack.pack(REGEX_COMPARE, Value.get(pattern)); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -281,7 +272,7 @@ public static Operation regexCompare(String binName, String pattern) { */ public static Operation regexCompare(String binName, String pattern, int regexFlags) { byte[] bytes = packCmdValueInt(REGEX_COMPARE, Value.get(pattern), regexFlags); - return new Operation(Operation.Type.STRING_READ, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } //----------------------------------------------------------------- @@ -294,7 +285,7 @@ public static Operation regexCompare(String binName, String pattern, int regexFl */ public static Operation insert(StringPolicy policy, String binName, int index, String value) { byte[] bytes = Pack.pack(INSERT, index, Value.get(value), policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -303,7 +294,7 @@ public static Operation insert(StringPolicy policy, String binName, int index, S */ public static Operation overwrite(StringPolicy policy, String binName, int index, String value) { byte[] bytes = Pack.pack(OVERWRITE, index, Value.get(value), policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -313,7 +304,7 @@ public static Operation concat(StringPolicy policy, String binName, String value List list = new ArrayList(1); list.add(Value.get(value)); byte[] bytes = Pack.pack(CONCAT, list, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -323,7 +314,7 @@ public static Operation concat(StringPolicy policy, String binName, String value public static Operation concat(StringPolicy policy, String binName, List values) { List list = toValueList(values); byte[] bytes = Pack.pack(CONCAT, list, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -332,7 +323,7 @@ public static Operation concat(StringPolicy policy, String binName, List */ public static Operation snip(StringPolicy policy, String binName, int start) { byte[] bytes = Pack.pack(SNIP, start, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -341,7 +332,7 @@ public static Operation snip(StringPolicy policy, String binName, int start) { */ public static Operation snip(StringPolicy policy, String binName, int start, int end) { byte[] bytes = Pack.pack(SNIP, start, end, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -351,7 +342,7 @@ public static Operation snip(StringPolicy policy, String binName, int start, int public static Operation replace(StringPolicy policy, String binName, String needle, String replacement) { List list = pair(needle, replacement); byte[] bytes = Pack.pack(REPLACE, list, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -361,7 +352,7 @@ public static Operation replace(StringPolicy policy, String binName, String need public static Operation replaceAll(StringPolicy policy, String binName, String needle, String replacement) { List list = pair(needle, replacement); byte[] bytes = Pack.pack(REPLACE_ALL, list, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -369,7 +360,7 @@ public static Operation replaceAll(StringPolicy policy, String binName, String n */ public static Operation upper(StringPolicy policy, String binName) { byte[] bytes = Pack.pack(UPPER, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -377,7 +368,7 @@ public static Operation upper(StringPolicy policy, String binName) { */ public static Operation lower(StringPolicy policy, String binName) { byte[] bytes = Pack.pack(LOWER, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -386,7 +377,7 @@ public static Operation lower(StringPolicy policy, String binName) { */ public static Operation caseFold(StringPolicy policy, String binName) { byte[] bytes = Pack.pack(CASE_FOLD, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -395,7 +386,7 @@ public static Operation caseFold(StringPolicy policy, String binName) { */ public static Operation normalizeNFC(StringPolicy policy, String binName) { byte[] bytes = Pack.pack(NORMALIZE_NFC, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -404,7 +395,7 @@ public static Operation normalizeNFC(StringPolicy policy, String binName) { */ public static Operation trimStart(StringPolicy policy, String binName) { byte[] bytes = Pack.pack(TRIM_START, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -413,7 +404,7 @@ public static Operation trimStart(StringPolicy policy, String binName) { */ public static Operation trimEnd(StringPolicy policy, String binName) { byte[] bytes = Pack.pack(TRIM_END, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -422,7 +413,7 @@ public static Operation trimEnd(StringPolicy policy, String binName) { */ public static Operation trim(StringPolicy policy, String binName) { byte[] bytes = Pack.pack(TRIM, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -432,7 +423,7 @@ public static Operation trim(StringPolicy policy, String binName) { */ public static Operation padStart(StringPolicy policy, String binName, int targetLength, String padString) { byte[] bytes = Pack.pack(PAD_START, targetLength, Value.get(padString), policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -442,7 +433,7 @@ public static Operation padStart(StringPolicy policy, String binName, int target */ public static Operation padEnd(StringPolicy policy, String binName, int targetLength, String padString) { byte[] bytes = Pack.pack(PAD_END, targetLength, Value.get(padString), policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -451,7 +442,7 @@ public static Operation padEnd(StringPolicy policy, String binName, int targetLe */ public static Operation repeat(StringPolicy policy, String binName, int count) { byte[] bytes = Pack.pack(REPEAT, count, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** @@ -468,7 +459,7 @@ public static Operation regexReplace( ) { List list = pair(pattern, replacement); byte[] bytes = Pack.pack(REGEX_REPLACE, list, regexFlags, policy.flags); - return new Operation(Operation.Type.STRING_MODIFY, binName, Value.get(bytes)); + return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } //----------------------------------------------------------------- diff --git a/test/src/com/aerospike/test/sync/basic/TestOperateString.java b/test/src/com/aerospike/test/sync/basic/TestOperateString.java index a29bbabed..8142ba979 100644 --- a/test/src/com/aerospike/test/sync/basic/TestOperateString.java +++ b/test/src/com/aerospike/test/sync/basic/TestOperateString.java @@ -55,7 +55,7 @@ public class TestOperateString extends TestSync { public static void serverVersionCheck() { Assume.assumeTrue( "Skipping: string operations require server version 8.1.3 or later", - args.serverVersion.isGreaterOrEqual(8, 1, 3, 0)); + args.serverVersion.isGreaterOrEqual(8, 1, 2, 0)); } //----------------------------------------------------------------- @@ -251,14 +251,6 @@ public void b64DecodeReturnsOriginalBlob() { assertArrayEquals("hello".getBytes(), (byte[])r.getValue(BIN)); } - @Test - public void b64EncodeOnBlobBinReturnsEncodedString() { - client.delete(null, KEY); - client.put(null, KEY, new Bin(BIN, "hello".getBytes())); - Record r = operate(StringOperation.b64Encode(BIN)); - assertEquals("aGVsbG8=", r.getString(BIN)); - } - //================================================================= // Modify operations //================================================================= From ac6e36eb1baad8c0587e93497839b40c796e6428 Mon Sep 17 00:00:00 2001 From: Mirza Karacic Date: Wed, 6 May 2026 16:21:18 -0700 Subject: [PATCH 3/9] Updated api's to fix failing tests --- .../client/operation/StringOperation.java | 29 +++++++------- .../test/sync/basic/TestOperateString.java | 39 ++++++++++--------- .../test/sync/basic/TestStringMasking.java | 11 +++--- 3 files changed, 41 insertions(+), 38 deletions(-) diff --git a/client/src/com/aerospike/client/operation/StringOperation.java b/client/src/com/aerospike/client/operation/StringOperation.java index 893c1a1fa..fa0f7d6c6 100644 --- a/client/src/com/aerospike/client/operation/StringOperation.java +++ b/client/src/com/aerospike/client/operation/StringOperation.java @@ -133,8 +133,8 @@ public static Operation find(String binName, String needle, int occurrence) { } /** - * Create string {@code contains} operation. Server returns 1 if the bin contains - * {@code needle} as a substring, 0 otherwise. + * Create string {@code contains} operation. Server returns true if the bin contains + * {@code needle} as a substring, false otherwise. */ public static Operation contains(String binName, String needle) { byte[] bytes = Pack.pack(CONTAINS, Value.get(needle)); @@ -142,8 +142,8 @@ public static Operation contains(String binName, String needle) { } /** - * Create string {@code startsWith} operation. Server returns 1 if the bin begins with - * {@code prefix}, 0 otherwise. + * Create string {@code startsWith} operation. Server returns true if the bin begins with + * {@code prefix}, false otherwise. */ public static Operation startsWith(String binName, String prefix) { byte[] bytes = Pack.pack(STARTS_WITH, Value.get(prefix)); @@ -151,8 +151,8 @@ public static Operation startsWith(String binName, String prefix) { } /** - * Create string {@code endsWith} operation. Server returns 1 if the bin ends with - * {@code suffix}, 0 otherwise. + * Create string {@code endsWith} operation. Server returns true if the bin ends with + * {@code suffix}, false otherwise. */ public static Operation endsWith(String binName, String suffix) { byte[] bytes = Pack.pack(ENDS_WITH, Value.get(suffix)); @@ -187,8 +187,8 @@ public static Operation byteLength(String binName) { } /** - * Create string {@code isNumeric} operation. Server returns 1 if the bin contains a valid - * integer or float, 0 otherwise. + * Create string {@code isNumeric} operation. Server returns true if the bin contains a valid + * integer or float, false otherwise. */ public static Operation isNumeric(String binName) { byte[] bytes = Pack.pack(IS_NUMERIC); @@ -205,8 +205,8 @@ public static Operation isNumeric(String binName, int numericType) { } /** - * Create string {@code isUpper} operation. Server returns 1 if every cased character - * in the bin is uppercase, 0 otherwise. + * Create string {@code isUpper} operation. Server returns true if every cased character + * in the bin is uppercase, false otherwise. */ public static Operation isUpper(String binName) { byte[] bytes = Pack.pack(IS_UPPER); @@ -214,8 +214,8 @@ public static Operation isUpper(String binName) { } /** - * Create string {@code isLower} operation. Server returns 1 if every cased character - * in the bin is lowercase, 0 otherwise. + * Create string {@code isLower} operation. Server returns true if every cased character + * in the bin is lowercase, false otherwise. */ public static Operation isLower(String binName) { byte[] bytes = Pack.pack(IS_LOWER); @@ -260,7 +260,7 @@ public static Operation b64Decode(String binName) { /** * Create string {@code regexCompare} operation. Server matches {@code pattern} (ICU - * regex syntax) against the bin and returns 1 on match, 0 otherwise. + * regex syntax) against the bin and returns true on match, false otherwise. */ public static Operation regexCompare(String binName, String pattern) { byte[] bytes = Pack.pack(REGEX_COMPARE, Value.get(pattern)); @@ -458,7 +458,8 @@ public static Operation regexReplace( int regexFlags ) { List list = pair(pattern, replacement); - byte[] bytes = Pack.pack(REGEX_REPLACE, list, regexFlags, policy.flags); + // Server's regex_replace op table accepts only [list, regexFlags]; no slot for policy flags. + byte[] bytes = Pack.pack(REGEX_REPLACE, list, regexFlags); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } diff --git a/test/src/com/aerospike/test/sync/basic/TestOperateString.java b/test/src/com/aerospike/test/sync/basic/TestOperateString.java index 8142ba979..d1eeb68dd 100644 --- a/test/src/com/aerospike/test/sync/basic/TestOperateString.java +++ b/test/src/com/aerospike/test/sync/basic/TestOperateString.java @@ -18,6 +18,7 @@ import static org.junit.Assert.assertArrayEquals; import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertFalse; import static org.junit.Assert.assertTrue; import java.util.Arrays; @@ -148,50 +149,50 @@ public void findReturnsMinusOneWhenAbsent() { } @Test - public void containsReturnsBooleanIntegers() { + public void containsReturnsBoolean() { put("hello world"); Record present = operate(StringOperation.contains(BIN, "hello")); Record absent = operate(StringOperation.contains(BIN, "xyz")); - assertEquals(1L, present.getLong(BIN)); - assertEquals(0L, absent.getLong(BIN)); + assertTrue(present.getBoolean(BIN)); + assertFalse(absent.getBoolean(BIN)); } @Test public void startsWithMatchesPrefix() { put("Hello123World"); - assertEquals(1L, operate(StringOperation.startsWith(BIN, "Hello")).getLong(BIN)); - assertEquals(0L, operate(StringOperation.startsWith(BIN, "World")).getLong(BIN)); + assertTrue(operate(StringOperation.startsWith(BIN, "Hello")).getBoolean(BIN)); + assertFalse(operate(StringOperation.startsWith(BIN, "World")).getBoolean(BIN)); } @Test public void endsWithMatchesSuffix() { put("Hello123World"); - assertEquals(1L, operate(StringOperation.endsWith(BIN, "World")).getLong(BIN)); - assertEquals(0L, operate(StringOperation.endsWith(BIN, "Hello")).getLong(BIN)); + assertTrue(operate(StringOperation.endsWith(BIN, "World")).getBoolean(BIN)); + assertFalse(operate(StringOperation.endsWith(BIN, "Hello")).getBoolean(BIN)); } @Test public void isUpperOnlyTrueForUppercase() { put("HELLO"); - assertEquals(1L, operate(StringOperation.isUpper(BIN)).getLong(BIN)); + assertTrue(operate(StringOperation.isUpper(BIN)).getBoolean(BIN)); put("hello"); - assertEquals(0L, operate(StringOperation.isUpper(BIN)).getLong(BIN)); + assertFalse(operate(StringOperation.isUpper(BIN)).getBoolean(BIN)); } @Test public void isLowerOnlyTrueForLowercase() { put("hello"); - assertEquals(1L, operate(StringOperation.isLower(BIN)).getLong(BIN)); + assertTrue(operate(StringOperation.isLower(BIN)).getBoolean(BIN)); put("HELLO"); - assertEquals(0L, operate(StringOperation.isLower(BIN)).getLong(BIN)); + assertFalse(operate(StringOperation.isLower(BIN)).getBoolean(BIN)); } @Test public void isNumericMatchesIntegerStrings() { put("12345"); - assertEquals(1L, operate(StringOperation.isNumeric(BIN)).getLong(BIN)); + assertTrue(operate(StringOperation.isNumeric(BIN)).getBoolean(BIN)); put("Hello123World"); - assertEquals(0L, operate(StringOperation.isNumeric(BIN)).getLong(BIN)); + assertFalse(operate(StringOperation.isNumeric(BIN)).getBoolean(BIN)); } @Test @@ -225,16 +226,16 @@ public void splitWithoutMatchReturnsSingletonList() { @Test public void regexCompareDistinguishesMatchVsMiss() { put("Hello123World"); - assertEquals(1L, operate(StringOperation.regexCompare(BIN, "[0-9]+")).getLong(BIN)); + assertTrue(operate(StringOperation.regexCompare(BIN, "[0-9]+")).getBoolean(BIN)); put("HELLO"); - assertEquals(0L, operate(StringOperation.regexCompare(BIN, "[0-9]+")).getLong(BIN)); + assertFalse(operate(StringOperation.regexCompare(BIN, "[0-9]+")).getBoolean(BIN)); } @Test public void regexCompareHonorsCaseInsensitiveFlag() { put("HELLO"); - assertEquals(1L, operate(StringOperation.regexCompare( - BIN, "hello", StringRegexFlags.CASE_INSENSITIVE)).getLong(BIN)); + assertTrue(operate(StringOperation.regexCompare( + BIN, "hello", StringRegexFlags.CASE_INSENSITIVE)).getBoolean(BIN)); } @Test @@ -516,10 +517,10 @@ public void readsAcrossMultipleBinsInOneOperate() { StringOperation.toInteger("number_str"), StringOperation.isUpper("upper_str")); - // strlen and toInteger return INT; isUpper returns 0/1. + // strlen and toInteger return INT; isUpper returns BOOL. assertEquals(15L, r.getLong("text")); assertEquals(12345L, r.getLong("number_str")); - assertEquals(1L, r.getLong("upper_str")); + assertTrue(r.getBoolean("upper_str")); } @Test diff --git a/test/src/com/aerospike/test/sync/basic/TestStringMasking.java b/test/src/com/aerospike/test/sync/basic/TestStringMasking.java index 4948c9fc0..8db39c740 100644 --- a/test/src/com/aerospike/test/sync/basic/TestStringMasking.java +++ b/test/src/com/aerospike/test/sync/basic/TestStringMasking.java @@ -17,6 +17,7 @@ package com.aerospike.test.sync.basic; import static org.junit.Assert.assertEquals; +import static org.junit.Assert.assertFalse; import static org.junit.Assert.assertNotEquals; import static org.junit.Assert.fail; @@ -85,7 +86,7 @@ public class TestStringMasking extends TestSync { @BeforeClass public static void setupUsersAndRule() { Assume.assumeTrue("Skipping: server version < 8.1.3 (string ops + masking)", - args.serverVersion.isGreaterOrEqual(8, 1, 3, 0)); + args.serverVersion.isGreaterOrEqual(8, 1, 2, 0)); Assume.assumeTrue("Skipping: admin credentials not provided", args.user != null && !args.user.isEmpty() && args.password != null && !args.password.isEmpty()); @@ -183,21 +184,21 @@ public void unprivilegedFindOnMaskedBinDoesNotLocateRealContent() { @Test public void unprivilegedContainsOnMaskedBinIsFalse() { Record r = unprivClient.operate(null, KEY, StringOperation.contains(MASKED_BIN, "hello")); - assertEquals(0L, r.getLong(MASKED_BIN)); + 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")); - assertEquals(0L, sw.getLong(MASKED_BIN)); - assertEquals(0L, ew.getLong(MASKED_BIN)); + 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.*")); - assertEquals(0L, r.getLong(MASKED_BIN)); + assertFalse(r.getBoolean(MASKED_BIN)); } @Test From 95684583b7ee46c16f1173f3961b81553f083768 Mon Sep 17 00:00:00 2001 From: Mirza Karacic Date: Wed, 6 May 2026 16:48:38 -0700 Subject: [PATCH 4/9] Updated StringOperation --- .../client/operation/StringOperation.java | 176 +++++++++--------- 1 file changed, 90 insertions(+), 86 deletions(-) diff --git a/client/src/com/aerospike/client/operation/StringOperation.java b/client/src/com/aerospike/client/operation/StringOperation.java index fa0f7d6c6..6a74d681c 100644 --- a/client/src/com/aerospike/client/operation/StringOperation.java +++ b/client/src/com/aerospike/client/operation/StringOperation.java @@ -21,6 +21,7 @@ import com.aerospike.client.Operation; import com.aerospike.client.Value; +import com.aerospike.client.cdt.CTX; import com.aerospike.client.command.ParticleType; import com.aerospike.client.util.Pack; import com.aerospike.client.util.Packer; @@ -32,8 +33,9 @@ * count from the end of the string ({@code -1} = last character). Out-of-bounds * indexes are clamped to the valid range; no error is returned. *

- * String operations require server version 8.1.3 or later. Operations on string - * items nested in lists/maps are not currently supported by the server. + * 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. */ public final class StringOperation { // Read ops @@ -82,8 +84,8 @@ public final class StringOperation { * Create string {@code strlen} operation. * Server returns the number of unicode codepoints in the string bin (int64). */ - public static Operation strlen(String binName) { - byte[] bytes = Pack.pack(STRLEN); + public static Operation strlen(String binName, CTX... ctx) { + byte[] bytes = Pack.pack(STRLEN, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -91,8 +93,8 @@ public static Operation strlen(String binName) { * Create string {@code substr} operation that reads from {@code start} to the end of the string. * Negative indexes count from the end. */ - public static Operation substr(String binName, int start) { - byte[] bytes = Pack.pack(SUBSTR, start); + public static Operation substr(String binName, int start, CTX... ctx) { + byte[] bytes = Pack.pack(SUBSTR, start, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -100,8 +102,8 @@ public static Operation substr(String binName, int start) { * Create string {@code substr} operation that reads {@code length} codepoints starting at {@code start}. * Negative indexes count from the end of the string. */ - public static Operation substr(String binName, int start, int length) { - byte[] bytes = Pack.pack(SUBSTR, start, length); + public static Operation substr(String binName, int start, int length, CTX... ctx) { + byte[] bytes = Pack.pack(SUBSTR, start, length, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -109,8 +111,8 @@ public static Operation substr(String binName, int start, int length) { * Create string {@code charAt} operation. Server returns the character at {@code index} as a string. * Negative indexes count from the end of the string. */ - public static Operation charAt(String binName, int index) { - byte[] bytes = Pack.pack(CHAR_AT, index); + public static Operation charAt(String binName, int index, CTX... ctx) { + byte[] bytes = Pack.pack(CHAR_AT, index, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -118,8 +120,8 @@ public static Operation charAt(String binName, int index) { * Create string {@code find} operation. Server returns the codepoint index of the first * occurrence of {@code needle}, or -1 if not found. */ - public static Operation find(String binName, String needle) { - byte[] bytes = Pack.pack(FIND, Value.get(needle)); + public static Operation find(String binName, String needle, CTX... ctx) { + byte[] bytes = Pack.pack(FIND, Value.get(needle), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -127,8 +129,8 @@ public static Operation find(String binName, String needle) { * Create string {@code find} operation. Server returns the codepoint index of the * {@code occurrence}-th match of {@code needle} (1 = first match), or -1 if not found. */ - public static Operation find(String binName, String needle, int occurrence) { - byte[] bytes = packCmdValueInt(FIND, Value.get(needle), occurrence); + public static Operation find(String binName, String needle, int occurrence, CTX... ctx) { + byte[] bytes = packCmdValueInt(FIND, Value.get(needle), occurrence, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -136,8 +138,8 @@ public static Operation find(String binName, String needle, int occurrence) { * Create string {@code contains} operation. Server returns true if the bin contains * {@code needle} as a substring, false otherwise. */ - public static Operation contains(String binName, String needle) { - byte[] bytes = Pack.pack(CONTAINS, Value.get(needle)); + public static Operation contains(String binName, String needle, CTX... ctx) { + byte[] bytes = Pack.pack(CONTAINS, Value.get(needle), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -145,8 +147,8 @@ public static Operation contains(String binName, String needle) { * Create string {@code startsWith} operation. Server returns true if the bin begins with * {@code prefix}, false otherwise. */ - public static Operation startsWith(String binName, String prefix) { - byte[] bytes = Pack.pack(STARTS_WITH, Value.get(prefix)); + public static Operation startsWith(String binName, String prefix, CTX... ctx) { + byte[] bytes = Pack.pack(STARTS_WITH, Value.get(prefix), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -154,8 +156,8 @@ public static Operation startsWith(String binName, String prefix) { * Create string {@code endsWith} operation. Server returns true if the bin ends with * {@code suffix}, false otherwise. */ - public static Operation endsWith(String binName, String suffix) { - byte[] bytes = Pack.pack(ENDS_WITH, Value.get(suffix)); + public static Operation endsWith(String binName, String suffix, CTX... ctx) { + byte[] bytes = Pack.pack(ENDS_WITH, Value.get(suffix), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -163,8 +165,8 @@ public static Operation endsWith(String binName, String suffix) { * Create string {@code toInteger} operation. Server parses the string as an int64. * Returns AEROSPIKE_ERR_PARAMETER if the bin cannot be parsed as an integer. */ - public static Operation toInteger(String binName) { - byte[] bytes = Pack.pack(TO_INTEGER); + public static Operation toInteger(String binName, CTX... ctx) { + byte[] bytes = Pack.pack(TO_INTEGER, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -172,8 +174,8 @@ public static Operation toInteger(String binName) { * Create string {@code toDouble} operation. Server parses the string as a 64-bit float. * Returns AEROSPIKE_ERR_PARAMETER if the bin cannot be parsed as a double. */ - public static Operation toDouble(String binName) { - byte[] bytes = Pack.pack(TO_DOUBLE); + public static Operation toDouble(String binName, CTX... ctx) { + byte[] bytes = Pack.pack(TO_DOUBLE, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -181,8 +183,8 @@ public static Operation toDouble(String binName) { * Create string {@code byteLength} operation. Server returns the UTF-8 byte length * of the string (int64). */ - public static Operation byteLength(String binName) { - byte[] bytes = Pack.pack(BYTE_LENGTH); + public static Operation byteLength(String binName, CTX... ctx) { + byte[] bytes = Pack.pack(BYTE_LENGTH, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -190,8 +192,8 @@ public static Operation byteLength(String binName) { * Create string {@code isNumeric} operation. Server returns true if the bin contains a valid * integer or float, false otherwise. */ - public static Operation isNumeric(String binName) { - byte[] bytes = Pack.pack(IS_NUMERIC); + public static Operation isNumeric(String binName, CTX... ctx) { + byte[] bytes = Pack.pack(IS_NUMERIC, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -199,8 +201,8 @@ public static Operation isNumeric(String binName) { * Create string {@code isNumeric} operation that filters by {@code numericType} * (see {@link StringNumericType}). */ - public static Operation isNumeric(String binName, int numericType) { - byte[] bytes = Pack.pack(IS_NUMERIC, numericType); + public static Operation isNumeric(String binName, int numericType, CTX... ctx) { + byte[] bytes = Pack.pack(IS_NUMERIC, numericType, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -208,8 +210,8 @@ public static Operation isNumeric(String binName, int numericType) { * Create string {@code isUpper} operation. Server returns true if every cased character * in the bin is uppercase, false otherwise. */ - public static Operation isUpper(String binName) { - byte[] bytes = Pack.pack(IS_UPPER); + public static Operation isUpper(String binName, CTX... ctx) { + byte[] bytes = Pack.pack(IS_UPPER, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -217,8 +219,8 @@ public static Operation isUpper(String binName) { * Create string {@code isLower} operation. Server returns true if every cased character * in the bin is lowercase, false otherwise. */ - public static Operation isLower(String binName) { - byte[] bytes = Pack.pack(IS_LOWER); + public static Operation isLower(String binName, CTX... ctx) { + byte[] bytes = Pack.pack(IS_LOWER, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -226,8 +228,8 @@ public static Operation isLower(String binName) { * Create string {@code toBlob} operation. Server returns the UTF-8 bytes of the string * as a blob. */ - public static Operation toBlob(String binName) { - byte[] bytes = Pack.pack(TO_BLOB); + public static Operation toBlob(String binName, CTX... ctx) { + byte[] bytes = Pack.pack(TO_BLOB, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -235,8 +237,8 @@ public static Operation toBlob(String binName) { * Create string {@code split} operation that splits by Unicode codepoint * (each codepoint becomes its own list element). */ - public static Operation split(String binName) { - byte[] bytes = Pack.pack(SPLIT); + public static Operation split(String binName, CTX... ctx) { + byte[] bytes = Pack.pack(SPLIT, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -244,8 +246,8 @@ public static Operation split(String binName) { * Create string {@code split} operation that splits by {@code separator}. * Server returns a list of strings. */ - public static Operation split(String binName, String separator) { - byte[] bytes = Pack.pack(SPLIT, Value.get(separator)); + public static Operation split(String binName, String separator, CTX... ctx) { + byte[] bytes = Pack.pack(SPLIT, Value.get(separator), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -253,8 +255,8 @@ public static Operation split(String binName, String separator) { * Create string {@code b64Decode} operation. Server base64-decodes the string and * returns a blob. */ - public static Operation b64Decode(String binName) { - byte[] bytes = Pack.pack(B64_DECODE); + public static Operation b64Decode(String binName, CTX... ctx) { + byte[] bytes = Pack.pack(B64_DECODE, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -262,16 +264,16 @@ public static Operation b64Decode(String binName) { * Create string {@code regexCompare} operation. Server matches {@code pattern} (ICU * regex syntax) against the bin and returns true on match, false otherwise. */ - public static Operation regexCompare(String binName, String pattern) { - byte[] bytes = Pack.pack(REGEX_COMPARE, Value.get(pattern)); + public static Operation regexCompare(String binName, String pattern, CTX... ctx) { + byte[] bytes = Pack.pack(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 with {@link StringRegexFlags}. */ - public static Operation regexCompare(String binName, String pattern, int regexFlags) { - byte[] bytes = packCmdValueInt(REGEX_COMPARE, Value.get(pattern), regexFlags); + public static Operation regexCompare(String binName, String pattern, int regexFlags, CTX... ctx) { + byte[] bytes = packCmdValueInt(REGEX_COMPARE, Value.get(pattern), regexFlags, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -283,8 +285,8 @@ public static Operation regexCompare(String binName, String pattern, int regexFl * Create string {@code insert} operation that inserts {@code value} at codepoint * {@code index}. Negative indexes count from the end of the string. */ - public static Operation insert(StringPolicy policy, String binName, int index, String value) { - byte[] bytes = Pack.pack(INSERT, index, Value.get(value), policy.flags); + public static Operation insert(StringPolicy policy, String binName, int index, String value, CTX... ctx) { + byte[] bytes = Pack.pack(INSERT, index, Value.get(value), policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -292,18 +294,18 @@ public static Operation insert(StringPolicy policy, String binName, int index, S * Create string {@code overwrite} operation that overwrites characters starting at * codepoint {@code index} with {@code value}. */ - public static Operation overwrite(StringPolicy policy, String binName, int index, String value) { - byte[] bytes = Pack.pack(OVERWRITE, index, Value.get(value), policy.flags); + public static Operation overwrite(StringPolicy policy, String binName, int index, String value, CTX... ctx) { + byte[] bytes = Pack.pack(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. */ - public static Operation concat(StringPolicy policy, String binName, String value) { + public static Operation concat(StringPolicy policy, String binName, String value, CTX... ctx) { List list = new ArrayList(1); list.add(Value.get(value)); - byte[] bytes = Pack.pack(CONCAT, list, policy.flags); + byte[] bytes = Pack.pack(CONCAT, list, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -311,9 +313,9 @@ public static Operation concat(StringPolicy policy, String binName, String value * Create string {@code concat} operation that appends every element of {@code values} * to the bin in order. */ - public static Operation concat(StringPolicy policy, String binName, List values) { + public static Operation concat(StringPolicy policy, String binName, List values, CTX... ctx) { List list = toValueList(values); - byte[] bytes = Pack.pack(CONCAT, list, policy.flags); + byte[] bytes = Pack.pack(CONCAT, list, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -321,8 +323,8 @@ public static Operation concat(StringPolicy policy, String binName, List * Create string {@code snip} operation that removes characters starting at codepoint * {@code start} through the end of the string. */ - public static Operation snip(StringPolicy policy, String binName, int start) { - byte[] bytes = Pack.pack(SNIP, start, policy.flags); + public static Operation snip(StringPolicy policy, String binName, int start, CTX... ctx) { + byte[] bytes = Pack.pack(SNIP, start, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -330,8 +332,8 @@ public static Operation snip(StringPolicy policy, String binName, int start) { * Create string {@code snip} operation that removes characters from codepoint * {@code start} (inclusive) to {@code end} (exclusive). */ - public static Operation snip(StringPolicy policy, String binName, int start, int end) { - byte[] bytes = Pack.pack(SNIP, start, end, policy.flags); + public static Operation snip(StringPolicy policy, String binName, int start, int end, CTX... ctx) { + byte[] bytes = Pack.pack(SNIP, start, end, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -339,9 +341,9 @@ public static Operation snip(StringPolicy policy, String binName, int start, int * Create string {@code replace} operation that replaces the first occurrence of * {@code needle} with {@code replacement}. */ - public static Operation replace(StringPolicy policy, String binName, String needle, String replacement) { + public static Operation replace(StringPolicy policy, String binName, String needle, String replacement, CTX... ctx) { List list = pair(needle, replacement); - byte[] bytes = Pack.pack(REPLACE, list, policy.flags); + byte[] bytes = Pack.pack(REPLACE, list, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -349,25 +351,25 @@ public static Operation replace(StringPolicy policy, String binName, String need * Create string {@code replaceAll} operation that replaces every occurrence of * {@code needle} with {@code replacement}. */ - public static Operation replaceAll(StringPolicy policy, String binName, String needle, String replacement) { + public static Operation replaceAll(StringPolicy policy, String binName, String needle, String replacement, CTX... ctx) { List list = pair(needle, replacement); - byte[] bytes = Pack.pack(REPLACE_ALL, list, policy.flags); + byte[] bytes = Pack.pack(REPLACE_ALL, list, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } /** * Create string {@code upper} operation that uppercases the bin in place. */ - public static Operation upper(StringPolicy policy, String binName) { - byte[] bytes = Pack.pack(UPPER, policy.flags); + public static Operation upper(StringPolicy policy, String binName, CTX... ctx) { + byte[] bytes = Pack.pack(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. */ - public static Operation lower(StringPolicy policy, String binName) { - byte[] bytes = Pack.pack(LOWER, policy.flags); + public static Operation lower(StringPolicy policy, String binName, CTX... ctx) { + byte[] bytes = Pack.pack(LOWER, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -375,8 +377,8 @@ public static Operation lower(StringPolicy policy, String binName) { * Create string {@code caseFold} operation. Server applies a locale-independent case * fold (lowercase) to the bin. */ - public static Operation caseFold(StringPolicy policy, String binName) { - byte[] bytes = Pack.pack(CASE_FOLD, policy.flags); + public static Operation caseFold(StringPolicy policy, String binName, CTX... ctx) { + byte[] bytes = Pack.pack(CASE_FOLD, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -384,8 +386,8 @@ public static Operation caseFold(StringPolicy policy, String binName) { * Create string {@code normalizeNFC} operation. Server normalizes the bin to Unicode * NFC form. */ - public static Operation normalizeNFC(StringPolicy policy, String binName) { - byte[] bytes = Pack.pack(NORMALIZE_NFC, policy.flags); + public static Operation normalizeNFC(StringPolicy policy, String binName, CTX... ctx) { + byte[] bytes = Pack.pack(NORMALIZE_NFC, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -393,8 +395,8 @@ public static Operation normalizeNFC(StringPolicy policy, String binName) { * Create string {@code trimStart} operation that removes whitespace from the start * of the bin. */ - public static Operation trimStart(StringPolicy policy, String binName) { - byte[] bytes = Pack.pack(TRIM_START, policy.flags); + public static Operation trimStart(StringPolicy policy, String binName, CTX... ctx) { + byte[] bytes = Pack.pack(TRIM_START, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -402,8 +404,8 @@ public static Operation trimStart(StringPolicy policy, String binName) { * Create string {@code trimEnd} operation that removes whitespace from the end of * the bin. */ - public static Operation trimEnd(StringPolicy policy, String binName) { - byte[] bytes = Pack.pack(TRIM_END, policy.flags); + public static Operation trimEnd(StringPolicy policy, String binName, CTX... ctx) { + byte[] bytes = Pack.pack(TRIM_END, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -411,8 +413,8 @@ public static Operation trimEnd(StringPolicy policy, String binName) { * Create string {@code trim} operation that removes whitespace from both ends of * the bin. */ - public static Operation trim(StringPolicy policy, String binName) { - byte[] bytes = Pack.pack(TRIM, policy.flags); + public static Operation trim(StringPolicy policy, String binName, CTX... ctx) { + byte[] bytes = Pack.pack(TRIM, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -421,8 +423,8 @@ public static Operation trim(StringPolicy policy, String binName) { * until the bin reaches {@code targetLength} codepoints. No-op if already at or above * target length. */ - public static Operation padStart(StringPolicy policy, String binName, int targetLength, String padString) { - byte[] bytes = Pack.pack(PAD_START, targetLength, Value.get(padString), policy.flags); + public static Operation padStart(StringPolicy policy, String binName, int targetLength, String padString, CTX... ctx) { + byte[] bytes = Pack.pack(PAD_START, targetLength, Value.get(padString), policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -431,8 +433,8 @@ public static Operation padStart(StringPolicy policy, String binName, int target * until the bin reaches {@code targetLength} codepoints. No-op if already at or above * target length. */ - public static Operation padEnd(StringPolicy policy, String binName, int targetLength, String padString) { - byte[] bytes = Pack.pack(PAD_END, targetLength, Value.get(padString), policy.flags); + public static Operation padEnd(StringPolicy policy, String binName, int targetLength, String padString, CTX... ctx) { + byte[] bytes = Pack.pack(PAD_END, targetLength, Value.get(padString), policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -440,8 +442,8 @@ public static Operation padEnd(StringPolicy policy, String binName, int targetLe * Create string {@code repeat} operation that repeats the bin contents {@code count} * times. */ - public static Operation repeat(StringPolicy policy, String binName, int count) { - byte[] bytes = Pack.pack(REPEAT, count, policy.flags); + public static Operation repeat(StringPolicy policy, String binName, int count, CTX... ctx) { + byte[] bytes = Pack.pack(REPEAT, count, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -455,11 +457,12 @@ public static Operation regexReplace( String binName, String pattern, String replacement, - int regexFlags + int regexFlags, + CTX... ctx ) { List list = pair(pattern, replacement); // Server's regex_replace op table accepts only [list, regexFlags]; no slot for policy flags. - byte[] bytes = Pack.pack(REGEX_REPLACE, list, regexFlags); + byte[] bytes = Pack.pack(REGEX_REPLACE, list, regexFlags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -473,7 +476,7 @@ public static Operation regexReplace( * other bin type. *

* The wire format for this op carries no payload; the bin is referenced solely by - * the operation header. + * the operation header, so {@link CTX} navigation is not supported. */ public static Operation toString(String binName) { return new Operation(Operation.Type.TO_STRING, binName, Value.getAsNull()); @@ -498,9 +501,10 @@ private static List toValueList(List strings) { return list; } - private static byte[] packCmdValueInt(int command, Value value, int v) { + private static byte[] packCmdValueInt(int command, Value value, int v, CTX[] ctx) { Packer packer = new Packer(); for (int i = 0; i < 2; i++) { + Pack.init(packer, ctx); packer.packArrayBegin(3); packer.packInt(command); value.pack(packer); From aa2ab3f6188a02b4d6374bbc1dd72c8499531eaa Mon Sep 17 00:00:00 2001 From: Mirza Karacic Date: Thu, 7 May 2026 10:10:59 -0700 Subject: [PATCH 5/9] Updated javadocs for StringOperation and StringExp, pack clena-up --- .../com/aerospike/client/exp/StringExp.java | 595 +++++++++++++-- .../client/operation/StringOperation.java | 684 +++++++++++++++--- .../src/com/aerospike/client/util/Pack.java | 20 + 3 files changed, 1149 insertions(+), 150 deletions(-) diff --git a/client/src/com/aerospike/client/exp/StringExp.java b/client/src/com/aerospike/client/exp/StringExp.java index 5c13d5ab2..6b0dc1123 100644 --- a/client/src/com/aerospike/client/exp/StringExp.java +++ b/client/src/com/aerospike/client/exp/StringExp.java @@ -22,14 +22,45 @@ import com.aerospike.client.util.Packer; /** - * String expression generator. See {@link com.aerospike.client.exp.Exp}. + * String expression generator. Produces {@link Exp} nodes that read or transform + * string values inside an Aerospike {@link Expression}. Mirrors the operations + * exposed by {@link com.aerospike.client.operation.StringOperation}, but composes + * inside expressions instead of being sent as standalone operate ops. *

- * The string source argument in these methods is any expression that yields a - * string: a bin reference (e.g. {@link Exp#stringBin(String)}), a string literal - * ({@link Exp#val(String)}), or a nested string expression. Expressions that - * modify a string value return the modified string; the bin is not changed. + * 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 @@ -78,7 +109,22 @@ public final class StringExp { //----------------------------------------------------------------- /** - * Create expression that returns the codepoint length of the source string. + * 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); @@ -86,7 +132,18 @@ public static Exp strlen(Exp src) { } /** - * Create expression that returns the substring from {@code start} to the end of the source. + * 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); @@ -94,7 +151,18 @@ public static Exp substr(Exp start, Exp src) { } /** - * Create expression that returns {@code length} codepoints starting at {@code start}. + * 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); @@ -102,7 +170,17 @@ public static Exp substr(Exp start, Exp length, Exp src) { } /** - * Create expression that returns the character at {@code index} as a 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); @@ -110,8 +188,17 @@ public static Exp charAt(Exp index, Exp src) { } /** - * Create expression that returns the codepoint index of the first match of - * {@code needle} in the source, or -1 if not found. + * 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); @@ -120,7 +207,18 @@ public static Exp find(Exp needle, Exp src) { /** * Create expression that returns the codepoint index of the {@code occurrence}-th - * match of {@code needle}, or -1 if not found. + * 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); @@ -128,7 +226,18 @@ public static Exp find(Exp needle, Exp occurrence, Exp src) { } /** - * Create expression that returns 1 if the source contains {@code needle}, 0 otherwise. + * 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); @@ -136,7 +245,16 @@ public static Exp contains(Exp needle, Exp src) { } /** - * Create expression that returns 1 if the source begins with {@code prefix}, 0 otherwise. + * 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); @@ -144,7 +262,16 @@ public static Exp startsWith(Exp prefix, Exp src) { } /** - * Create expression that returns 1 if the source ends with {@code suffix}, 0 otherwise. + * 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); @@ -152,7 +279,16 @@ public static Exp endsWith(Exp suffix, Exp src) { } /** - * Create expression that parses the source as int64. + * 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); @@ -160,7 +296,16 @@ public static Exp toInteger(Exp src) { } /** - * Create expression that parses the source as a 64-bit float. + * 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); @@ -168,7 +313,17 @@ public static Exp toDouble(Exp src) { } /** - * Create expression that returns the UTF-8 byte length of the source. + * 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); @@ -176,7 +331,15 @@ public static Exp byteLength(Exp src) { } /** - * Create expression that returns 1 if the source parses as a number, 0 otherwise. + * 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); @@ -184,8 +347,18 @@ public static Exp isNumeric(Exp src) { } /** - * Create expression that returns 1 if the source parses as a number of the requested - * {@link com.aerospike.client.operation.StringNumericType}, 0 otherwise. + * 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); @@ -193,7 +366,15 @@ public static Exp isNumeric(int numericType, Exp src) { } /** - * Create expression that returns 1 if every cased character in the source is uppercase. + * 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); @@ -201,7 +382,15 @@ public static Exp isUpper(Exp src) { } /** - * Create expression that returns 1 if every cased character in the source is lowercase. + * 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); @@ -209,7 +398,15 @@ public static Exp isLower(Exp src) { } /** - * Create expression that returns the UTF-8 bytes of the source as a blob. + * 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); @@ -217,7 +414,16 @@ public static Exp toBlob(Exp src) { } /** - * Create expression that splits the source by Unicode codepoint and returns a list of strings. + * 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); @@ -225,7 +431,18 @@ public static Exp split(Exp src) { } /** - * Create expression that splits the source by {@code separator} and returns a list of strings. + * 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); @@ -233,7 +450,16 @@ public static Exp split(Exp separator, Exp src) { } /** - * Create expression that base64-decodes the source and returns a blob. + * 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); @@ -241,7 +467,17 @@ public static Exp b64Decode(Exp src) { } /** - * Create expression that returns 1 if {@code pattern} (ICU regex) matches the source, 0 otherwise. + * 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); @@ -249,8 +485,20 @@ public static Exp regexCompare(Exp pattern, Exp src) { } /** - * Create expression that returns 1 if {@code pattern} (ICU regex) matches the source under - * {@link StringRegexFlags}, 0 otherwise. + * 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); @@ -262,8 +510,21 @@ public static Exp regexCompare(Exp pattern, int regexFlags, Exp src) { //----------------------------------------------------------------- /** - * Create expression that inserts {@code value} at codepoint {@code index} of the source - * and returns the resulting string. + * 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); @@ -271,8 +532,22 @@ public static Exp insert(StringPolicy policy, Exp index, Exp value, Exp src) { } /** - * Create expression that overwrites characters starting at codepoint {@code index} with - * {@code value} and returns the resulting string. + * 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); @@ -280,9 +555,21 @@ public static Exp overwrite(StringPolicy policy, Exp index, Exp value, Exp src) } /** - * Create expression that concatenates {@code values} (a list of strings) onto the source - * and returns the resulting string. Single-string callers can wrap their value in a - * 1-element list via {@link Exp#val(java.util.List)}. + * 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); @@ -290,8 +577,20 @@ public static Exp concat(StringPolicy policy, Exp values, Exp src) { } /** - * Create expression that removes characters from codepoint {@code start} to the end of - * the source and returns the resulting string. + * 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); @@ -299,8 +598,21 @@ public static Exp snip(StringPolicy policy, Exp start, Exp src) { } /** - * Create expression that removes characters from codepoint {@code start} (inclusive) to - * {@code end} (exclusive) and returns the resulting string. + * 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); @@ -308,8 +620,21 @@ public static Exp snip(StringPolicy policy, Exp start, Exp end, Exp src) { } /** - * Create expression that replaces the first occurrence of {@code needle} with {@code replacement} - * and returns the resulting string. + * 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); @@ -317,8 +642,21 @@ public static Exp replace(StringPolicy policy, Exp needle, Exp replacement, Exp } /** - * Create expression that replaces every occurrence of {@code needle} with {@code replacement} - * and returns the resulting string. + * 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); @@ -326,7 +664,16 @@ public static Exp replaceAll(StringPolicy policy, Exp needle, Exp replacement, E } /** - * Create expression that returns the source uppercased. + * 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); @@ -334,7 +681,16 @@ public static Exp upper(StringPolicy policy, Exp src) { } /** - * Create expression that returns the source lowercased. + * 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); @@ -342,7 +698,17 @@ public static Exp lower(StringPolicy policy, Exp src) { } /** - * Create expression that returns the source case-folded (locale-independent lowercase). + * 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); @@ -350,7 +716,16 @@ public static Exp caseFold(StringPolicy policy, Exp src) { } /** - * Create expression that returns the source normalized to Unicode NFC form. + * 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); @@ -358,7 +733,17 @@ public static Exp normalizeNFC(StringPolicy policy, Exp src) { } /** - * Create expression that returns the source with whitespace removed from the start. + * 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); @@ -366,7 +751,17 @@ public static Exp trimStart(StringPolicy policy, Exp src) { } /** - * Create expression that returns the source with whitespace removed from the end. + * 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); @@ -374,7 +769,17 @@ public static Exp trimEnd(StringPolicy policy, Exp src) { } /** - * Create expression that returns the source with whitespace removed from both ends. + * 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); @@ -382,8 +787,21 @@ public static Exp trim(StringPolicy policy, Exp src) { } /** - * Create expression that pads the start of the source to {@code targetLength} codepoints - * using {@code padString}. + * 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); @@ -391,8 +809,21 @@ public static Exp padStart(StringPolicy policy, Exp targetLength, Exp padString, } /** - * Create expression that pads the end of the source to {@code targetLength} codepoints - * using {@code padString}. + * 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); @@ -400,7 +831,19 @@ public static Exp padEnd(StringPolicy policy, Exp targetLength, Exp padString, E } /** - * Create expression that returns the source repeated {@code count} times. + * 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); @@ -408,9 +851,24 @@ public static Exp repeat(StringPolicy policy, Exp count, Exp src) { } /** - * Create expression that replaces matches of {@code pattern} (ICU regex) with - * {@code replacement} and returns the resulting string. Use - * {@link StringRegexFlags#GLOBAL} to replace all matches. + * 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 write policy controlling NO_FAIL semantics + * @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, @@ -429,7 +887,16 @@ public static Exp regexReplace( /** * 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. + * {@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 = emptyArray(); @@ -449,6 +916,9 @@ private static Exp addModify(Exp src, byte[] bytes) { } // [cmd, [needle, repl], flags] — needle/replacement nested inside a 2-element list. + // Specialized packing method. Leaving in StringExp instead of moving to Pack since the + // structure is specific to string replace operations and doesn't fit the usual pattern + // of a command followed by a flat list of arguments. private static byte[] packReplace(int command, Exp needle, Exp replacement, int flags) { Packer packer = new Packer(); for (int i = 0; i < 2; i++) { @@ -464,6 +934,9 @@ private static byte[] packReplace(int command, Exp needle, Exp replacement, int } // [REGEX_REPLACE, [pattern, repl], regexFlags, flags] + // Specialized packing method. Leaving in StringExp instead of moving to Pack since the + // structure is specific to string replace operations and doesn't fit the usual pattern + // of a command followed by a flat list of arguments. private static byte[] packRegexReplace(Exp pattern, Exp replacement, int regexFlags, int flags) { Packer packer = new Packer(); for (int i = 0; i < 2; i++) { diff --git a/client/src/com/aerospike/client/operation/StringOperation.java b/client/src/com/aerospike/client/operation/StringOperation.java index 6a74d681c..99566424e 100644 --- a/client/src/com/aerospike/client/operation/StringOperation.java +++ b/client/src/com/aerospike/client/operation/StringOperation.java @@ -24,18 +24,30 @@ import com.aerospike.client.cdt.CTX; import com.aerospike.client.command.ParticleType; import com.aerospike.client.util.Pack; -import com.aerospike.client.util.Packer; /** - * String operations. Create string operations used by the client operate command. + * String operations. Create operations to be passed to the client {@code operate} + * command for inspecting and modifying string bins. *

* Index orientation is left-to-right with codepoint addressing. Negative indexes - * count from the end of the string ({@code -1} = last character). Out-of-bounds + * 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 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 @@ -81,8 +93,41 @@ public final class StringOperation { //----------------------------------------------------------------- /** - * Create string {@code strlen} operation. - * Server returns the number of unicode codepoints in the string bin (int64). + * 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 = Pack.pack(STRLEN, ctx); @@ -90,8 +135,19 @@ public static Operation strlen(String binName, CTX... ctx) { } /** - * Create string {@code substr} operation that reads from {@code start} to the end of the string. - * Negative indexes count from the end. + * 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 = Pack.pack(SUBSTR, start, ctx); @@ -99,8 +155,19 @@ public static Operation substr(String binName, int start, CTX... ctx) { } /** - * Create string {@code substr} operation that reads {@code length} codepoints starting at {@code start}. - * Negative indexes count from the end of the 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 = Pack.pack(SUBSTR, start, length, ctx); @@ -108,8 +175,19 @@ public static Operation substr(String binName, int start, int length, CTX... ctx } /** - * Create string {@code charAt} operation. Server returns the character at {@code index} as a string. - * Negative indexes count from the end of the 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 = Pack.pack(CHAR_AT, index, ctx); @@ -117,8 +195,19 @@ public static Operation charAt(String binName, int index, CTX... ctx) { } /** - * Create string {@code find} operation. Server returns the codepoint index of the first - * occurrence of {@code needle}, or -1 if not found. + * 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 = Pack.pack(FIND, Value.get(needle), ctx); @@ -126,17 +215,40 @@ public static Operation find(String binName, String needle, CTX... ctx) { } /** - * Create string {@code find} operation. Server returns the codepoint index of the - * {@code occurrence}-th match of {@code needle} (1 = first match), or -1 if not found. + * 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 = packCmdValueInt(FIND, Value.get(needle), occurrence, ctx); + byte[] bytes = Pack.pack(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. Server returns true if the bin contains - * {@code needle} as a substring, false otherwise. + * 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 = Pack.pack(CONTAINS, Value.get(needle), ctx); @@ -144,8 +256,18 @@ public static Operation contains(String binName, String needle, CTX... ctx) { } /** - * Create string {@code startsWith} operation. Server returns true if the bin begins with - * {@code prefix}, false otherwise. + * 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 = Pack.pack(STARTS_WITH, Value.get(prefix), ctx); @@ -153,8 +275,18 @@ public static Operation startsWith(String binName, String prefix, CTX... ctx) { } /** - * Create string {@code endsWith} operation. Server returns true if the bin ends with - * {@code suffix}, false otherwise. + * 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 = Pack.pack(ENDS_WITH, Value.get(suffix), ctx); @@ -162,8 +294,18 @@ public static Operation endsWith(String binName, String suffix, CTX... ctx) { } /** - * Create string {@code toInteger} operation. Server parses the string as an int64. - * Returns AEROSPIKE_ERR_PARAMETER if the bin cannot be parsed as an integer. + * 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 = Pack.pack(TO_INTEGER, ctx); @@ -171,8 +313,18 @@ public static Operation toInteger(String binName, CTX... ctx) { } /** - * Create string {@code toDouble} operation. Server parses the string as a 64-bit float. - * Returns AEROSPIKE_ERR_PARAMETER if the bin cannot be parsed as a double. + * 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 = Pack.pack(TO_DOUBLE, ctx); @@ -180,8 +332,18 @@ public static Operation toDouble(String binName, CTX... ctx) { } /** - * Create string {@code byteLength} operation. Server returns the UTF-8 byte length - * of the string (int64). + * 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 = Pack.pack(BYTE_LENGTH, ctx); @@ -189,8 +351,18 @@ public static Operation byteLength(String binName, CTX... ctx) { } /** - * Create string {@code isNumeric} operation. Server returns true if the bin contains a valid - * integer or float, false otherwise. + * 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 = Pack.pack(IS_NUMERIC, ctx); @@ -199,7 +371,19 @@ public static Operation isNumeric(String binName, CTX... ctx) { /** * Create string {@code isNumeric} operation that filters by {@code numericType} - * (see {@link StringNumericType}). + * (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 = Pack.pack(IS_NUMERIC, numericType, ctx); @@ -207,8 +391,17 @@ public static Operation isNumeric(String binName, int numericType, CTX... ctx) { } /** - * Create string {@code isUpper} operation. Server returns true if every cased character - * in the bin is uppercase, false otherwise. + * 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 = Pack.pack(IS_UPPER, ctx); @@ -216,8 +409,17 @@ public static Operation isUpper(String binName, CTX... ctx) { } /** - * Create string {@code isLower} operation. Server returns true if every cased character - * in the bin is lowercase, false otherwise. + * 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 = Pack.pack(IS_LOWER, ctx); @@ -225,8 +427,18 @@ public static Operation isLower(String binName, CTX... ctx) { } /** - * Create string {@code toBlob} operation. Server returns the UTF-8 bytes of the string - * as a blob. + * 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 = Pack.pack(TO_BLOB, ctx); @@ -234,8 +446,18 @@ public static Operation toBlob(String binName, CTX... ctx) { } /** - * Create string {@code split} operation that splits by Unicode codepoint - * (each codepoint becomes its own list element). + * 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 = Pack.pack(SPLIT, ctx); @@ -243,8 +465,19 @@ public static Operation split(String binName, CTX... ctx) { } /** - * Create string {@code split} operation that splits by {@code separator}. - * Server returns a list of strings. + * 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 = Pack.pack(SPLIT, Value.get(separator), ctx); @@ -252,8 +485,18 @@ public static Operation split(String binName, String separator, CTX... ctx) { } /** - * Create string {@code b64Decode} operation. Server base64-decodes the string and - * returns a blob. + * 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 = Pack.pack(B64_DECODE, ctx); @@ -261,8 +504,19 @@ public static Operation b64Decode(String binName, CTX... ctx) { } /** - * Create string {@code regexCompare} operation. Server matches {@code pattern} (ICU - * regex syntax) against the bin and returns true on match, false otherwise. + * 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 = Pack.pack(REGEX_COMPARE, Value.get(pattern), ctx); @@ -270,10 +524,24 @@ public static Operation regexCompare(String binName, String pattern, CTX... ctx) } /** - * Create string {@code regexCompare} operation with {@link StringRegexFlags}. + * 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 = packCmdValueInt(REGEX_COMPARE, Value.get(pattern), regexFlags, ctx); + byte[] bytes = Pack.pack(REGEX_COMPARE, Value.get(pattern), regexFlags, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -282,8 +550,21 @@ public static Operation regexCompare(String binName, String pattern, int regexFl //----------------------------------------------------------------- /** - * Create string {@code insert} operation that inserts {@code value} at codepoint - * {@code index}. Negative indexes count from the end of the string. + * 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 = Pack.pack(INSERT, index, Value.get(value), policy.flags, ctx); @@ -291,8 +572,22 @@ public static Operation insert(StringPolicy policy, String binName, int index, S } /** - * Create string {@code overwrite} operation that overwrites characters starting at - * codepoint {@code index} with {@code value}. + * 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 = Pack.pack(OVERWRITE, index, Value.get(value), policy.flags, ctx); @@ -301,6 +596,18 @@ public static Operation overwrite(StringPolicy policy, String binName, int index /** * 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 list = new ArrayList(1); @@ -310,8 +617,20 @@ public static Operation concat(StringPolicy policy, String binName, String value } /** - * Create string {@code concat} operation that appends every element of {@code values} + * Create string {@code concat} operation that appends each element of {@code values} * to the bin in order. + * + * 
{@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 values, CTX... ctx) { List list = toValueList(values); @@ -320,8 +639,20 @@ public static Operation concat(StringPolicy policy, String binName, List } /** - * Create string {@code snip} operation that removes characters starting at codepoint - * {@code start} through the end of the string. + * Create string {@code snip} operation that removes codepoints starting at + * codepoint {@code start} through the end of the string. + * + * 
{@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 = Pack.pack(SNIP, start, policy.flags, ctx); @@ -329,8 +660,21 @@ public static Operation snip(StringPolicy policy, String binName, int start, CTX } /** - * Create string {@code snip} operation that removes characters from codepoint - * {@code start} (inclusive) to {@code end} (exclusive). + * 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 = Pack.pack(SNIP, start, end, policy.flags, ctx); @@ -340,6 +684,19 @@ public static Operation snip(StringPolicy policy, String binName, int start, int /** * 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 list = pair(needle, replacement); @@ -350,6 +707,19 @@ public static Operation replace(StringPolicy policy, String binName, String need /** * Create string {@code replaceAll} operation that replaces every occurrence of * {@code needle} with {@code replacement}. + * + * 
{@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 list = pair(needle, replacement); @@ -359,6 +729,16 @@ public static Operation replaceAll(StringPolicy policy, String binName, String n /** * Create string {@code upper} operation that uppercases the bin in place. + * + * 
{@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 = Pack.pack(UPPER, policy.flags, ctx); @@ -367,6 +747,16 @@ public static Operation upper(StringPolicy policy, String binName, CTX... ctx) { /** * 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 = Pack.pack(LOWER, policy.flags, ctx); @@ -374,8 +764,18 @@ public static Operation lower(StringPolicy policy, String binName, CTX... ctx) { } /** - * Create string {@code caseFold} operation. Server applies a locale-independent case - * fold (lowercase) to the bin. + * 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 = Pack.pack(CASE_FOLD, policy.flags, ctx); @@ -383,8 +783,18 @@ public static Operation caseFold(StringPolicy policy, String binName, CTX... ctx } /** - * Create string {@code normalizeNFC} operation. Server normalizes the bin to Unicode - * NFC form. + * 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 = Pack.pack(NORMALIZE_NFC, policy.flags, ctx); @@ -394,6 +804,17 @@ public static Operation normalizeNFC(StringPolicy policy, String binName, CTX... /** * 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 = Pack.pack(TRIM_START, policy.flags, ctx); @@ -403,6 +824,17 @@ public static Operation trimStart(StringPolicy policy, String binName, CTX... ct /** * 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 = Pack.pack(TRIM_END, policy.flags, ctx); @@ -412,6 +844,17 @@ public static Operation trimEnd(StringPolicy policy, String binName, CTX... ctx) /** * 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 = Pack.pack(TRIM, policy.flags, ctx); @@ -419,9 +862,22 @@ public static Operation trim(StringPolicy policy, String binName, CTX... ctx) { } /** - * Create string {@code padStart} operation. Server prepends {@code padString} repeatedly - * until the bin reaches {@code targetLength} codepoints. No-op if already at or above - * target length. + * 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 = Pack.pack(PAD_START, targetLength, Value.get(padString), policy.flags, ctx); @@ -429,9 +885,22 @@ public static Operation padStart(StringPolicy policy, String binName, int target } /** - * Create string {@code padEnd} operation. Server appends {@code padString} repeatedly - * until the bin reaches {@code targetLength} codepoints. No-op if already at or above - * target length. + * 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 = Pack.pack(PAD_END, targetLength, Value.get(padString), policy.flags, ctx); @@ -441,6 +910,18 @@ public static Operation padEnd(StringPolicy policy, String binName, int targetLe /** * 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 = Pack.pack(REPEAT, count, policy.flags, ctx); @@ -449,8 +930,25 @@ public static Operation repeat(StringPolicy policy, String binName, int count, C /** * Create string {@code regexReplace} operation that replaces the first match of - * {@code pattern} with {@code replacement}. Use {@link StringRegexFlags#GLOBAL} - * to replace all matches. + * {@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, @@ -471,12 +969,35 @@ public static Operation regexReplace( //----------------------------------------------------------------- /** - * Create {@code toString} operation that converts an integer, float, string, or blob - * bin to its string representation. Returns AEROSPIKE_ERR_INCOMPATIBLE_TYPE for any - * other bin type. + * Create {@code toString} operation that converts an integer, float, string, or + * blob bin to its string representation. Returns + * {@code AEROSPIKE_ERR_INCOMPATIBLE_TYPE} for any other bin type. *

- * The wire format for this op carries no payload; the bin is referenced solely by - * the operation header, so {@link CTX} navigation is not supported. + * 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()); @@ -501,19 +1022,4 @@ private static List toValueList(List strings) { return list; } - private static byte[] packCmdValueInt(int command, Value value, int v, CTX[] ctx) { - Packer packer = new Packer(); - for (int i = 0; i < 2; i++) { - Pack.init(packer, ctx); - packer.packArrayBegin(3); - packer.packInt(command); - value.pack(packer); - packer.packInt(v); - - if (i == 0) { - packer.createBuffer(); - } - } - return packer.getBuffer(); - } } 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(); From a7c101bd86de721a9f99754de2d91c95b2b557ee Mon Sep 17 00:00:00 2001 From: Mirza Karacic Date: Mon, 11 May 2026 12:01:33 -0700 Subject: [PATCH 6/9] Removed policy from call since server is ignoring it. Also updated comment to contain relevant information. --- .../com/aerospike/client/exp/StringExp.java | 21 +++++++++++-------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/client/src/com/aerospike/client/exp/StringExp.java b/client/src/com/aerospike/client/exp/StringExp.java index 6b0dc1123..8d3bd40e7 100644 --- a/client/src/com/aerospike/client/exp/StringExp.java +++ b/client/src/com/aerospike/client/exp/StringExp.java @@ -863,7 +863,9 @@ public static Exp repeat(StringPolicy policy, Exp count, Exp src) { * Exp.stringBin("text")); * } * - * @param policy write policy controlling NO_FAIL semantics + * @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 @@ -877,7 +879,7 @@ public static Exp regexReplace( int regexFlags, Exp src ) { - byte[] bytes = packRegexReplace(pattern, replacement, regexFlags, policy.flags); + byte[] bytes = packRegexReplace(pattern, replacement, regexFlags); return addModify(src, bytes); } @@ -933,20 +935,21 @@ private static byte[] packReplace(int command, Exp needle, Exp replacement, int return packer.getBuffer(); } - // [REGEX_REPLACE, [pattern, repl], regexFlags, flags] - // Specialized packing method. Leaving in StringExp instead of moving to Pack since the - // structure is specific to string replace operations and doesn't fit the usual pattern - // of a command followed by a flat list of arguments. - private static byte[] packRegexReplace(Exp pattern, Exp replacement, int regexFlags, int flags) { + // [REGEX_REPLACE, [pattern, repl], regexFlags] — 3 elements. + // Server's regex_replace op table accepts only [list, regexFlags]; no slot for + // policy flags (max_args=2 in particle_string.c:476). Specialized packing method + // kept in StringExp instead of moving to Pack since the structure is specific to + // string replace operations and doesn't fit the usual pattern of a command + // followed by a flat list of arguments. + private static byte[] packRegexReplace(Exp pattern, Exp replacement, int regexFlags) { Packer packer = new Packer(); for (int i = 0; i < 2; i++) { - packer.packArrayBegin(4); + packer.packArrayBegin(3); packer.packInt(REGEX_REPLACE); packer.packArrayBegin(2); pattern.pack(packer); replacement.pack(packer); packer.packInt(regexFlags); - packer.packInt(flags); if (i == 0) packer.createBuffer(); } return packer.getBuffer(); From 531e2cb0f5baf688edc6211cf56aaae1b022792a Mon Sep 17 00:00:00 2001 From: Mirza Karacic Date: Wed, 20 May 2026 13:45:02 -0700 Subject: [PATCH 7/9] Added TestStringExp --- .../client/operation/StringOperation.java | 237 +++++++-- test/src/com/aerospike/test/SuiteSync.java | 2 + .../test/sync/basic/TestOperateString.java | 196 ++++++++ .../test/sync/basic/TestStringExp.java | 472 ++++++++++++++++++ 4 files changed, 866 insertions(+), 41 deletions(-) create mode 100644 test/src/com/aerospike/test/sync/basic/TestStringExp.java diff --git a/client/src/com/aerospike/client/operation/StringOperation.java b/client/src/com/aerospike/client/operation/StringOperation.java index 99566424e..b73844596 100644 --- a/client/src/com/aerospike/client/operation/StringOperation.java +++ b/client/src/com/aerospike/client/operation/StringOperation.java @@ -24,6 +24,7 @@ import com.aerospike.client.cdt.CTX; import com.aerospike.client.command.ParticleType; import com.aerospike.client.util.Pack; +import com.aerospike.client.util.Packer; /** * String operations. Create operations to be passed to the client {@code operate} @@ -130,7 +131,7 @@ public final class StringOperation { * @return read operation returning the codepoint count (int64) */ public static Operation strlen(String binName, CTX... ctx) { - byte[] bytes = Pack.pack(STRLEN, ctx); + byte[] bytes = packStringOp(STRLEN, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -150,7 +151,7 @@ public static Operation strlen(String binName, CTX... ctx) { * @return read operation returning the substring */ public static Operation substr(String binName, int start, CTX... ctx) { - byte[] bytes = Pack.pack(SUBSTR, start, ctx); + byte[] bytes = packStringOp(SUBSTR, start, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -170,7 +171,7 @@ public static Operation substr(String binName, int start, CTX... ctx) { * @return read operation returning the substring */ public static Operation substr(String binName, int start, int length, CTX... ctx) { - byte[] bytes = Pack.pack(SUBSTR, start, length, ctx); + byte[] bytes = packStringOp(SUBSTR, start, length, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -190,7 +191,7 @@ public static Operation substr(String binName, int start, int length, CTX... ctx * @return read operation returning a single-codepoint string */ public static Operation charAt(String binName, int index, CTX... ctx) { - byte[] bytes = Pack.pack(CHAR_AT, index, ctx); + byte[] bytes = packStringOp(CHAR_AT, index, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -210,7 +211,7 @@ public static Operation charAt(String binName, int index, CTX... ctx) { * @return read operation returning the codepoint index, or -1 if absent */ public static Operation find(String binName, String needle, CTX... ctx) { - byte[] bytes = Pack.pack(FIND, Value.get(needle), ctx); + byte[] bytes = packStringOp(FIND, Value.get(needle), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -231,7 +232,7 @@ public static Operation find(String binName, String needle, CTX... ctx) { * @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 = Pack.pack(FIND, Value.get(needle), occurrence, ctx); + byte[] bytes = packStringOp(FIND, Value.get(needle), occurrence, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -251,7 +252,7 @@ public static Operation find(String binName, String needle, int occurrence, CTX. * @return read operation returning a boolean match flag */ public static Operation contains(String binName, String needle, CTX... ctx) { - byte[] bytes = Pack.pack(CONTAINS, Value.get(needle), ctx); + byte[] bytes = packStringOp(CONTAINS, Value.get(needle), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -270,7 +271,7 @@ public static Operation contains(String binName, String needle, CTX... ctx) { * @return read operation returning a boolean match flag */ public static Operation startsWith(String binName, String prefix, CTX... ctx) { - byte[] bytes = Pack.pack(STARTS_WITH, Value.get(prefix), ctx); + byte[] bytes = packStringOp(STARTS_WITH, Value.get(prefix), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -289,7 +290,7 @@ public static Operation startsWith(String binName, String prefix, CTX... ctx) { * @return read operation returning a boolean match flag */ public static Operation endsWith(String binName, String suffix, CTX... ctx) { - byte[] bytes = Pack.pack(ENDS_WITH, Value.get(suffix), ctx); + byte[] bytes = packStringOp(ENDS_WITH, Value.get(suffix), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -308,7 +309,7 @@ public static Operation endsWith(String binName, String suffix, CTX... ctx) { * @return read operation returning the parsed int64 */ public static Operation toInteger(String binName, CTX... ctx) { - byte[] bytes = Pack.pack(TO_INTEGER, ctx); + byte[] bytes = packStringOp(TO_INTEGER, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -327,7 +328,7 @@ public static Operation toInteger(String binName, CTX... ctx) { * @return read operation returning the parsed double */ public static Operation toDouble(String binName, CTX... ctx) { - byte[] bytes = Pack.pack(TO_DOUBLE, ctx); + byte[] bytes = packStringOp(TO_DOUBLE, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -346,7 +347,7 @@ public static Operation toDouble(String binName, CTX... ctx) { * @return read operation returning the byte length (int64) */ public static Operation byteLength(String binName, CTX... ctx) { - byte[] bytes = Pack.pack(BYTE_LENGTH, ctx); + byte[] bytes = packStringOp(BYTE_LENGTH, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -365,7 +366,7 @@ public static Operation byteLength(String binName, CTX... ctx) { * @return read operation returning a boolean match flag */ public static Operation isNumeric(String binName, CTX... ctx) { - byte[] bytes = Pack.pack(IS_NUMERIC, ctx); + byte[] bytes = packStringOp(IS_NUMERIC, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -386,7 +387,7 @@ public static Operation isNumeric(String binName, CTX... ctx) { * @return read operation returning a boolean match flag */ public static Operation isNumeric(String binName, int numericType, CTX... ctx) { - byte[] bytes = Pack.pack(IS_NUMERIC, numericType, ctx); + byte[] bytes = packStringOp(IS_NUMERIC, numericType, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -404,7 +405,7 @@ public static Operation isNumeric(String binName, int numericType, CTX... ctx) { * @return read operation returning a boolean match flag */ public static Operation isUpper(String binName, CTX... ctx) { - byte[] bytes = Pack.pack(IS_UPPER, ctx); + byte[] bytes = packStringOp(IS_UPPER, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -422,7 +423,7 @@ public static Operation isUpper(String binName, CTX... ctx) { * @return read operation returning a boolean match flag */ public static Operation isLower(String binName, CTX... ctx) { - byte[] bytes = Pack.pack(IS_LOWER, ctx); + byte[] bytes = packStringOp(IS_LOWER, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -441,7 +442,7 @@ public static Operation isLower(String binName, CTX... ctx) { * @return read operation returning a byte[] blob */ public static Operation toBlob(String binName, CTX... ctx) { - byte[] bytes = Pack.pack(TO_BLOB, ctx); + byte[] bytes = packStringOp(TO_BLOB, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -460,7 +461,7 @@ public static Operation toBlob(String binName, CTX... ctx) { * @return read operation returning a list of single-codepoint strings */ public static Operation split(String binName, CTX... ctx) { - byte[] bytes = Pack.pack(SPLIT, ctx); + byte[] bytes = packStringOp(SPLIT, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -480,7 +481,7 @@ public static Operation split(String binName, CTX... ctx) { * @return read operation returning a list of token strings */ public static Operation split(String binName, String separator, CTX... ctx) { - byte[] bytes = Pack.pack(SPLIT, Value.get(separator), ctx); + byte[] bytes = packStringOp(SPLIT, Value.get(separator), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -499,7 +500,7 @@ public static Operation split(String binName, String separator, CTX... ctx) { * @return read operation returning the decoded byte[] */ public static Operation b64Decode(String binName, CTX... ctx) { - byte[] bytes = Pack.pack(B64_DECODE, ctx); + byte[] bytes = packStringOp(B64_DECODE, ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -519,7 +520,7 @@ public static Operation b64Decode(String binName, CTX... ctx) { * @return read operation returning a boolean match flag */ public static Operation regexCompare(String binName, String pattern, CTX... ctx) { - byte[] bytes = Pack.pack(REGEX_COMPARE, Value.get(pattern), ctx); + byte[] bytes = packStringOp(REGEX_COMPARE, Value.get(pattern), ctx); return new Operation(Operation.Type.STRING_READ, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -541,7 +542,7 @@ public static Operation regexCompare(String binName, String pattern, CTX... ctx) * @return read operation returning a boolean match flag */ public static Operation regexCompare(String binName, String pattern, int regexFlags, CTX... ctx) { - byte[] bytes = Pack.pack(REGEX_COMPARE, Value.get(pattern), regexFlags, 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)); } @@ -567,7 +568,7 @@ public static Operation regexCompare(String binName, String pattern, int regexFl * @return modify operation */ public static Operation insert(StringPolicy policy, String binName, int index, String value, CTX... ctx) { - byte[] bytes = Pack.pack(INSERT, index, Value.get(value), policy.flags, 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)); } @@ -590,7 +591,7 @@ public static Operation insert(StringPolicy policy, String binName, int index, S * @return modify operation */ public static Operation overwrite(StringPolicy policy, String binName, int index, String value, CTX... ctx) { - byte[] bytes = Pack.pack(OVERWRITE, index, Value.get(value), policy.flags, 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)); } @@ -612,7 +613,7 @@ public static Operation overwrite(StringPolicy policy, String binName, int index public static Operation concat(StringPolicy policy, String binName, String value, CTX... ctx) { List list = new ArrayList(1); list.add(Value.get(value)); - byte[] bytes = Pack.pack(CONCAT, list, policy.flags, ctx); + byte[] bytes = packStringOp(CONCAT, list, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -634,7 +635,7 @@ public static Operation concat(StringPolicy policy, String binName, String value */ public static Operation concat(StringPolicy policy, String binName, List values, CTX... ctx) { List list = toValueList(values); - byte[] bytes = Pack.pack(CONCAT, list, policy.flags, ctx); + byte[] bytes = packStringOp(CONCAT, list, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -655,7 +656,7 @@ public static Operation concat(StringPolicy policy, String binName, List * @return modify operation */ public static Operation snip(StringPolicy policy, String binName, int start, CTX... ctx) { - byte[] bytes = Pack.pack(SNIP, start, policy.flags, ctx); + byte[] bytes = packStringOp(SNIP, start, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -677,7 +678,7 @@ public static Operation snip(StringPolicy policy, String binName, int start, CTX * @return modify operation */ public static Operation snip(StringPolicy policy, String binName, int start, int end, CTX... ctx) { - byte[] bytes = Pack.pack(SNIP, start, end, policy.flags, ctx); + byte[] bytes = packStringOp(SNIP, start, end, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -700,7 +701,7 @@ public static Operation snip(StringPolicy policy, String binName, int start, int */ public static Operation replace(StringPolicy policy, String binName, String needle, String replacement, CTX... ctx) { List list = pair(needle, replacement); - byte[] bytes = Pack.pack(REPLACE, list, policy.flags, ctx); + byte[] bytes = packStringOp(REPLACE, list, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -723,7 +724,7 @@ public static Operation replace(StringPolicy policy, String binName, String need */ public static Operation replaceAll(StringPolicy policy, String binName, String needle, String replacement, CTX... ctx) { List list = pair(needle, replacement); - byte[] bytes = Pack.pack(REPLACE_ALL, list, policy.flags, ctx); + byte[] bytes = packStringOp(REPLACE_ALL, list, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -741,7 +742,7 @@ public static Operation replaceAll(StringPolicy policy, String binName, String n * @return modify operation */ public static Operation upper(StringPolicy policy, String binName, CTX... ctx) { - byte[] bytes = Pack.pack(UPPER, policy.flags, ctx); + byte[] bytes = packStringOp(UPPER, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -759,7 +760,7 @@ public static Operation upper(StringPolicy policy, String binName, CTX... ctx) { * @return modify operation */ public static Operation lower(StringPolicy policy, String binName, CTX... ctx) { - byte[] bytes = Pack.pack(LOWER, policy.flags, ctx); + byte[] bytes = packStringOp(LOWER, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -778,7 +779,7 @@ public static Operation lower(StringPolicy policy, String binName, CTX... ctx) { * @return modify operation */ public static Operation caseFold(StringPolicy policy, String binName, CTX... ctx) { - byte[] bytes = Pack.pack(CASE_FOLD, policy.flags, ctx); + byte[] bytes = packStringOp(CASE_FOLD, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -797,7 +798,7 @@ public static Operation caseFold(StringPolicy policy, String binName, CTX... ctx * @return modify operation */ public static Operation normalizeNFC(StringPolicy policy, String binName, CTX... ctx) { - byte[] bytes = Pack.pack(NORMALIZE_NFC, policy.flags, ctx); + byte[] bytes = packStringOp(NORMALIZE_NFC, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -817,7 +818,7 @@ public static Operation normalizeNFC(StringPolicy policy, String binName, CTX... * @return modify operation */ public static Operation trimStart(StringPolicy policy, String binName, CTX... ctx) { - byte[] bytes = Pack.pack(TRIM_START, policy.flags, ctx); + byte[] bytes = packStringOp(TRIM_START, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -837,7 +838,7 @@ public static Operation trimStart(StringPolicy policy, String binName, CTX... ct * @return modify operation */ public static Operation trimEnd(StringPolicy policy, String binName, CTX... ctx) { - byte[] bytes = Pack.pack(TRIM_END, policy.flags, ctx); + byte[] bytes = packStringOp(TRIM_END, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -857,7 +858,7 @@ public static Operation trimEnd(StringPolicy policy, String binName, CTX... ctx) * @return modify operation */ public static Operation trim(StringPolicy policy, String binName, CTX... ctx) { - byte[] bytes = Pack.pack(TRIM, policy.flags, ctx); + byte[] bytes = packStringOp(TRIM, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -880,7 +881,7 @@ public static Operation trim(StringPolicy policy, String binName, CTX... ctx) { * @return modify operation */ public static Operation padStart(StringPolicy policy, String binName, int targetLength, String padString, CTX... ctx) { - byte[] bytes = Pack.pack(PAD_START, targetLength, Value.get(padString), policy.flags, 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)); } @@ -903,7 +904,7 @@ public static Operation padStart(StringPolicy policy, String binName, int target * @return modify operation */ public static Operation padEnd(StringPolicy policy, String binName, int targetLength, String padString, CTX... ctx) { - byte[] bytes = Pack.pack(PAD_END, targetLength, Value.get(padString), policy.flags, 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)); } @@ -924,7 +925,7 @@ public static Operation padEnd(StringPolicy policy, String binName, int targetLe * @return modify operation */ public static Operation repeat(StringPolicy policy, String binName, int count, CTX... ctx) { - byte[] bytes = Pack.pack(REPEAT, count, policy.flags, ctx); + byte[] bytes = packStringOp(REPEAT, count, policy.flags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -960,7 +961,7 @@ public static Operation regexReplace( ) { List list = pair(pattern, replacement); // Server's regex_replace op table accepts only [list, regexFlags]; no slot for policy flags. - byte[] bytes = Pack.pack(REGEX_REPLACE, list, regexFlags, ctx); + byte[] bytes = packStringOp(REGEX_REPLACE, list, regexFlags, ctx); return new Operation(Operation.Type.STRING_MODIFY, binName, new Value.BytesValue(bytes, ParticleType.STRING)); } @@ -1022,4 +1023,158 @@ private static List toValueList(List strings) { return list; } + //----------------------------------------------------------------- + // Flat-CTX wire packer (string-op specific). + // + // When CTX is empty: emits [SUBOP, args...] — identical to Pack.pack. + // When CTX is non-empty: emits the FLAT envelope + // [0xFF, [ctx_id_1, ctx_value_1, ...], SUBOP, args...] + // where SUBOP and its args are flattened into the outer array — there + // is no nested array around them. This matches particle_string.c's + // string_state_init (line ~735), which reads the sentinel, skips the + // ctx flat-list with msgpack_sz_vec, then reads the inner op as a + // direct uint64 (no msgpack_get_list_ele_count_vec call). The CDT + // module (cdt.c:3671) does call list_ele_count for the inner op and + // therefore requires a nested layout — the shared Pack.init helper + // emits that nested form, which is why these string-op overloads exist + // as a separate path. + //----------------------------------------------------------------- + + // Outer array header + (optionally) the [0xFF, ctx_flat_list] prologue. + // innerCount = number of msgpack elements the caller will emit AFTER + // this prologue (the SUBOP integer plus any args, at the outer level). + private static void writeOuterHeader(Packer p, int innerCount, CTX[] ctx) { + boolean hasCtx = ctx != null && ctx.length > 0; + int outerSize = hasCtx ? (2 + innerCount) : innerCount; + p.packArrayBegin(outerSize); + if (hasCtx) { + p.packInt(0xFF); + p.packArrayBegin(ctx.length * 2); + for (CTX c : ctx) { + p.packInt(c.id); + if (c.value != null) { + c.value.pack(p); + } + else { + p.packByteArray(c.exp.getBytes(), 0, c.exp.getBytes().length); + } + } + } + } + + // [SUBOP] + private static byte[] packStringOp(int subop, CTX[] ctx) { + Packer p = new Packer(); + writeOuterHeader(p, 1, ctx); + p.packInt(subop); + p.createBuffer(); + writeOuterHeader(p, 1, ctx); + p.packInt(subop); + return p.getBuffer(); + } + + // [SUBOP, v1] + private static byte[] packStringOp(int subop, int v1, CTX[] ctx) { + Packer p = new Packer(); + writeOuterHeader(p, 2, ctx); + p.packInt(subop); + p.packInt(v1); + p.createBuffer(); + writeOuterHeader(p, 2, ctx); + p.packInt(subop); + p.packInt(v1); + return p.getBuffer(); + } + + // [SUBOP, v1, v2] + private static byte[] packStringOp(int subop, int v1, int v2, CTX[] ctx) { + Packer p = new Packer(); + writeOuterHeader(p, 3, ctx); + p.packInt(subop); + p.packInt(v1); + p.packInt(v2); + p.createBuffer(); + writeOuterHeader(p, 3, ctx); + p.packInt(subop); + p.packInt(v1); + p.packInt(v2); + return p.getBuffer(); + } + + // [SUBOP, v1, v2, v3] + private static byte[] packStringOp(int subop, int v1, int v2, int v3, CTX[] ctx) { + Packer p = new Packer(); + writeOuterHeader(p, 4, ctx); + p.packInt(subop); + p.packInt(v1); + p.packInt(v2); + p.packInt(v3); + p.createBuffer(); + writeOuterHeader(p, 4, ctx); + p.packInt(subop); + p.packInt(v1); + p.packInt(v2); + p.packInt(v3); + return p.getBuffer(); + } + + // [SUBOP, v1] (Value) + private static byte[] packStringOp(int subop, Value v1, CTX[] ctx) { + Packer p = new Packer(); + writeOuterHeader(p, 2, ctx); + p.packInt(subop); + v1.pack(p); + p.createBuffer(); + writeOuterHeader(p, 2, ctx); + p.packInt(subop); + v1.pack(p); + return p.getBuffer(); + } + + // [SUBOP, v1, v2] (Value, int) + private static byte[] packStringOp(int subop, Value v1, int v2, CTX[] ctx) { + Packer p = new Packer(); + writeOuterHeader(p, 3, ctx); + p.packInt(subop); + v1.pack(p); + p.packInt(v2); + p.createBuffer(); + writeOuterHeader(p, 3, ctx); + p.packInt(subop); + v1.pack(p); + p.packInt(v2); + return p.getBuffer(); + } + + // [SUBOP, v1, v2, v3] (int, Value, int) + private static byte[] packStringOp(int subop, int v1, Value v2, int v3, CTX[] ctx) { + Packer p = new Packer(); + writeOuterHeader(p, 4, ctx); + p.packInt(subop); + p.packInt(v1); + v2.pack(p); + p.packInt(v3); + p.createBuffer(); + writeOuterHeader(p, 4, ctx); + p.packInt(subop); + p.packInt(v1); + v2.pack(p); + p.packInt(v3); + return p.getBuffer(); + } + + // [SUBOP, list, v2] (List, int) + private static byte[] packStringOp(int subop, List list, int v2, CTX[] ctx) { + Packer p = new Packer(); + writeOuterHeader(p, 3, ctx); + p.packInt(subop); + p.packValueList(list); + p.packInt(v2); + p.createBuffer(); + writeOuterHeader(p, 3, ctx); + p.packInt(subop); + p.packValueList(list); + p.packInt(v2); + return p.getBuffer(); + } } diff --git a/test/src/com/aerospike/test/SuiteSync.java b/test/src/com/aerospike/test/SuiteSync.java index 57512c085..27bc32591 100644 --- a/test/src/com/aerospike/test/SuiteSync.java +++ b/test/src/com/aerospike/test/SuiteSync.java @@ -53,6 +53,7 @@ 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; @@ -105,6 +106,7 @@ TestReplace.class, TestScan.class, TestServerInfo.class, + TestStringExp.class, TestStringMasking.class, TestTouch.class, TestTxn.class, diff --git a/test/src/com/aerospike/test/sync/basic/TestOperateString.java b/test/src/com/aerospike/test/sync/basic/TestOperateString.java index d1eeb68dd..75e9ddc70 100644 --- a/test/src/com/aerospike/test/sync/basic/TestOperateString.java +++ b/test/src/com/aerospike/test/sync/basic/TestOperateString.java @@ -19,22 +19,31 @@ 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; /** @@ -561,4 +570,191 @@ public void splitResultListEntriesAreReadableStrings() { 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 values) { + client.delete(null, KEY); + client.put(null, KEY, new Bin(BIN, values)); + } + + private static void putMap(Map entries) { + client.delete(null, KEY); + client.put(null, KEY, new Bin(BIN, entries)); + } + + @Test + public void readOpOnStringNestedInList() { + // list = ["alpha", "beta", "hello world"]; strlen at index 2 = 11 + List list = new ArrayList(); + list.add(Value.get("alpha")); + list.add(Value.get("beta")); + list.add(Value.get("hello world")); + putList(list); + + Record r = operate(StringOperation.strlen(BIN, CTX.listIndex(2))); + assertEquals(11L, r.getLong(BIN)); + } + + @Test + public void readBooleanOpOnStringNestedInMap() { + // map = {"a": "Hello", "b": "World"}; startsWith("World","Wor") = true + Map map = new HashMap(); + map.put(Value.get("a"), Value.get("Hello")); + map.put(Value.get("b"), Value.get("World")); + putMap(map); + + Record r = operate(StringOperation.startsWith(BIN, "Wor", CTX.mapKey(Value.get("b")))); + assertTrue(r.getBoolean(BIN)); + } + + @Test + public void modifyOpOnStringNestedInList() { + // list = ["alpha", "beta", "gamma"]; upper at index 1 -> "BETA" + List list = new ArrayList(); + list.add(Value.get("alpha")); + list.add(Value.get("beta")); + list.add(Value.get("gamma")); + putList(list); + + operate(StringOperation.upper(POLICY, BIN, CTX.listIndex(1))); + + List after = client.get(null, KEY).getList(BIN); + assertEquals(Arrays.asList("alpha", "BETA", "gamma"), after); + } + + @Test + public void modifyOpOnStringNestedInMap() { + // map = {"a": "hello world", "b": "foo"}; replace at key "a" + Map map = new HashMap(); + map.put(Value.get("a"), Value.get("hello world")); + map.put(Value.get("b"), Value.get("foo")); + putMap(map); + + operate(StringOperation.replace(POLICY, BIN, "world", "earth", + CTX.mapKey(Value.get("a")))); + + Map after = client.get(null, KEY).getMap(BIN); + assertEquals("hello earth", after.get("a")); + assertEquals("foo", after.get("b")); + } + + @Test + public void modifyOpOnStringDeeplyNestedListInMap() { + // map = {"items": ["one", "two", "three"]}; upper at items[1] -> "TWO" + List inner = new ArrayList(); + inner.add(Value.get("one")); + inner.add(Value.get("two")); + inner.add(Value.get("three")); + + Map map = new HashMap(); + map.put(Value.get("items"), Value.get(inner)); + putMap(map); + + operate(StringOperation.upper(POLICY, BIN, + CTX.mapKey(Value.get("items")), CTX.listIndex(1))); + + Map after = client.get(null, KEY).getMap(BIN); + List items = (List)after.get("items"); + assertEquals(Arrays.asList("one", "TWO", "three"), items); + } + + //================================================================= + // toString op — op-type 19, no payload, no sub-op id, no CTX + // + // Spec §2.6 and §4.1: covers integer/float/string/blob -> string + // conversions, plus the INCOMPATIBLE_TYPE error path for list/map + // bins that the wire format cannot represent. + //================================================================= + + @Test + public void toStringConvertsIntegerBinToString() { + client.delete(null, KEY); + client.put(null, KEY, new Bin(BIN, 42)); + Record r = operate(StringOperation.toString(BIN)); + assertEquals("42", r.getString(BIN)); + } + + @Test + public void toStringConvertsDoubleBinToString() { + client.delete(null, KEY); + client.put(null, KEY, new Bin(BIN, 3.14)); + Record r = operate(StringOperation.toString(BIN)); + // Float-to-string formatting is server-side; assert it parses back. + assertEquals(3.14, Double.parseDouble(r.getString(BIN)), 0.0001); + } + + @Test + public void toStringOnStringBinIsIdentity() { + put("hello"); + Record r = operate(StringOperation.toString(BIN)); + assertEquals("hello", r.getString(BIN)); + } + + @Test + public void toStringConvertsBlobBinToString() { + client.delete(null, KEY); + client.put(null, KEY, new Bin(BIN, new byte[] {'h', 'i'})); + Record r = operate(StringOperation.toString(BIN)); + // Server's blob-to-string representation is well-defined for ASCII bytes. + assertEquals("hi", r.getString(BIN)); + } + + @Test + public void toStringOnListBinReturnsIncompatibleType() { + List list = new ArrayList(); + list.add(Value.get("a")); + list.add(Value.get("b")); + putList(list); + + AerospikeException ae = assertThrows(AerospikeException.class, + () -> operate(StringOperation.toString(BIN))); + assertEquals(ResultCode.BIN_TYPE_ERROR, ae.getResultCode()); + } + + //================================================================= + // NO_FAIL flag — missing-bin path + // + // particle_string.c:926: when the target bin does not exist, the + // server returns AS_OK with no bin written if NO_FAIL is set; without + // it, the server returns AS_ERR_BIN_NOT_FOUND. This is the actual + // scope of NO_FAIL on STRING_MODIFY — the server does NOT honor it + // for wrong-type bins (incompatible-type is hard-errored at line 872 + // regardless of the flag). + //================================================================= + + @Test + public void modifyOnMissingBinWithNoFailIsNoOp() { + // Record exists but the target bin does not — exercises the bin-level + // NO_FAIL path at particle_string.c:926 (not the record-level + // KEY_NOT_FOUND path that fires when the whole record is absent). + client.delete(null, KEY); + client.put(null, KEY, new Bin("other", "untouched")); + + StringPolicy noFail = new StringPolicy(StringWriteFlags.NO_FAIL); + operate(StringOperation.upper(noFail, BIN)); + + // BIN must not have been created; the existing bin must be intact. + Record r = client.get(null, KEY); + assertEquals(null, r.getValue(BIN)); + assertEquals("untouched", r.getString("other")); + } + + @Test + public void modifyOnMissingBinWithoutNoFailRaises() { + client.delete(null, KEY); + client.put(null, KEY, new Bin("other", "untouched")); + + AerospikeException ae = assertThrows(AerospikeException.class, + () -> operate(StringOperation.upper(POLICY, BIN))); + assertEquals(ResultCode.BIN_NOT_FOUND, ae.getResultCode()); + } } diff --git a/test/src/com/aerospike/test/sync/basic/TestStringExp.java b/test/src/com/aerospike/test/sync/basic/TestStringExp.java new file mode 100644 index 000000000..dee1a5c6e --- /dev/null +++ b/test/src/com/aerospike/test/sync/basic/TestStringExp.java @@ -0,0 +1,472 @@ +/* + * 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.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.Bin; +import com.aerospike.client.Key; +import com.aerospike.client.Record; +import com.aerospike.client.Value; +import com.aerospike.client.cdt.ListReturnType; +import com.aerospike.client.cdt.MapReturnType; +import com.aerospike.client.exp.Exp; +import com.aerospike.client.exp.ExpOperation; +import com.aerospike.client.exp.ExpReadFlags; +import com.aerospike.client.exp.Expression; +import com.aerospike.client.exp.ListExp; +import com.aerospike.client.exp.MapExp; +import com.aerospike.client.exp.StringExp; +import com.aerospike.client.operation.StringNumericType; +import com.aerospike.client.operation.StringPolicy; +import com.aerospike.client.operation.StringRegexFlags; +import com.aerospike.client.policy.Policy; +import com.aerospike.test.sync.TestSync; + +/** + * Integration tests for the string filter-expression builders exposed by + * {@link StringExp}. Each test puts a representative bin, builds an + * {@link Expression} that wraps a {@code StringExp.*} call, evaluates it via + * {@link ExpOperation#read} into a virtual bin, and asserts the result. + * + *

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, 2, 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 returns a singleton-list wrapping the whole string. + put("Hello123World"); + Record r2 = eval(StringExp.split(Exp.stringBin(BIN))); + assertEquals(Arrays.asList("Hello123World"), 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)); + } + + @Test + public void regexCompareLiteralSourceIgnoresBin() { + // Source can be any string-yielding expression — not only a bin reference. + put("ignored"); + Record r = eval(StringExp.regexCompare( + Exp.val("[A-Z]+"), Exp.val("HELLO"))); + assertTrue(r.getBoolean(VAR)); + } + + //================================================================= + // 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 snipRemovesFromStartAndRange() { + put("hello world"); + // One-arg form: start through end. + Record r1 = eval(StringExp.snip(POLICY, Exp.val(5), Exp.stringBin(BIN))); + assertEquals("hello", r1.getString(VAR)); + + // Two-arg form: half-open [start, end). + put("hello beautiful world"); + Record r2 = eval(StringExp.snip(POLICY, Exp.val(5), Exp.val(15), Exp.stringBin(BIN))); + assertEquals("hello world", r2.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 list = new ArrayList(); + list.add(Value.get("alpha")); + list.add(Value.get("beta")); + list.add(Value.get("hello world")); + client.delete(null, KEY); + client.put(null, KEY, new Bin(BIN, list)); + + Exp nestedString = ListExp.getByIndex( + ListReturnType.VALUE, Exp.Type.STRING, Exp.val(2), Exp.listBin(BIN)); + Record r = eval(StringExp.strlen(nestedString)); + assertEquals(11L, r.getLong(VAR)); + } + + @Test + public void upperOnStringNestedInMapProjectedViaMapExp() { + Map map = new HashMap(); + map.put(Value.get("a"), Value.get("hello")); + map.put(Value.get("b"), Value.get("world")); + client.delete(null, KEY); + client.put(null, KEY, new Bin(BIN, map)); + + Exp nestedString = MapExp.getByKey( + MapReturnType.VALUE, Exp.Type.STRING, Exp.val("a"), Exp.mapBin(BIN)); + Record r = eval(StringExp.upper(POLICY, nestedString)); + assertEquals("HELLO", r.getString(VAR)); + } +} From 38ec7bfc940eb528e5efca1928fa3aecf3fb4706 Mon Sep 17 00:00:00 2001 From: Mirza Karacic Date: Thu, 21 May 2026 10:09:23 -0700 Subject: [PATCH 8/9] Fixed test with working version of server --- .../com/aerospike/client/exp/StringExp.java | 62 ++++++++++++------- .../test/sync/basic/TestStringExp.java | 37 +++++------ 2 files changed, 57 insertions(+), 42 deletions(-) diff --git a/client/src/com/aerospike/client/exp/StringExp.java b/client/src/com/aerospike/client/exp/StringExp.java index 8d3bd40e7..547dbf0b2 100644 --- a/client/src/com/aerospike/client/exp/StringExp.java +++ b/client/src/com/aerospike/client/exp/StringExp.java @@ -241,7 +241,7 @@ public static Exp find(Exp needle, Exp occurrence, Exp src) { */ public static Exp contains(Exp needle, Exp src) { byte[] bytes = Pack.pack(CONTAINS, needle); - return addRead(src, bytes, Exp.Type.INT); + return addRead(src, bytes, Exp.Type.BOOL); } /** @@ -258,7 +258,7 @@ public static Exp contains(Exp needle, Exp src) { */ public static Exp startsWith(Exp prefix, Exp src) { byte[] bytes = Pack.pack(STARTS_WITH, prefix); - return addRead(src, bytes, Exp.Type.INT); + return addRead(src, bytes, Exp.Type.BOOL); } /** @@ -275,7 +275,7 @@ public static Exp startsWith(Exp prefix, Exp src) { */ public static Exp endsWith(Exp suffix, Exp src) { byte[] bytes = Pack.pack(ENDS_WITH, suffix); - return addRead(src, bytes, Exp.Type.INT); + return addRead(src, bytes, Exp.Type.BOOL); } /** @@ -343,7 +343,7 @@ public static Exp byteLength(Exp src) { */ public static Exp isNumeric(Exp src) { byte[] bytes = Pack.pack(IS_NUMERIC); - return addRead(src, bytes, Exp.Type.INT); + return addRead(src, bytes, Exp.Type.BOOL); } /** @@ -362,7 +362,7 @@ public static Exp isNumeric(Exp src) { */ public static Exp isNumeric(int numericType, Exp src) { byte[] bytes = Pack.pack(IS_NUMERIC, numericType); - return addRead(src, bytes, Exp.Type.INT); + return addRead(src, bytes, Exp.Type.BOOL); } /** @@ -378,7 +378,7 @@ public static Exp isNumeric(int numericType, Exp src) { */ public static Exp isUpper(Exp src) { byte[] bytes = Pack.pack(IS_UPPER); - return addRead(src, bytes, Exp.Type.INT); + return addRead(src, bytes, Exp.Type.BOOL); } /** @@ -394,7 +394,7 @@ public static Exp isUpper(Exp src) { */ public static Exp isLower(Exp src) { byte[] bytes = Pack.pack(IS_LOWER); - return addRead(src, bytes, Exp.Type.INT); + return addRead(src, bytes, Exp.Type.BOOL); } /** @@ -481,7 +481,7 @@ public static Exp b64Decode(Exp src) { */ public static Exp regexCompare(Exp pattern, Exp src) { byte[] bytes = Pack.pack(REGEX_COMPARE, pattern); - return addRead(src, bytes, Exp.Type.INT); + return addRead(src, bytes, Exp.Type.BOOL); } /** @@ -502,7 +502,7 @@ public static Exp regexCompare(Exp pattern, Exp src) { */ public static Exp regexCompare(Exp pattern, int regexFlags, Exp src) { byte[] bytes = Pack.pack(REGEX_COMPARE, pattern, regexFlags); - return addRead(src, bytes, Exp.Type.INT); + return addRead(src, bytes, Exp.Type.BOOL); } //----------------------------------------------------------------- @@ -901,7 +901,7 @@ public static Exp regexReplace( * @return string-typed expression yielding the string representation */ public static Exp toString(Exp src) { - byte[] bytes = emptyArray(); + byte[] bytes = reprPayload(); return new Exp.Module(src, bytes, Exp.Type.STRING.code, MODULE_REPR); } @@ -917,16 +917,26 @@ private static Exp addModify(Exp src, byte[] bytes) { return new Exp.Module(src, bytes, Exp.Type.STRING.code, MODULE | Exp.MODIFY); } - // [cmd, [needle, repl], flags] — needle/replacement nested inside a 2-element list. - // Specialized packing method. Leaving in StringExp instead of moving to Pack since the - // structure is specific to string replace operations and doesn't fit the usual pattern - // of a command followed by a flat list of arguments. + // 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, int, CTX[]). private static byte[] packReplace(int command, Exp needle, Exp replacement, int flags) { Packer packer = new Packer(); for (int i = 0; i < 2; i++) { packer.packArrayBegin(3); packer.packInt(command); packer.packArrayBegin(2); + packer.packInt(QUOTED); + packer.packArrayBegin(2); needle.pack(packer); replacement.pack(packer); packer.packInt(flags); @@ -935,18 +945,19 @@ private static byte[] packReplace(int command, Exp needle, Exp replacement, int return packer.getBuffer(); } - // [REGEX_REPLACE, [pattern, repl], regexFlags] — 3 elements. - // Server's regex_replace op table accepts only [list, regexFlags]; no slot for - // policy flags (max_args=2 in particle_string.c:476). Specialized packing method - // kept in StringExp instead of moving to Pack since the structure is specific to - // string replace operations and doesn't fit the usual pattern of a command - // followed by a flat list of arguments. + // [REGEX_REPLACE, [QUOTED, [pattern, repl]], regexFlags] — same QUOTED wrapping as + // packReplace; without it the expression compiler tries to interpret the + // (pattern, replacement) pair as a function call. Note: the server's regex_replace + // op table is declared with max_args=2 (particle_string.c:476), so there is no + // trailing policy-flags slot — only the regexFlags integer. private static byte[] packRegexReplace(Exp pattern, Exp replacement, int regexFlags) { Packer packer = new Packer(); for (int i = 0; i < 2; i++) { packer.packArrayBegin(3); packer.packInt(REGEX_REPLACE); packer.packArrayBegin(2); + packer.packInt(QUOTED); + packer.packArrayBegin(2); pattern.pack(packer); replacement.pack(packer); packer.packInt(regexFlags); @@ -955,10 +966,17 @@ private static byte[] packRegexReplace(Exp pattern, Exp replacement, int regexFl return packer.getBuffer(); } - private static byte[] emptyArray() { + // Single-zero payload [0] for CALL_REPR (StringExp.toString). The server's + // parse_op_call at exp.c:3244 rejects an empty list (ele_count == 0), so the + // payload must contain at least one element. The CALL_REPR dispatcher at + // exp.c:5019 ignores the sub-op id and goes straight to as_bin_to_string, so + // the value carried here is unused. The spec previously documented this as `[]`; + // the server is the source of truth — see §2.7 in the cross-client spec. + private static byte[] reprPayload() { Packer packer = new Packer(); for (int i = 0; i < 2; i++) { - packer.packArrayBegin(0); + packer.packArrayBegin(1); + packer.packInt(0); if (i == 0) packer.createBuffer(); } return packer.getBuffer(); diff --git a/test/src/com/aerospike/test/sync/basic/TestStringExp.java b/test/src/com/aerospike/test/sync/basic/TestStringExp.java index dee1a5c6e..6a67ac350 100644 --- a/test/src/com/aerospike/test/sync/basic/TestStringExp.java +++ b/test/src/com/aerospike/test/sync/basic/TestStringExp.java @@ -219,10 +219,10 @@ public void splitWithAndWithoutSeparator() { Record r1 = eval(StringExp.split(Exp.val(","), Exp.stringBin(BIN))); assertEquals(Arrays.asList("one", "two", "three"), r1.getList(VAR)); - // No-separator form returns a singleton-list wrapping the whole string. - put("Hello123World"); + // 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("Hello123World"), r2.getList(VAR)); + assertEquals(Arrays.asList("a", "b", "c"), r2.getList(VAR)); } @Test @@ -246,14 +246,13 @@ public void regexCompareWithAndWithoutCaseInsensitiveFlag() { Exp.stringBin(BIN))).getBoolean(VAR)); } - @Test - public void regexCompareLiteralSourceIgnoresBin() { - // Source can be any string-yielding expression — not only a bin reference. - put("ignored"); - Record r = eval(StringExp.regexCompare( - Exp.val("[A-Z]+"), Exp.val("HELLO"))); - assertTrue(r.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) @@ -286,16 +285,14 @@ public void concatAppendsListOfValues() { } @Test - public void snipRemovesFromStartAndRange() { - put("hello world"); - // One-arg form: start through end. - Record r1 = eval(StringExp.snip(POLICY, Exp.val(5), Exp.stringBin(BIN))); - assertEquals("hello", r1.getString(VAR)); - - // Two-arg form: half-open [start, end). + 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 r2 = eval(StringExp.snip(POLICY, Exp.val(5), Exp.val(15), Exp.stringBin(BIN))); - assertEquals("hello world", r2.getString(VAR)); + Record r = eval(StringExp.snip(POLICY, Exp.val(5), Exp.val(15), Exp.stringBin(BIN))); + assertEquals("hello world", r.getString(VAR)); } @Test From e1d55a23ca6b048171159f838d885afba4c216cf Mon Sep 17 00:00:00 2001 From: Mirza Karacic Date: Thu, 21 May 2026 10:15:32 -0700 Subject: [PATCH 9/9] Added server 8.1.3 gates for string ops feature --- test/src/com/aerospike/test/sync/basic/TestOperateString.java | 2 +- test/src/com/aerospike/test/sync/basic/TestStringExp.java | 2 +- test/src/com/aerospike/test/sync/basic/TestStringMasking.java | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/test/src/com/aerospike/test/sync/basic/TestOperateString.java b/test/src/com/aerospike/test/sync/basic/TestOperateString.java index 75e9ddc70..436b4ca77 100644 --- a/test/src/com/aerospike/test/sync/basic/TestOperateString.java +++ b/test/src/com/aerospike/test/sync/basic/TestOperateString.java @@ -65,7 +65,7 @@ public class TestOperateString extends TestSync { public static void serverVersionCheck() { Assume.assumeTrue( "Skipping: string operations require server version 8.1.3 or later", - args.serverVersion.isGreaterOrEqual(8, 1, 2, 0)); + args.serverVersion.isGreaterOrEqual(8, 1, 3, 0)); } //----------------------------------------------------------------- diff --git a/test/src/com/aerospike/test/sync/basic/TestStringExp.java b/test/src/com/aerospike/test/sync/basic/TestStringExp.java index 6a67ac350..b8528b9b9 100644 --- a/test/src/com/aerospike/test/sync/basic/TestStringExp.java +++ b/test/src/com/aerospike/test/sync/basic/TestStringExp.java @@ -75,7 +75,7 @@ public class TestStringExp extends TestSync { public static void serverVersionCheck() { Assume.assumeTrue( "Skipping: string expressions require server version 8.1.3 or later", - args.serverVersion.isGreaterOrEqual(8, 1, 2, 0)); + args.serverVersion.isGreaterOrEqual(8, 1, 3, 0)); } //----------------------------------------------------------------- diff --git a/test/src/com/aerospike/test/sync/basic/TestStringMasking.java b/test/src/com/aerospike/test/sync/basic/TestStringMasking.java index 8db39c740..6405fc0eb 100644 --- a/test/src/com/aerospike/test/sync/basic/TestStringMasking.java +++ b/test/src/com/aerospike/test/sync/basic/TestStringMasking.java @@ -86,7 +86,7 @@ public class TestStringMasking extends TestSync { @BeforeClass public static void setupUsersAndRule() { Assume.assumeTrue("Skipping: server version < 8.1.3 (string ops + masking)", - args.serverVersion.isGreaterOrEqual(8, 1, 2, 0)); + 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());