--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.types.StringDataValue\r
+\r
+ Licensed to the Apache Software Foundation (ASF) under one or more\r
+ contributor license agreements. See the NOTICE file distributed with\r
+ this work for additional information regarding copyright ownership.\r
+ The ASF licenses this file to you under the Apache License, Version 2.0\r
+ (the "License"); you may not use this file except in compliance with\r
+ the License. You may obtain a copy of the License at\r
+\r
+ http://www.apache.org/licenses/LICENSE-2.0\r
+\r
+ Unless required by applicable law or agreed to in writing, software\r
+ distributed under the License is distributed on an "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
+ See the License for the specific language governing permissions and\r
+ limitations under the License.\r
+\r
+ */\r
+\r
+package org.apache.derby.iapi.types;\r
+\r
+import org.apache.derby.iapi.error.StandardException;\r
+\r
+import java.text.RuleBasedCollator;\r
+\r
+public interface StringDataValue extends ConcatableDataValue\r
+{\r
+ // TRIM() types\r
+ public static final int BOTH = 0;\r
+ public static final int TRAILING = 1;\r
+ public static final int LEADING = 2;\r
+\r
+ /**\r
+ For a character string type, the collation derivation should always be \r
+ "explicit"(not possible in Derby 10.3), "implicit" or "none". We will \r
+ start by setting it to "implicit" in TypeDescriptorImpl. At runtime, only \r
+ character string types which are results of aggregate methods dealing \r
+ with operands with different collation types should have a collation \r
+ derivation of "none". All the other character string types should have \r
+ their collation derivation set to "implicit". \r
+ */\r
+ public static final int COLLATION_DERIVATION_NONE = 0;\r
+ /** @see StringDataValue#COLLATION_DERIVATION_NONE */\r
+ public static final int COLLATION_DERIVATION_IMPLICIT = 1;\r
+ /** @see StringDataValue#COLLATION_DERIVATION_NONE */\r
+ public static final int COLLATION_DERIVATION_EXPLICIT = 2;\r
+ /**\r
+ * In Derby 10.3, it is possible to have database with one of the following\r
+ * two configurations\r
+ * 1)all the character columns will have a collation type of UCS_BASIC. \r
+ * This is same as what we do in Derby 10.2 release. \r
+ * 2)all the character string columns belonging to system tables will have \r
+ * collation type of UCS_BASIC but all the character string columns \r
+ * belonging to user tables will have collation type of TERRITORY_BASED.\r
+ * \r
+ * Data types will start with collation type defaulting to UCS_BASIC in\r
+ * TypeDescriptorImpl. This collation type ofcourse makes sense fpr \r
+ * character string types only. It will be ignored for the rest of the\r
+ * types. If a character's collation type should be TERRITORY_BASED, then\r
+ * DTD.setCollationType can be called to change the default of UCS_BASIC.\r
+ */\r
+ public static final int COLLATION_TYPE_UCS_BASIC = 0;\r
+ /** @see StringDataValue#COLLATION_TYPE_UCS_BASIC */\r
+ public static final int COLLATION_TYPE_TERRITORY_BASED = 1;\r
+\r
+ /**\r
+ * The SQL concatenation '||' operator.\r
+ *\r
+ * @param leftOperand String on the left hand side of '||'\r
+ * @param rightOperand String on the right hand side of '||'\r
+ * @param result The result of a previous call to this method,\r
+ * null if not called yet.\r
+ *\r
+ * @return A ConcatableDataValue containing the result of the '||'\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public StringDataValue concatenate(\r
+ StringDataValue leftOperand,\r
+ StringDataValue rightOperand,\r
+ StringDataValue result)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * The SQL like() function with out escape clause.\r
+ *\r
+ * @param pattern the pattern to use\r
+ *\r
+ * @return A BooleanDataValue containing the result of the like\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public BooleanDataValue like(DataValueDescriptor pattern)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * The SQL like() function WITH escape clause.\r
+ *\r
+ * @param pattern the pattern to use\r
+ * @param escape the escape character\r
+ *\r
+ * @return A BooleanDataValue containing the result of the like\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public BooleanDataValue like(DataValueDescriptor pattern,\r
+ DataValueDescriptor escape)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * The SQL trim(), ltrim() and rtrim() functions.\r
+ *\r
+ * @param trimType Type of trim\r
+ * @param result The result of a previous call to this method,\r
+ * null if not called yet.\r
+ *\r
+ * @return A StringDataValue containing the result of the trim()\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public StringDataValue trim(\r
+ int trimType,\r
+ StringDataValue result)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * The SQL Ansi trim function.\r
+\r
+ * @param trimType type of trim. Possible values are {@link #LEADING}, {@link #TRAILING}\r
+ * or {@link #BOTH}.\r
+ * @param trimChar The character to trim from <em>this</em>\r
+ * @param result The result of a previous call to this method,\r
+ * null if not called yet.\r
+ * @return A StringDataValue containing the result of the trim().\r
+ * @throws StandardException\r
+ */\r
+ public StringDataValue ansiTrim(\r
+ int trimType,\r
+ StringDataValue trimChar,\r
+ StringDataValue result)\r
+ throws StandardException;\r
+\r
+ /** \r
+ * Convert the string to upper case.\r
+ *\r
+ * @param result The result (reusable - allocate if null).\r
+ * \r
+ * @return The string converted to upper case.\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public StringDataValue upper(StringDataValue result)\r
+ throws StandardException;\r
+\r
+ /** \r
+ * Convert the string to lower case.\r
+ *\r
+ * @param result The result (reusable - allocate if null).\r
+ * \r
+ * @return The string converted to lower case.\r
+ *\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public StringDataValue lower(StringDataValue result)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Position in searchFrom of the first occurrence of this.value.\r
+ * The search begins from position start. 0 is returned if searchFrom does\r
+ * not contain this.value. Position 1 is the first character in searchFrom.\r
+ *\r
+ * @param searchFrom - The string to search from\r
+ * @param start - The position to search from in string searchFrom\r
+ * @param result - The object to return\r
+ *\r
+ * @return The position in searchFrom the fist occurrence of this.value.\r
+ * 0 is returned if searchFrom does not contain this.value.\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public NumberDataValue locate( StringDataValue searchFrom, \r
+ NumberDataValue start,\r
+ NumberDataValue result)\r
+ throws StandardException;\r
+\r
+\r
+ /**\r
+ * Get a char array. Typically, this is a simple\r
+ * getter that is cheaper than getString() because\r
+ * we always need to create a char array when\r
+ * doing I/O. Use this instead of getString() where\r
+ * reasonable.\r
+ * <p>\r
+ * <b>WARNING</b>: may return a character array that has spare\r
+ * characters at the end. MUST be used in conjunction\r
+ * with getLength() to be safe.\r
+ * \r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public char[] getCharArray() throws StandardException;\r
+\r
+ /**\r
+ * Gets either SQLChar/SQLVarchar/SQLLongvarchar/SQLClob(base classes) or \r
+ * CollatorSQLChar/CollatorSQLVarchar/CollatorSQLLongvarch/CollatorSQLClob\r
+ * (subclasses). Whether this method returns the base class or the subclass \r
+ * depends on the value of the RuleBasedCollator. If RuleBasedCollator is \r
+ * null, then the object returned would be baseclass otherwise it would be \r
+ * subcalss.\r
+ */\r
+ public StringDataValue getValue(RuleBasedCollator collatorForComparison);\r
+}\r