KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > derby > iapi > types > XMLDataValue


1 /*
2
3    Derby - Class org.apache.derby.iapi.types.XMLDataValue
4
5    Licensed to the Apache Software Foundation (ASF) under one or more
6    contributor license agreements. See the NOTICE file distributed with
7    this work for additional information regarding copyright ownership.
8    The ASF licenses this file to you under the Apache License, Version 2.0
9    (the "License"); you may not use this file except in compliance with
10    the License. You may obtain a copy of the License at
11
12       http://www.apache.org/licenses/LICENSE-2.0
13
14    Unless required by applicable law or agreed to in writing, software
15    distributed under the License is distributed on an "AS IS" BASIS,
16    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17    See the License for the specific language governing permissions and
18    limitations under the License.
19
20  */
21
22 package org.apache.derby.iapi.types;
23
24 import org.apache.derby.iapi.error.StandardException;
25
26 public interface XMLDataValue extends DataValueDescriptor
27 {
28    /**
29      * Method to parse an XML string and, if it's valid,
30      * store the _serialized_ version locally and then return
31      * this XMLDataValue.
32      *
33      * @param text The string value to check.
34      * @param preserveWS Whether or not to preserve
35      * ignorable whitespace.
36      * @param sqlxUtil Contains SQL/XML objects and util
37      * methods that facilitate execution of XML-related
38      * operations
39      * @return If 'text' constitutes a valid XML document,
40      * it has been stored in this XML value and this XML
41      * value returned; otherwise, an exception is thrown.
42      * @exception StandardException Thrown on error.
43      */
44     public XMLDataValue XMLParse(String JavaDoc text, boolean preserveWS,
45         SqlXmlUtil sqlxUtil) throws StandardException;
46
47     /**
48      * The SQL/XML XMLSerialize operator.
49      * Serializes this XML value into a string with a user-specified
50      * character type, and returns that string via the received
51      * StringDataValue (if the received StringDataValue is non-null
52      * and of the correct type; else, a new StringDataValue is
53      * returned).
54      *
55      * @param result The result of a previous call to this method,
56      * null if not called yet.
57      * @param targetType The string type to which we want to serialize.
58      * @param targetWidth The width of the target type.
59      * @return A serialized (to string) version of this XML object,
60      * in the form of a StringDataValue object.
61      * @exception StandardException Thrown on error
62      */
63     public StringDataValue XMLSerialize(StringDataValue result,
64         int targetType, int targetWidth) throws StandardException;
65
66     /**
67      * The SQL/XML XMLExists operator.
68      * Checks to see if evaluation of the query expression contained
69      * within the received util object against this XML value returns
70      * at least one item. NOTE: For now, the query expression must be
71      * XPath only (XQuery not supported) because that's what Xalan
72      * supports.
73      *
74      * @param sqlxUtil Contains SQL/XML objects and util
75      * methods that facilitate execution of XML-related
76      * operations
77      * @return True if evaluation of the query expression stored
78      * in sqlxUtil returns at least one node for this XML value;
79      * unknown if the xml value is NULL; false otherwise.
80      * @exception StandardException Thrown on error
81      */
82     public BooleanDataValue XMLExists(SqlXmlUtil sqlxUtil)
83         throws StandardException;
84
85     /**
86      * Evaluate the XML query expression contained within the received
87      * util object against this XML value and store the results into
88      * the received XMLDataValue "result" param (assuming "result" is
89      * non-null; else create a new XMLDataValue).
90      *
91      * @param result The result of a previous call to this method; null
92      * if not called yet.
93      * @param sqlxUtil Contains SQL/XML objects and util methods that
94      * facilitate execution of XML-related operations
95      * @return An XMLDataValue whose content corresponds to the serialized
96      * version of the results from evaluation of the query expression.
97      * Note: this XMLDataValue may not be storable into Derby XML
98      * columns.
99      * @exception Exception thrown on error (and turned into a
100      * StandardException by the caller).
101      */
102     public XMLDataValue XMLQuery(XMLDataValue result, SqlXmlUtil sqlxUtil)
103         throws StandardException;
104
105     /* ****
106      * Helper classes and methods.
107      * */
108
109     /**
110      * Set this XML value's qualified type.
111      */
112     public void setXType(int xtype);
113
114     /**
115      * Retrieve this XML value's qualified type.
116      */
117     public int getXType();
118
119     /**
120      * Take note of the fact this XML value represents an XML
121      * sequence that has one or more top-level attribute nodes.
122      */
123     public void markAsHavingTopLevelAttr();
124
125     /**
126      * Return whether or not this XML value represents a sequence
127      * that has one or more top-level attribute nodes.
128      */
129     public boolean hasTopLevelAttr();
130 }
131
Popular Tags