Note
This class is only compiled with JDK 1.4 and higher since the XML-related classes that it uses (JAXP and Xalan) are not part of earlier JDKs. Having a separate class for this functionality is beneficial for two reasons: 1. Allows us to allocate XML objects and compile an XML query expression a single time per statement, instead of having to do it for every row against which the query is evaluated. An instance of this class is created at compile time and then passed to the appropriate operator implementation method in XML.java. 2. By keeping all XML-specific references in this one class, we have a single "point of entry" to the XML objects--namely, the constructor for this class. Thus, if we always make sure to check for the required XML classes _before_ calling this class's constructor, we can detect early on whether some classes (ex. Xalan) are missing, and can throw a friendly error up front, instead of a ClassNotFoundException somewhere deeper in the execution codepath. The initial check for the required XML classes can be found in XML.checkXMLRequirements(). Note that we don't want to put references to XML-specific objects directly into XML.java because that class (XML.java) is instantiated anytime a table with an XML column is referenced. That would mean that if a user tried to select a non-XML column (ex. integer) from a table that had at least one XML column in it, the user would have to have JAXP and Xalan classes in his/her classpath--which we don't want. Instead, by keeping all XML-specific objects in this one class, and then only instantiating this class when an XML operator is used (either implicitly or explicitly), we make it so that the user is only required to have XML-specific classes in his/her classpath _if_ s/he is trying to access or operate on XML values.
| Modifier and Type | Class and Description |
|---|---|
| private static class | SqlXmlUtil.
A NamespaceContext that reports all namespaces as unbound. |
| private class |
| Modifier and Type | Field and Description |
|---|---|
| private DocumentBuilder | |
| private XPathExpression | query
The compiled XPath query. |
| private QName | returnType
The return type of the XPath query. |
| private Transformer |
| Access | Constructor and Description |
|---|---|
| public |
| Modifier and Type | Method and Description |
|---|---|
| public void | compileXQExpr(String
The XPath expression to compile queryExpr, String opName)Take the received string, which is an XML query expression, compile it, and store the compiled query locally. |
| private Object | |
| protected List | Returns: If returnResults is false then return an empty ArrayList if evaluation returned at least one item and return null otherwise. If returnResults is true then return an array list containing all of the result items and return the qualified XML type via the resultXType parameter.The XML value against which to evaluate
the stored (compiled) query expression xmlContext, boolean Whether or not to return the actual
results of the query returnResults, int[] The qualified XML type of the result
of evaluating the expression, if returnResults is true.
If the result is a sequence of exactly one Document node
then this will be XML(DOCUMENT(ANY)); else it will be
XML(SEQUENCE). If returnResults is false, this value
is ignored. resultXType)Evaluate this object's compiled XML query expression against the received xmlContext. |
| private void | loadSerializer()
Create an instance of Xalan serializer for the sake of serializing an XML value according the SQL/XML specification for serialization. |
| protected String | Returns: A properly serialized version of xmlAsText.String version of XML on which to perform
serialization. xmlAsText)Take a string representing an XML value and serialize it according SQL/XML serialization rules. |
| protected String | Returns: Single string holding the serialized version of the normalized sequence created from the items in the received list.List of items to serialize. It should either be
a list of a single string value (in case it's the result of
an XMLQUERY operation that returns an atomic value), or a list
of zero or more Node objects. items, XMLDataValue XMLDataValue into which the serialized string
returned by this method is ultimately going to be stored.
This is used for keeping track of XML values that represent
sequences having top-level (parentless) attribute nodes. xmlVal)Take an array list (sequence) of XML nodes and/or string values and serialize that entire list according to SQL/XML serialization rules, which ultimately point to XML serialization rules as defined by w3c. |
| dBuilder | back to summary |
|---|---|
| private DocumentBuilder dBuilder | |
| query | back to summary |
|---|---|
| private XPathExpression query The compiled XPath query. | |
| returnType | back to summary |
|---|---|
| private QName returnType The return type of the XPath query. | |
| serializer | back to summary |
|---|---|
| private Transformer serializer | |
| SqlXmlUtil | back to summary |
|---|---|
| public SqlXmlUtil() throws StandardException Constructor: Initializes objects required for parsing and serializing XML values. Since most XML operations that require XML-specific classes perform both parsing and serialization at some point, we just initialize the objects up front. | |
| compileXQExpr | back to summary |
|---|---|
| public void compileXQExpr(String queryExpr, String opName) throws StandardException Take the received string, which is an XML query expression, compile it, and store the compiled query locally. Note that for now, we only support XPath because that's what Xalan supports.
| |
| evaluate | back to summary |
|---|---|
| private Object evaluate(Document doc) throws XPathExpressionException Evaluate the XPath query on the specified document. | |
| evalXQExpression | back to summary |
|---|---|
| protected List Evaluate this object's compiled XML query expression against the received xmlContext. Then if returnResults is false, return an empty sequence (ArrayList) if evaluation yields at least one item and return null if evaluation yields zero items (the caller can then just check for null to see if the query returned any items). If returnResults is true, then return return a sequence (ArrayList) containing all items returned from evaluation of the expression. This array list can contain any combination of atomic values and XML nodes; it may also be empty. Assumption here is that the query expression has already been compiled and is stored in this.query.
| |
| loadSerializer | back to summary |
|---|---|
| private void loadSerializer() throws TransformerConfigurationException Create an instance of Xalan serializer for the sake of serializing an XML value according the SQL/XML specification for serialization. | |
| serializeToString | back to summary |
|---|---|
| protected String serializeToString(String xmlAsText) throws Exception Take a string representing an XML value and serialize it according SQL/XML serialization rules. Right now, we perform this serialization by first parsing the string into a JAXP Document object, and then applying the serialization semantics to that Document. That seems a bit inefficient, but neither Xalan nor JAXP provides a more direct way to do this. | |
| serializeToString | back to summary |
|---|---|
| protected String serializeToString(List<E> items, XMLDataValue xmlVal) throws TransformerException Take an array list (sequence) of XML nodes and/or string values and serialize that entire list according to SQL/XML serialization rules, which ultimately point to XML serialization rules as defined by w3c. As part of that serialization process we have to first "normalize" the sequence. We do that by iterating through the list and performing the steps for "sequence normalization" as defined here: http://www.w3.org/TR/xslt-xquery-serialization/#serdm This method primarily focuses on taking the steps for normalization; for the rest of the serialization work, we just make calls on the DOMSerializer class provided by Xalan.
| |
| Modifier and Type | Field and Description |
|---|---|
| private static final SqlXmlUtil. |
| Access | Constructor and Description |
|---|---|
| private |
| Modifier and Type | Method and Description |
|---|---|
| public String | getNamespaceURI(String
prefix to look up prefix)Implements javax. Get Namespace URI bound to a prefix in the current scope. |
| public String | getPrefix(String
URI of Namespace to lookup namespaceURI)Implements javax. Get prefix bound to Namespace URI in the current scope. |
| public Iterator | getPrefixes(String
URI of Namespace to lookup namespaceURI)Implements javax. Get all prefixes bound to a Namespace URI in the current scope. |
| SINGLETON | back to summary |
|---|---|
| private static final SqlXmlUtil. | |
| NullNamespaceContext | back to summary |
|---|---|
| private NullNamespaceContext() | |
| getNamespaceURI | back to summary | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| public String getNamespaceURI(String prefix) Implements javax. Doc from javax. Get Namespace URI bound to a prefix in the current scope. When requesting a Namespace URI by prefix, the following table describes the returned Namespace URI value for all possible prefix values:
| |||||||||||||||
| getPrefix | back to summary | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| public String getPrefix(String namespaceURI) Implements javax. Doc from javax. Get prefix bound to Namespace URI in the current scope. To get all prefixes bound to a Namespace URI in the current
scope, use When requesting a prefix by Namespace URI, the following table describes the returned prefix value for all Namespace URI values:
| |||||||||||||||
| getPrefixes | back to summary | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| public Iterator Implements javax. Doc from javax. Get all prefixes bound to a Namespace URI in the current scope. An Iterator over String elements is returned in an arbitrary, implementation dependent, order. The When requesting prefixes by Namespace URI, the following table describes the returned prefixes value for all Namespace URI values:
| |||||||||||||
| Access | Constructor and Description |
|---|---|
| private |
| Modifier and Type | Method and Description |
|---|---|
| public void | error(SAXParseException
The error information encapsulated in a
SAX parse exception. exception)Implements org. Receive notification of a recoverable error. |
| public void | fatalError(SAXParseException
The error information encapsulated in a
exception)SAXParseException.Implements org. Receive notification of a non-recoverable, fatal error. |
| public void | warning(SAXParseException
The warning information encapsulated in a
SAX parse exception. exception)Implements org. Receive notification of a warning. |
| XMLErrorHandler | back to summary |
|---|---|
| private XMLErrorHandler() | |
| error | back to summary |
|---|---|
| public void error(SAXParseException exception) throws SAXException Implements org. Doc from org. Receive notification of a recoverable error. This corresponds to the definition of "error" in section 1.2 of the W3C XML 1.0 Recommendation. For example, a validating parser would use this callback to report the violation of a validity constraint. The default behaviour is to take no action. The SAX parser must continue to provide normal parsing events after invoking this method: it should still be possible for the application to process the document through to the end. If the application cannot do so, then the parser should report a fatal error even if the XML recommendation does not require it to do so. Filters may use this method to report other, non-XML errors as well.
| |
| fatalError | back to summary |
|---|---|
| public void fatalError(SAXParseException exception) throws SAXException Implements org. Doc from org. Receive notification of a non-recoverable, fatal error. As defined in section 1.2 of the W3C XML 1.0 Recommendation, fatal errors are those that would make it impossible for a parser to continue normal processing. These include violation of a well-formedness constraint, invalid encoding, and forbidden structural errors as described in the W3C XML 1.0 Recommendation.
| |
| warning | back to summary |
|---|---|
| public void warning(SAXParseException exception) throws SAXException Implements org. Doc from org. Receive notification of a warning. SAX parsers will use this method to report conditions that are not errors or fatal errors as defined by the XML recommendation. The default behaviour is to take no action. The SAX parser must continue to provide normal parsing events after invoking this method: it should still be possible for the application to process the document through to the end. Filters may use this method to report other, non-XML warnings as well.
| |