--- /dev/null
+/*\r
+\r
+ Derby - Class org.apache.derby.iapi.types.XMLDataValue\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
+public interface XMLDataValue extends DataValueDescriptor\r
+{\r
+ /**\r
+ * Method to parse an XML string and, if it's valid,\r
+ * store the _serialized_ version locally and then return\r
+ * this XMLDataValue.\r
+ *\r
+ * @param text The string value to check.\r
+ * @param preserveWS Whether or not to preserve\r
+ * ignorable whitespace.\r
+ * @param sqlxUtil Contains SQL/XML objects and util\r
+ * methods that facilitate execution of XML-related\r
+ * operations\r
+ * @return If 'text' constitutes a valid XML document,\r
+ * it has been stored in this XML value and this XML\r
+ * value returned; otherwise, an exception is thrown. \r
+ * @exception StandardException Thrown on error.\r
+ */\r
+ public XMLDataValue XMLParse(String text, boolean preserveWS,\r
+ SqlXmlUtil sqlxUtil) throws StandardException;\r
+\r
+ /**\r
+ * The SQL/XML XMLSerialize operator.\r
+ * Serializes this XML value into a string with a user-specified\r
+ * character type, and returns that string via the received\r
+ * StringDataValue (if the received StringDataValue is non-null\r
+ * and of the correct type; else, a new StringDataValue is\r
+ * returned).\r
+ *\r
+ * @param result The result of a previous call to this method,\r
+ * null if not called yet.\r
+ * @param targetType The string type to which we want to serialize.\r
+ * @param targetWidth The width of the target type.\r
+ * @param targetCollationType The collation type of the target type.\r
+ * @return A serialized (to string) version of this XML object,\r
+ * in the form of a StringDataValue object.\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public StringDataValue XMLSerialize(StringDataValue result,\r
+ int targetType, int targetWidth, int targetCollationType) \r
+ throws StandardException;\r
+\r
+ /**\r
+ * The SQL/XML XMLExists operator.\r
+ * Checks to see if evaluation of the query expression contained\r
+ * within the received util object against this XML value returns\r
+ * at least one item. NOTE: For now, the query expression must be\r
+ * XPath only (XQuery not supported) because that's what Xalan\r
+ * supports.\r
+ *\r
+ * @param sqlxUtil Contains SQL/XML objects and util\r
+ * methods that facilitate execution of XML-related\r
+ * operations\r
+ * @return True if evaluation of the query expression stored\r
+ * in sqlxUtil returns at least one node for this XML value;\r
+ * unknown if the xml value is NULL; false otherwise.\r
+ * @exception StandardException Thrown on error\r
+ */\r
+ public BooleanDataValue XMLExists(SqlXmlUtil sqlxUtil)\r
+ throws StandardException;\r
+\r
+ /**\r
+ * Evaluate the XML query expression contained within the received\r
+ * util object against this XML value and store the results into\r
+ * the received XMLDataValue "result" param (assuming "result" is\r
+ * non-null; else create a new XMLDataValue).\r
+ *\r
+ * @param result The result of a previous call to this method; null\r
+ * if not called yet.\r
+ * @param sqlxUtil Contains SQL/XML objects and util methods that\r
+ * facilitate execution of XML-related operations\r
+ * @return An XMLDataValue whose content corresponds to the serialized\r
+ * version of the results from evaluation of the query expression.\r
+ * Note: this XMLDataValue may not be storable into Derby XML\r
+ * columns.\r
+ * @exception Exception thrown on error (and turned into a\r
+ * StandardException by the caller).\r
+ */\r
+ public XMLDataValue XMLQuery(XMLDataValue result, SqlXmlUtil sqlxUtil)\r
+ throws StandardException;\r
+\r
+ /* ****\r
+ * Helper classes and methods.\r
+ * */\r
+\r
+ /**\r
+ * Set this XML value's qualified type.\r
+ */\r
+ public void setXType(int xtype);\r
+\r
+ /**\r
+ * Retrieve this XML value's qualified type.\r
+ */\r
+ public int getXType();\r
+\r
+ /**\r
+ * Take note of the fact this XML value represents an XML\r
+ * sequence that has one or more top-level attribute nodes.\r
+ */\r
+ public void markAsHavingTopLevelAttr();\r
+\r
+ /**\r
+ * Return whether or not this XML value represents a sequence\r
+ * that has one or more top-level attribute nodes.\r
+ */\r
+ public boolean hasTopLevelAttr();\r
+}\r