001: /*
002:
003: Derby - Class org.apache.derby.iapi.types.XMLDataValue
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.types;
023:
024: import org.apache.derby.iapi.error.StandardException;
025:
026: public interface XMLDataValue extends DataValueDescriptor {
027: /**
028: * Method to parse an XML string and, if it's valid,
029: * store the _serialized_ version locally and then return
030: * this XMLDataValue.
031: *
032: * @param text The string value to check.
033: * @param preserveWS Whether or not to preserve
034: * ignorable whitespace.
035: * @param sqlxUtil Contains SQL/XML objects and util
036: * methods that facilitate execution of XML-related
037: * operations
038: * @return If 'text' constitutes a valid XML document,
039: * it has been stored in this XML value and this XML
040: * value returned; otherwise, an exception is thrown.
041: * @exception StandardException Thrown on error.
042: */
043: public XMLDataValue XMLParse(String text, boolean preserveWS,
044: SqlXmlUtil sqlxUtil) throws StandardException;
045:
046: /**
047: * The SQL/XML XMLSerialize operator.
048: * Serializes this XML value into a string with a user-specified
049: * character type, and returns that string via the received
050: * StringDataValue (if the received StringDataValue is non-null
051: * and of the correct type; else, a new StringDataValue is
052: * returned).
053: *
054: * @param result The result of a previous call to this method,
055: * null if not called yet.
056: * @param targetType The string type to which we want to serialize.
057: * @param targetWidth The width of the target type.
058: * @return A serialized (to string) version of this XML object,
059: * in the form of a StringDataValue object.
060: * @exception StandardException Thrown on error
061: */
062: public StringDataValue XMLSerialize(StringDataValue result,
063: int targetType, int targetWidth) throws StandardException;
064:
065: /**
066: * The SQL/XML XMLExists operator.
067: * Checks to see if evaluation of the query expression contained
068: * within the received util object against this XML value returns
069: * at least one item. NOTE: For now, the query expression must be
070: * XPath only (XQuery not supported) because that's what Xalan
071: * supports.
072: *
073: * @param sqlxUtil Contains SQL/XML objects and util
074: * methods that facilitate execution of XML-related
075: * operations
076: * @return True if evaluation of the query expression stored
077: * in sqlxUtil returns at least one node for this XML value;
078: * unknown if the xml value is NULL; false otherwise.
079: * @exception StandardException Thrown on error
080: */
081: public BooleanDataValue XMLExists(SqlXmlUtil sqlxUtil)
082: throws StandardException;
083:
084: /**
085: * Evaluate the XML query expression contained within the received
086: * util object against this XML value and store the results into
087: * the received XMLDataValue "result" param (assuming "result" is
088: * non-null; else create a new XMLDataValue).
089: *
090: * @param result The result of a previous call to this method; null
091: * if not called yet.
092: * @param sqlxUtil Contains SQL/XML objects and util methods that
093: * facilitate execution of XML-related operations
094: * @return An XMLDataValue whose content corresponds to the serialized
095: * version of the results from evaluation of the query expression.
096: * Note: this XMLDataValue may not be storable into Derby XML
097: * columns.
098: * @exception Exception thrown on error (and turned into a
099: * StandardException by the caller).
100: */
101: public XMLDataValue XMLQuery(XMLDataValue result,
102: SqlXmlUtil sqlxUtil) throws StandardException;
103:
104: /* ****
105: * Helper classes and methods.
106: * */
107:
108: /**
109: * Set this XML value's qualified type.
110: */
111: public void setXType(int xtype);
112:
113: /**
114: * Retrieve this XML value's qualified type.
115: */
116: public int getXType();
117:
118: /**
119: * Take note of the fact this XML value represents an XML
120: * sequence that has one or more top-level attribute nodes.
121: */
122: public void markAsHavingTopLevelAttr();
123:
124: /**
125: * Return whether or not this XML value represents a sequence
126: * that has one or more top-level attribute nodes.
127: */
128: public boolean hasTopLevelAttr();
129: }
|