/* Copyright (c) 2001-2019, The HSQL Development Group
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice, this
 * list of conditions and the following disclaimer.
 *
 * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 *
 * Neither the name of the HSQL Development Group nor the names of its
 * contributors may be used to endorse or promote products derived from this
 * software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL HSQL DEVELOPMENT GROUP, HSQLDB.ORG,
 * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */


package org.hsqldb.jdbc;

import java.io.ByteArrayInputStream;
import java.io.ByteArrayOutputStream;
import java.io.CharArrayReader;
import java.io.Closeable;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.io.OutputStreamWriter;
import java.io.Reader;
import java.io.StringReader;
import java.io.Writer;
import java.lang.reflect.Constructor;
import java.lang.reflect.InvocationTargetException;
import java.nio.charset.Charset;
import java.sql.SQLException;
import java.sql.SQLFeatureNotSupportedException;
import java.sql.SQLXML;
import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ArrayBlockingQueue;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;
import java.util.zip.GZIPInputStream;
import java.util.zip.GZIPOutputStream;

import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.DocumentBuilderFactory;
import javax.xml.parsers.FactoryConfigurationError;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.stream.XMLEventReader;
import javax.xml.stream.XMLInputFactory;
import javax.xml.stream.XMLOutputFactory;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamWriter;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import javax.xml.transform.Transformer;
import javax.xml.transform.TransformerConfigurationException;
import javax.xml.transform.TransformerException;
import javax.xml.transform.TransformerFactory;
import javax.xml.transform.TransformerFactoryConfigurationError;
import javax.xml.transform.dom.DOMResult;
import javax.xml.transform.dom.DOMSource;
import javax.xml.transform.sax.SAXResult;
import javax.xml.transform.sax.SAXSource;
import javax.xml.transform.stax.StAXResult;
import javax.xml.transform.stax.StAXSource;
import javax.xml.transform.stream.StreamResult;
import javax.xml.transform.stream.StreamSource;

import org.hsqldb.error.ErrorCode;
import org.hsqldb.lib.ClosableByteArrayOutputStream;
import org.hsqldb.lib.StringConverter;
import org.w3c.dom.DOMException;
import org.w3c.dom.DOMImplementation;
import org.w3c.dom.Document;
import org.w3c.dom.DocumentType;
import org.w3c.dom.Element;
import org.w3c.dom.EntityReference;
import org.w3c.dom.Node;
import org.w3c.dom.ProcessingInstruction;
import org.w3c.dom.Text;
import org.w3c.dom.bootstrap.DOMImplementationRegistry;
import org.xml.sax.Attributes;
import org.xml.sax.ContentHandler;
import org.xml.sax.InputSource;
import org.xml.sax.Locator;
import org.xml.sax.SAXException;

/* $Id: JDBCSQLXML.java 5968 2019-04-27 12:55:27Z fredt $ */


The mapping in the JavaTM programming language for the SQL XML type.
XML is a built-in type that stores an XML value
as a column value in a row of a database table.
By default drivers implement an SQLXML object as
a logical pointer to the XML data
rather than the data itself.
An SQLXML object is valid for the duration of the transaction in which it was created.

The SQLXML interface provides methods for accessing the XML value
as a String, a Reader or Writer, or as a Stream.  The XML value
may also be accessed through a Source or set as a Result, which
are used with XML Parser APIs such as DOM, SAX, and StAX, as
well as with XSLT transforms and XPath evaluations.

Methods in the interfaces ResultSet, CallableStatement, and PreparedStatement,
such as getSQLXML allow a programmer to access an XML value.
In addition, this interface has methods for updating an XML value.

The XML value of the SQLXML instance may be obtained as a BinaryStream using
  SQLXML sqlxml = resultSet.getSQLXML(column);
  InputStream binaryStream = sqlxml.getBinaryStream();

For example, to parse an XML value with a DOM parser:
  DocumentBuilder parser = DocumentBuilderFactory.newInstance().newDocumentBuilder();
  Document result = parser.parse(binaryStream);

or to parse an XML value with a SAX parser to your handler:
  SAXParser parser = SAXParserFactory.newInstance().newSAXParser();
  parser.parse(binaryStream, myHandler);

or to parse an XML value with a StAX parser:
  XMLInputFactory factory = XMLInputFactory.newInstance();
  XMLStreamReader streamReader = factory.createXMLStreamReader(binaryStream);


Because databases may use an optimized representation for the XML,
accessing the value through getSource() and
setResult() can lead to improved processing performance
without serializing to a stream representation and parsing the XML.

For example, to obtain a DOM Document Node:
  DOMSource domSource = sqlxml.getSource(DOMSource.class);
  Document document = (Document) domSource.getNode();

or to set the value to a DOM Document Node to myNode:
  DOMResult domResult = sqlxml.setResult(DOMResult.class);
  domResult.setNode(myNode);

or, to send SAX events to your handler:
  SAXSource saxSource = sqlxml.getSource(SAXSource.class);
  XMLReader xmlReader = saxSource.getXMLReader();
  xmlReader.setContentHandler(myHandler);
  xmlReader.parse(saxSource.getInputSource());

or, to set the result value from SAX events:
  SAXResult saxResult = sqlxml.setResult(SAXResult.class);
  ContentHandler contentHandler = saxResult.getXMLReader().getContentHandler();
  contentHandler.startDocument();
  // set the XML elements and attributes into the result
  contentHandler.endDocument();

or, to obtain StAX events:
  StAXSource staxSource = sqlxml.getSource(StAXSource.class);
  XMLStreamReader streamReader = staxSource.getXMLStreamReader();

or, to set the result value from StAX events:
  StAXResult staxResult = sqlxml.getResult(StAXResult.class);
  XMLStreamWriter streamWriter = staxResult.getXMLStreamWriter();

or, to perform XSLT transformations on the XML value using the XSLT in xsltFile
output to file resultFile:
  File xsltFile = new File("a.xslt");
  File myFile = new File("result.xml");
  Transformer xslt = TransformerFactory.newInstance().newTransformer(new StreamSource(xsltFile));
  Source source = sqlxml.getSource(null);
  Result result = new StreamResult(myFile);
  xslt.transform(source, result);

or, to evaluate an XPath expression on the XML value:
  XPath xpath = XPathFactory.newInstance().newXPath();
  DOMSource domSource = sqlxml.getSource(DOMSource.class);
  Document document = (Document) domSource.getNode();
  String expression = "/foo/@bar";
  String barValue = xpath.evaluate(expression, document);

To set the XML value to be the result of an XSLT transform:
  File sourceFile = new File("source.xml");
  Transformer xslt = TransformerFactory.newInstance().newTransformer(new StreamSource(xsltFile));
  Source streamSource = new StreamSource(sourceFile);
  Result result = sqlxml.setResult(null);
  xslt.transform(streamSource, result);

Any Source can be transformed to a Result using the identity transform
specified by calling newTransformer():
  Transformer identity = TransformerFactory.newInstance().newTransformer();
  Source source = sqlxml.getSource(null);
  File myFile = new File("result.xml");
  Result result = new StreamResult(myFile);
  identity.transform(source, result);

To write the contents of a Source to standard output:
  Transformer identity = TransformerFactory.newInstance().newTransformer();
  Source source = sqlxml.getSource(null);
  Result result = new StreamResult(System.out);
  identity.transform(source, result);

To create a DOMSource from a DOMResult:
   DOMSource domSource = new DOMSource(domResult.getNode());


Incomplete or invalid XML values may cause an SQLException when
set or the exception may occur when execute() occurs.  All streams
must be closed before execute() occurs or an SQLException will be thrown.

Reading and writing XML values to or from an SQLXML object can happen at most once.
The conceptual states of readable and not readable determine if one
of the reading APIs will return a value or throw an exception.
The conceptual states of writable and not writable determine if one
of the writing APIs will set a value or throw an exception.

The state moves from readable to not readable once free() or any of the
reading APIs are called: getBinaryStream(), getCharacterStream(), getSource(), and getString().
Implementations may also change the state to not writable when this occurs.

The state moves from writable to not writeable once free() or any of the
writing APIs are called: setBinaryStream(), setCharacterStream(), setResult(), and setString().
Implementations may also change the state to not readable when this occurs.

All methods on the SQLXML interface must be fully implemented if the
JDBC driver supports the data type.



HSQLDB-Specific Information:
 

Starting with HSQLDB 2.0, a rudimentary client-side SQLXML interface
implementation (this class) is supported for local use when the product is
built and run under JDK 1.6+ and the SQLXML instance is constructed as the
result of calling JDBCConnection.createSQLXML(). 

SQLXML instances retrieved in such a fashion are initially write-only, with
the lifecycle of read and write availability constrained in accordance with
the documentation of the interface methods. 

When build and run under JDK 1.6+, it is also possible to retrieve read-only
SQLXML instances from JDBCResultSet.getSQLXML(...), given that the underlying
data can be converted to an XML Document Object Model (DOM). 

However, at the time of this writing (2007-06-12) it is not yet possible to
store SQLXML objects directly into an HSQLDB database or to use them directly
for HSQLDB statement parameterization purposes.  This is because the SQLXML
data type is not yet natively supported by the HSQLDB engine. Instead, a
JDBCSQLXML instance must first be read as a string, binary input stream,
character input stream and so on, which can then be used for such purposes. 

Here is the current read/write availability lifecycle for JDBCSQLXML:

    

        

            

                Origin
            
            

                Initially
            
            

                After 1st Write
            
            

                After 1st Read
            
            

                After 1st Free
            
        
    
    

        

            

                org.hsqldb.jdbc.JDBCConnection.createSQLXML()
            
            

                Write-only
            
            

                Read-only
            
            

                Not readable or writable
            
            

                Not readable or writable
            
        
        

            

                org.hsqldb.jdbc.JDBCResultSet.getSQLXML(...)
            
            

                Read-only
            
            

                N/A
            
            

                Not readable or writable
            
            

                Not readable or writable
            
        
    



Author:
Campbell Burnet (campbell-burnet@users dot sourceforge.net)
See Also:
parsers
stream
transform
xpath
Since:
JDK 1.6, HSQLDB 2.0/**
 * <!-- start generic documentation -->
 * The mapping in the JavaTM programming language for the SQL XML type.
 * XML is a built-in type that stores an XML value
 * as a column value in a row of a database table.
 * By default drivers implement an SQLXML object as
 * a logical pointer to the XML data
 * rather than the data itself.
 * An SQLXML object is valid for the duration of the transaction in which it was created.
 * <p>
 * The SQLXML interface provides methods for accessing the XML value
 * as a String, a Reader or Writer, or as a Stream.  The XML value
 * may also be accessed through a Source or set as a Result, which
 * are used with XML Parser APIs such as DOM, SAX, and StAX, as
 * well as with XSLT transforms and XPath evaluations.
 * <p>
 * Methods in the interfaces ResultSet, CallableStatement, and PreparedStatement,
 * such as getSQLXML allow a programmer to access an XML value.
 * In addition, this interface has methods for updating an XML value.
 * <p>
 * The XML value of the SQLXML instance may be obtained as a BinaryStream using
 * <pre>
 *   SQLXML sqlxml = resultSet.getSQLXML(column);
 *   InputStream binaryStream = sqlxml.getBinaryStream();
 * </pre>
 * For example, to parse an XML value with a DOM parser:
 * <pre>
 *   DocumentBuilder parser = DocumentBuilderFactory.newInstance().newDocumentBuilder();
 *   Document result = parser.parse(binaryStream);
 * </pre>
 * or to parse an XML value with a SAX parser to your handler:
 * <pre>
 *   SAXParser parser = SAXParserFactory.newInstance().newSAXParser();
 *   parser.parse(binaryStream, myHandler);
 * </pre>
 * or to parse an XML value with a StAX parser:
 * <pre>
 *   XMLInputFactory factory = XMLInputFactory.newInstance();
 *   XMLStreamReader streamReader = factory.createXMLStreamReader(binaryStream);
 * </pre>
 * <p>
 * Because databases may use an optimized representation for the XML,
 * accessing the value through getSource() and
 * setResult() can lead to improved processing performance
 * without serializing to a stream representation and parsing the XML.
 * <p>
 * For example, to obtain a DOM Document Node:
 * <pre>
 *   DOMSource domSource = sqlxml.getSource(DOMSource.class);
 *   Document document = (Document) domSource.getNode();
 * </pre>
 * or to set the value to a DOM Document Node to myNode:
 * <pre>
 *   DOMResult domResult = sqlxml.setResult(DOMResult.class);
 *   domResult.setNode(myNode);
 * </pre>
 * or, to send SAX events to your handler:
 * <pre>
 *   SAXSource saxSource = sqlxml.getSource(SAXSource.class);
 *   XMLReader xmlReader = saxSource.getXMLReader();
 *   xmlReader.setContentHandler(myHandler);
 *   xmlReader.parse(saxSource.getInputSource());
 * </pre>
 * or, to set the result value from SAX events:
 * <pre>
 *   SAXResult saxResult = sqlxml.setResult(SAXResult.class);
 *   ContentHandler contentHandler = saxResult.getXMLReader().getContentHandler();
 *   contentHandler.startDocument();
 *   // set the XML elements and attributes into the result
 *   contentHandler.endDocument();
 * </pre>
 * or, to obtain StAX events:
 * <pre>
 *   StAXSource staxSource = sqlxml.getSource(StAXSource.class);
 *   XMLStreamReader streamReader = staxSource.getXMLStreamReader();
 * </pre>
 * or, to set the result value from StAX events:
 * <pre>
 *   StAXResult staxResult = sqlxml.getResult(StAXResult.class);
 *   XMLStreamWriter streamWriter = staxResult.getXMLStreamWriter();
 * </pre>
 * or, to perform XSLT transformations on the XML value using the XSLT in xsltFile
 * output to file resultFile:
 * <pre>
 *   File xsltFile = new File("a.xslt");
 *   File myFile = new File("result.xml");
 *   Transformer xslt = TransformerFactory.newInstance().newTransformer(new StreamSource(xsltFile));
 *   Source source = sqlxml.getSource(null);
 *   Result result = new StreamResult(myFile);
 *   xslt.transform(source, result);
 * </pre>
 * or, to evaluate an XPath expression on the XML value:
 * <pre>
 *   XPath xpath = XPathFactory.newInstance().newXPath();
 *   DOMSource domSource = sqlxml.getSource(DOMSource.class);
 *   Document document = (Document) domSource.getNode();
 *   String expression = "/foo/@bar";
 *   String barValue = xpath.evaluate(expression, document);
 * </pre>
 * To set the XML value to be the result of an XSLT transform:
 * <pre>
 *   File sourceFile = new File("source.xml");
 *   Transformer xslt = TransformerFactory.newInstance().newTransformer(new StreamSource(xsltFile));
 *   Source streamSource = new StreamSource(sourceFile);
 *   Result result = sqlxml.setResult(null);
 *   xslt.transform(streamSource, result);
 * </pre>
 * Any Source can be transformed to a Result using the identity transform
 * specified by calling newTransformer():
 * <pre>
 *   Transformer identity = TransformerFactory.newInstance().newTransformer();
 *   Source source = sqlxml.getSource(null);
 *   File myFile = new File("result.xml");
 *   Result result = new StreamResult(myFile);
 *   identity.transform(source, result);
 * </pre>
 * To write the contents of a Source to standard output:
 * <pre>
 *   Transformer identity = TransformerFactory.newInstance().newTransformer();
 *   Source source = sqlxml.getSource(null);
 *   Result result = new StreamResult(System.out);
 *   identity.transform(source, result);
 * </pre>
 * To create a DOMSource from a DOMResult:
 * <pre>
 *    DOMSource domSource = new DOMSource(domResult.getNode());
 * </pre>
 * <p>
 * Incomplete or invalid XML values may cause an SQLException when
 * set or the exception may occur when execute() occurs.  All streams
 * must be closed before execute() occurs or an SQLException will be thrown.
 * <p>
 * Reading and writing XML values to or from an SQLXML object can happen at most once.
 * The conceptual states of readable and not readable determine if one
 * of the reading APIs will return a value or throw an exception.
 * The conceptual states of writable and not writable determine if one
 * of the writing APIs will set a value or throw an exception.
 * <p>
 * The state moves from readable to not readable once free() or any of the
 * reading APIs are called: getBinaryStream(), getCharacterStream(), getSource(), and getString().
 * Implementations may also change the state to not writable when this occurs.
 * <p>
 * The state moves from writable to not writeable once free() or any of the
 * writing APIs are called: setBinaryStream(), setCharacterStream(), setResult(), and setString().
 * Implementations may also change the state to not readable when this occurs.
 * <p>
 * All methods on the <code>SQLXML</code> interface must be fully implemented if the
 * JDBC driver supports the data type.
 * <!-- end generic documentation -->
 *
 * <!-- start release-specific documentation -->
 * <div class="ReleaseSpecificDocumentation">
 * <h3>HSQLDB-Specific Information:</h3> <p>
 *
 * Starting with HSQLDB 2.0, a rudimentary client-side SQLXML interface
 * implementation (this class) is supported for local use when the product is
 * built and run under JDK 1.6+ and the SQLXML instance is constructed as the
 * result of calling JDBCConnection.createSQLXML(). <p>
 *
 * SQLXML instances retrieved in such a fashion are initially write-only, with
 * the lifecycle of read and write availability constrained in accordance with
 * the documentation of the interface methods. <p>
 *
 * When build and run under JDK 1.6+, it is also possible to retrieve read-only
 * SQLXML instances from JDBCResultSet.getSQLXML(...), given that the underlying
 * data can be converted to an XML Document Object Model (DOM). <p>
 *
 * However, at the time of this writing (2007-06-12) it is not yet possible to
 * store SQLXML objects directly into an HSQLDB database or to use them directly
 * for HSQLDB statement parameterization purposes.  This is because the SQLXML
 * data type is not yet natively supported by the HSQLDB engine. Instead, a
 * JDBCSQLXML instance must first be read as a string, binary input stream,
 * character input stream and so on, which can then be used for such purposes. <p>
 *
 * Here is the current read/write availability lifecycle for JDBCSQLXML:
 *
 * <TABLE summary="">
 *     <THEAD valign="bottom">
 *         <TR align="center">
 *             <TH>
 *                 Origin
 *             </TH>
 *             <TH>
 *                 Initially
 *             </TH>
 *             <TH>
 *                 After 1<SUP>st</SUP> Write
 *             </TH>
 *             <TH>
 *                 After 1<SUP>st</SUP> Read
 *             </TH>
 *             <TH>
 *                 After 1<SUP>st</SUP> Free
 *             </TH>
 *         </TR>
 *     </THEAD>
 *     <TBODY>
 *         <TR >
 *             <TH>
 *                 <tt>org.hsqldb.jdbc.JDBCConnection.createSQLXML()</tt>
 *             </TH>
 *             <TD >
 *                 Write-only
 *             </TD>
 *             <TD>
 *                 Read-only
 *             </TD>
 *             <TD>
 *                 Not readable or writable
 *             </TD>
 *             <TD>
 *                 Not readable or writable
 *             </TD>
 *         </TR>
 *         <TR>
 *             <TH>
 *                 <tt>org.hsqldb.jdbc.JDBCResultSet.getSQLXML(...)</tt>
 *             </TH>
 *             <TD >
 *                 Read-only
 *             </TD>
 *             <TD>
 *                 N/A
 *             </TD>
 *             <TD>
 *                 Not readable or writable
 *             </TD>
 *             <TD>
 *                 Not readable or writable
 *             </TD>
 *         </TR>
 *     </TBODY>
 * </TABLE>
 * </div>
 * <!-- end release-specific documentation -->
 *
 * @author Campbell Burnet (campbell-burnet@users dot sourceforge.net)
 * @see javax.xml.parsers
 * @see javax.xml.stream
 * @see javax.xml.transform
 * @see javax.xml.xpath
 * @since JDK 1.6, HSQLDB 2.0
 */
public class JDBCSQLXML implements SQLXML {

    private static String domFeatures = "XML 3.0 Traversal +Events 2.0";
    private static DOMImplementation         domImplementation;
    private static DOMImplementationRegistry domImplementationRegistry;
    private static ThreadPoolExecutor        executorService;
    private static Transformer               identityTransformer;
    private static TransformerFactory        transformerFactory;

    
Precomputed Charset to reduce octet to character sequence conversion
charset lookup overhead.
/**
     * Precomputed Charset to reduce octet to character sequence conversion
     * charset lookup overhead.
     */
    private static final Charset                utf8Charset;
    private static ArrayBlockingQueue<Runnable> workQueue;

    static {
        Charset charset = null;

        try {
            charset = Charset.forName("UTF8");
        } catch (Exception e) {
        }
        utf8Charset = charset;
    }

    
When non-null, the SAX ContentHandler currently in use to build this
object's SQLXML value from a SAX event sequence.
/**
     * When non-null, the SAX ContentHandler currently in use to build this
     * object's SQLXML value from a SAX event sequence.
     */
    private SAX2DOMBuilder builder;

    
Whether this object is closed.  When closed, no further reading
or writing is possible.
/**
     * Whether this object is closed.  When closed, no further reading
     * or writing is possible.
     */
    private boolean closed;

    // ------------------------- Internal Implementation -----------------------

    
This object's SQLXML value as a GZIPed byte array
/**
     * This object's SQLXML value as a GZIPed byte array
     */
    private volatile byte[] gzdata;

    
When non-null, the stream currently in use to read this object's
SQLXML value as an octet sequence.
/**
     * When non-null, the stream currently in use to read this object's
     * SQLXML value as an octet sequence.
     */
    private InputStream inputStream;

    
When non-null, the stream currently in use to write this object's
SQLXML value from an octet sequence.
/**
     * When non-null, the stream currently in use to write this object's
     * SQLXML value from an octet sequence.
     */
    private ClosableByteArrayOutputStream outputStream;

    
When non-null, the DOMResult currently in use to build this object's
SQLXML value.
/**
     * When non-null, the DOMResult currently in use to build this object's
     * SQLXML value.
     */
    private DOMResult domResult;

    
This object's public id
/**
     * This object's public id
     */
    private String publicId;

    
Whether it is possible to read this object's SQLXML value.
/**
     * Whether it is possible to read this object's SQLXML value.
     */
    private boolean readable;

    
This object's system id
/**
     * This object's system id
     */
    private String systemId;

    
Whether it is possible to write this object's SQLXML value.
/**
     * Whether it is possible to write this object's SQLXML value.
     */
    private boolean writable;

    
Constructs a new, initially write-only JDBCSQLXML object. 

/**
     * Constructs a new, initially write-only JDBCSQLXML object. <p>
     */
    protected JDBCSQLXML() {
        setReadable(false);
        setWritable(true);
    }

    
Constructs a new read-only JDBCSQLXML object from the given octet
sequence. 

Params:
bytes – the octet sequence representing the SQLXML value
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given octet
     * sequence. <p>
     *
     * @param bytes the octet sequence representing the SQLXML value
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(byte[] bytes) throws SQLException {
        this(bytes, null);
    }

    
Constructs a new read-only JDBCSQLXML object from the given character
sequence. 

Params:
chars – the character sequence representing the SQLXML value
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given character
     * sequence. <p>
     *
     * @param chars the character sequence representing the SQLXML value
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(char[] chars) throws SQLException {
        this(chars, 0, chars.length, null);
    }

    
Constructs a new JDBCSQLXML object from the given Document. 

Params:
document – the Document representing the SQLXML value
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new JDBCSQLXML object from the given Document. <p>
     *
     * @param document the Document representing the SQLXML value
     * @throws java.sql.SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(Document document) throws SQLException {
        this(new DOMSource(document));
    }

    
Constructs a new read-only JDBCSQLXML object from the given octet
sequence. 

Relative URI references will be resolved against the present working
directory reported by the Java virtual machine. 

Params:
inputStream – an octet stream representing an SQLXML value
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given octet
     * sequence. <p>
     *
     * Relative URI references will be resolved against the present working
     * directory reported by the Java virtual machine. <p>
     *
     * @param inputStream an octet stream representing an SQLXML value
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(InputStream inputStream) throws SQLException {
        this(inputStream, null);
    }

    
Constructs a new read-only JDBCSQLXML object from the given character
sequence. 

Relative URI references will be resolved against the present working
directory reported by the Java virtual machine. 

Note:Normally, a byte stream should be used rather than a reader,
so that the XML parser can resolve character encoding specified by the
XML declaration. However, in many cases the encoding of the input stream
is already resolved, as in the case of reading XML from a StringReader.
Params:
reader – a character stream representing an SQLXML value
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given character
     * sequence. <p>
     *
     * Relative URI references will be resolved against the present working
     * directory reported by the Java virtual machine. <p>
     *
     * <b>Note:</b>Normally, a byte stream should be used rather than a reader,
     * so that the XML parser can resolve character encoding specified by the
     * XML declaration. However, in many cases the encoding of the input stream
     * is already resolved, as in the case of reading XML from a StringReader.
     *
     * @param reader a character stream representing an SQLXML value
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(Reader reader) throws SQLException {
        this(reader, null);
    }

    
Constructs a new read-only JDBCSQLXML object from the given Source
object. 

Params:
source – a Source representing an SQLXML value
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given Source
     * object. <p>
     *
     * @param source a Source representing an SQLXML value
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    public JDBCSQLXML(Source source) throws SQLException {
        init(source);
    }

    
Constructs a new read-only JDBCSQLXML object from the given character
sequence. 

Relative URI references will be resolved against the present working
directory reported by the Java virtual machine. 

Params:
string – a character sequence representing an SQLXML value
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given character
     * sequence. <p>
     *
     * Relative URI references will be resolved against the present working
     * directory reported by the Java virtual machine. <p>
     *
     * @param string a character sequence representing an SQLXML value
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(String string) throws SQLException {
        this(new StreamSource(new StringReader(string)));
    }

    
Constructs a new read-only JDBCSQLXML object from the given octet
sequence. 

Params:
bytes – the octet sequence representing the SQLXML value
systemId – must be a String that conforms to the URI syntax;
       allows relative URIs to be processed.
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given octet
     * sequence. <p>
     *
     * @param bytes the octet sequence representing the SQLXML value
     * @param systemId must be a String that conforms to the URI syntax;
     *        allows relative URIs to be processed.
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(byte[] bytes, String systemId) throws SQLException {
        this(new StreamSource(new ByteArrayInputStream(bytes), systemId));
    }

    protected JDBCSQLXML(char[] chars, String systemId) throws SQLException {
        this(chars, 0, chars.length, systemId);
    }

    
Constructs a new read-only JDBCSQLXML object from the given octet
sequence. 

Relative URI references will be resolved against the given systemId. 

Params:
inputStream – an octet stream representing an SQLXML value
systemId – a String that conforms to the URI syntax, indicating
     the URI from which the XML data is being read, so that relative URI
     references can be resolved
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given octet
     * sequence. <p>
     *
     * Relative URI references will be resolved against the given systemId. <p>
     *
     * @param inputStream an octet stream representing an SQLXML value
     * @param systemId a String that conforms to the URI syntax, indicating
     *      the URI from which the XML data is being read, so that relative URI
     *      references can be resolved
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(InputStream inputStream,
                         String systemId) throws SQLException {
        this(new StreamSource(inputStream, systemId));
    }

    
Constructs a new read-only JDBCSQLXML object from the given character
sequence. 

Relative URI references will be resolved against the given systemId. 

Note:Normally, a byte stream should be used rather than a reader,
so that the XML parser can resolve character encoding specified by the
XML declaration. However, in many cases the encoding of the input stream
is already resolved, as in the case of reading XML from a StringReader.
Params:
reader – a character stream representing an SQLXML value;
systemId – a String that conforms to the URI syntax, indicating
     the URI from which the XML data is being read, so that relative URI
     references can be resolved
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given character
     * sequence. <p>
     *
     * Relative URI references will be resolved against the given systemId. <p>
     *
     * <b>Note:</b>Normally, a byte stream should be used rather than a reader,
     * so that the XML parser can resolve character encoding specified by the
     * XML declaration. However, in many cases the encoding of the input stream
     * is already resolved, as in the case of reading XML from a StringReader.
     *
     * @param reader a character stream representing an SQLXML value;
     * @param systemId a String that conforms to the URI syntax, indicating
     *      the URI from which the XML data is being read, so that relative URI
     *      references can be resolved
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(Reader reader, String systemId) throws SQLException {
        this(new StreamSource(reader, systemId));
    }

    
Constructs a new read-only JDBCSQLXML object from the given character
sequence. 

Relative URI references will be resolved against the given systemId. 

Params:
string – a character sequence representing an SQLXML value
systemId – a String that conforms to the URI syntax, indicating
     the URI from which the XML data is being read, so that relative URI
     references can be resolved
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given character
     * sequence. <p>
     *
     * Relative URI references will be resolved against the given systemId. <p>
     *
     * @param string a character sequence representing an SQLXML value
     * @param systemId a String that conforms to the URI syntax, indicating
     *      the URI from which the XML data is being read, so that relative URI
     *      references can be resolved
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(String string, String systemId) throws SQLException {
        this(new StreamSource(new StringReader(string), systemId));
    }

    
Constructs a new read-only JDBCSQLXML object from the given gzipped octet
sequence. 

Params:
bytes – the gzipped octet sequence representing the SQLXML value
clone – whether to clone the given gzipped octet sequence
systemId – 
publicId – 
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Constructs a new read-only JDBCSQLXML object from the given gzipped octet
     * sequence. <p>
     *
     * @param bytes the gzipped octet sequence representing the SQLXML value
     * @param clone whether to clone the given gzipped octet sequence
     * @param systemId
     * @param publicId
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected JDBCSQLXML(byte[] bytes, boolean clone, String systemId,
                         String publicId) throws SQLException {

        this.setGZipData(clone ? bytes.clone()
                               : bytes);

        this.systemId = systemId;
        this.publicId = publicId;
    }

    protected JDBCSQLXML(char[] chars, int offset, int length,
                         String systemId) throws SQLException {
        this(new StreamSource(new CharArrayReader(chars, offset, length),
                              systemId));
    }

    
This method closes this object and releases the resources that it held.
The SQL XML object becomes invalid and neither readable or writable
when this method is called.
After free has been called, any attempt to invoke a
method other than free will result in a SQLException
being thrown.  If free is called multiple times, the subsequent
calls to free are treated as a no-op.
Throws:
SQLException – if there is an error freeing the XML value.
SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Since:
JDK 1.6/**
     * This method closes this object and releases the resources that it held.
     * The SQL XML object becomes invalid and neither readable or writable
     * when this method is called.
     *
     * After <code>free</code> has been called, any attempt to invoke a
     * method other than <code>free</code> will result in a <code>SQLException</code>
     * being thrown.  If <code>free</code> is called multiple times, the subsequent
     * calls to <code>free</code> are treated as a no-op.
     * @throws SQLException if there is an error freeing the XML value.
     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
     * this method
     * @since JDK 1.6
     */
    public void free() throws SQLException {
        close();
    }

    
Retrieves the XML value designated by this SQLXML instance as a stream.
The bytes of the input stream are interpreted according to appendix F of the XML 1.0 specification.
The behavior of this method is the same as ResultSet.getBinaryStream()
when the designated column of the ResultSet has a type java.sql.Types of SQLXML.

The SQL XML object becomes not readable when this method is called and
may also become not writable depending on implementation.
Throws:
SQLException – if there is an error processing the XML value.
  An exception is thrown if the state is not readable.
SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Returns:
a stream containing the XML data.
Since:
JDK 1.6/**
     * Retrieves the XML value designated by this SQLXML instance as a stream.
     * The bytes of the input stream are interpreted according to appendix F of the XML 1.0 specification.
     * The behavior of this method is the same as ResultSet.getBinaryStream()
     * when the designated column of the ResultSet has a type java.sql.Types of SQLXML.
     * <p>
     * The SQL XML object becomes not readable when this method is called and
     * may also become not writable depending on implementation.
     *
     * @return a stream containing the XML data.
     * @throws SQLException if there is an error processing the XML value.
     *   An exception is thrown if the state is not readable.
     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
     * this method
     * @since JDK 1.6
     */
    public synchronized InputStream getBinaryStream() throws SQLException {

        checkClosed();
        checkReadable();

        InputStream rval = getBinaryStreamImpl();

        setReadable(false);
        setWritable(false);

        return rval;
    }

    
Retrieves a stream that can be used to write the XML value that this SQLXML instance represents.
The stream begins at position 0.
The bytes of the stream are interpreted according to appendix F of the XML 1.0 specification
The behavior of this method is the same as ResultSet.updateBinaryStream()
when the designated column of the ResultSet has a type java.sql.Types of SQLXML.

The SQL XML object becomes not writeable when this method is called and
may also become not readable depending on implementation.
Throws:
SQLException – if there is an error processing the XML value.
  An exception is thrown if the state is not writable.
SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Returns:
a stream to which data can be written.
Since:
JDK 1.6/**
     * Retrieves a stream that can be used to write the XML value that this SQLXML instance represents.
     * The stream begins at position 0.
     * The bytes of the stream are interpreted according to appendix F of the XML 1.0 specification
     * The behavior of this method is the same as ResultSet.updateBinaryStream()
     * when the designated column of the ResultSet has a type java.sql.Types of SQLXML.
     * <p>
     * The SQL XML object becomes not writeable when this method is called and
     * may also become not readable depending on implementation.
     *
     * @return a stream to which data can be written.
     * @throws SQLException if there is an error processing the XML value.
     *   An exception is thrown if the state is not writable.
     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
     * this method
     * @since JDK 1.6
     */
    public synchronized OutputStream setBinaryStream() throws SQLException {

        checkClosed();
        checkWritable();

        OutputStream rval = setBinaryStreamImpl();

        setWritable(false);
        setReadable(true);

        return rval;
    }

    
Retrieves the XML value designated by this SQLXML instance as a java.io.Reader object.
The format of this stream is defined by org.xml.sax.InputSource,
where the characters in the stream represent the unicode code points for
XML according to section 2 and appendix B of the XML 1.0 specification.
Although an encoding declaration other than unicode may be present,
the encoding of the stream is unicode.
The behavior of this method is the same as ResultSet.getCharacterStream()
when the designated column of the ResultSet has a type java.sql.Types of SQLXML.

The SQL XML object becomes not readable when this method is called and
may also become not writable depending on implementation.
Throws:
SQLException – if there is an error processing the XML value.
  The getCause() method of the exception may provide a more detailed exception, for example,
  if the stream does not contain valid characters.
  An exception is thrown if the state is not readable.
SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Returns:
a stream containing the XML data.
Since:
JDK 1.6/**
     * Retrieves the XML value designated by this SQLXML instance as a java.io.Reader object.
     * The format of this stream is defined by org.xml.sax.InputSource,
     * where the characters in the stream represent the unicode code points for
     * XML according to section 2 and appendix B of the XML 1.0 specification.
     * Although an encoding declaration other than unicode may be present,
     * the encoding of the stream is unicode.
     * The behavior of this method is the same as ResultSet.getCharacterStream()
     * when the designated column of the ResultSet has a type java.sql.Types of SQLXML.
     * <p>
     * The SQL XML object becomes not readable when this method is called and
     * may also become not writable depending on implementation.
     *
     * @return a stream containing the XML data.
     * @throws SQLException if there is an error processing the XML value.
     *   The getCause() method of the exception may provide a more detailed exception, for example,
     *   if the stream does not contain valid characters.
     *   An exception is thrown if the state is not readable.
     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
     * this method
     * @since JDK 1.6
     */
    public synchronized Reader getCharacterStream() throws SQLException {

        checkClosed();
        checkReadable();

        Reader reader = getCharacterStreamImpl();

        setReadable(false);
        setWritable(false);

        return reader;
    }

    
Retrieves a stream to be used to write the XML value that this SQLXML instance represents.
The format of this stream is defined by org.xml.sax.InputSource,
where the characters in the stream represent the unicode code points for
XML according to section 2 and appendix B of the XML 1.0 specification.
Although an encoding declaration other than unicode may be present,
the encoding of the stream is unicode.
The behavior of this method is the same as ResultSet.updateCharacterStream()
when the designated column of the ResultSet has a type java.sql.Types of SQLXML.

The SQL XML object becomes not writable when this method is called and
may also become not readable depending on implementation.
Throws:
SQLException – if there is an error processing the XML value.
  The getCause() method of the exception may provide a more detailed exception, for example,
  if the stream does not contain valid characters.
  An exception is thrown if the state is not writable.
SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Returns:
a stream to which data can be written.
Since:
JDK 1.6 Build 79/**
     * Retrieves a stream to be used to write the XML value that this SQLXML instance represents.
     * The format of this stream is defined by org.xml.sax.InputSource,
     * where the characters in the stream represent the unicode code points for
     * XML according to section 2 and appendix B of the XML 1.0 specification.
     * Although an encoding declaration other than unicode may be present,
     * the encoding of the stream is unicode.
     * The behavior of this method is the same as ResultSet.updateCharacterStream()
     * when the designated column of the ResultSet has a type java.sql.Types of SQLXML.
     * <p>
     * The SQL XML object becomes not writable when this method is called and
     * may also become not readable depending on implementation.
     *
     * @return a stream to which data can be written.
     * @throws SQLException if there is an error processing the XML value.
     *   The getCause() method of the exception may provide a more detailed exception, for example,
     *   if the stream does not contain valid characters.
     *   An exception is thrown if the state is not writable.
     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
     * this method
     * @since JDK 1.6 Build 79
     */
    public synchronized Writer setCharacterStream() throws SQLException {

        checkClosed();
        checkWritable();

        Writer writer = setCharacterStreamImpl();

        setReadable(true);
        setWritable(false);

        return writer;
    }

    
Returns a string representation of the XML value designated by this SQLXML instance.
The format of this String is defined by org.xml.sax.InputSource,
where the characters in the stream represent the unicode code points for
XML according to section 2 and appendix B of the XML 1.0 specification.
Although an encoding declaration other than unicode may be present,
the encoding of the String is unicode.
The behavior of this method is the same as ResultSet.getString()
when the designated column of the ResultSet has a type java.sql.Types of SQLXML.

The SQL XML object becomes not readable when this method is called and
may also become not writable depending on implementation.
Throws:
SQLException – if there is an error processing the XML value.
  The getCause() method of the exception may provide a more detailed exception, for example,
  if the stream does not contain valid characters.
  An exception is thrown if the state is not readable.
SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Returns:
a string representation of the XML value designated by this SQLXML instance.
Since:
JDK 1.6/**
     * Returns a string representation of the XML value designated by this SQLXML instance.
     * The format of this String is defined by org.xml.sax.InputSource,
     * where the characters in the stream represent the unicode code points for
     * XML according to section 2 and appendix B of the XML 1.0 specification.
     * Although an encoding declaration other than unicode may be present,
     * the encoding of the String is unicode.
     * The behavior of this method is the same as ResultSet.getString()
     * when the designated column of the ResultSet has a type java.sql.Types of SQLXML.
     * <p>
     * The SQL XML object becomes not readable when this method is called and
     * may also become not writable depending on implementation.
     *
     * @return a string representation of the XML value designated by this SQLXML instance.
     * @throws SQLException if there is an error processing the XML value.
     *   The getCause() method of the exception may provide a more detailed exception, for example,
     *   if the stream does not contain valid characters.
     *   An exception is thrown if the state is not readable.
     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
     * this method
     * @since JDK 1.6
     */
    public synchronized String getString() throws SQLException {

        checkClosed();
        checkReadable();

        String value = getStringImpl();

        setReadable(false);
        setWritable(false);

        return value;
    }

    
Sets the XML value designated by this SQLXML instance to the given String representation.
The format of this String is defined by org.xml.sax.InputSource,
where the characters in the stream represent the unicode code points for
XML according to section 2 and appendix B of the XML 1.0 specification.
Although an encoding declaration other than unicode may be present,
the encoding of the String is unicode.
The behavior of this method is the same as ResultSet.updateString()
when the designated column of the ResultSet has a type java.sql.Types of SQLXML.

The SQL XML object becomes not writeable when this method is called and
may also become not readable depending on implementation.
Params:
value – the XML value
Throws:
SQLException – if there is an error processing the XML value.
  The getCause() method of the exception may provide a more detailed exception, for example,
  if the stream does not contain valid characters.
  An exception is thrown if the state is not writable.
SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Since:
JDK 1.6/**
     * Sets the XML value designated by this SQLXML instance to the given String representation.
     * The format of this String is defined by org.xml.sax.InputSource,
     * where the characters in the stream represent the unicode code points for
     * XML according to section 2 and appendix B of the XML 1.0 specification.
     * Although an encoding declaration other than unicode may be present,
     * the encoding of the String is unicode.
     * The behavior of this method is the same as ResultSet.updateString()
     * when the designated column of the ResultSet has a type java.sql.Types of SQLXML.
     * <p>
     * The SQL XML object becomes not writeable when this method is called and
     * may also become not readable depending on implementation.
     *
     * @param value the XML value
     * @throws SQLException if there is an error processing the XML value.
     *   The getCause() method of the exception may provide a more detailed exception, for example,
     *   if the stream does not contain valid characters.
     *   An exception is thrown if the state is not writable.
     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
     * this method
     * @since JDK 1.6
     */
    public synchronized void setString(String value) throws SQLException {

        if (value == null) {
            throw JDBCUtil.nullArgument("value");
        }
        checkWritable();
        setStringImpl(value);
        setReadable(true);
        setWritable(false);
    }

    
Returns a Source for reading the XML value designated by this SQLXML instance.
Sources are used as inputs to XML parsers and XSLT transformers.

Sources for XML parsers will have namespace processing on by default.
The systemID of the Source is implementation dependent.

The SQL XML object becomes not readable when this method is called and
may also become not writable depending on implementation.

Note that SAX is a callback architecture, so a returned
SAXSource should then be set with a content handler that will
receive the SAX events from parsing.  The content handler
will receive callbacks based on the contents of the XML.
  SAXSource saxSource = sqlxml.getSource(SAXSource.class);
  XMLReader xmlReader = saxSource.getXMLReader();
  xmlReader.setContentHandler(myHandler);
  xmlReader.parse(saxSource.getInputSource());

Params:
sourceClass – The class of the source, or null.
If the class is null, a vendor specific Source implementation will be returned.
The following classes are supported at a minimum:
  javax.xml.transform.dom.DOMSource - returns a DOMSource
  javax.xml.transform.sax.SAXSource - returns a SAXSource
  javax.xml.transform.stax.StAXSource - returns a StAXSource
  javax.xml.transform.stream.StreamSource - returns a StreamSource
Throws:
SQLException – if there is an error processing the XML value
  or if this feature is not supported.
  The getCause() method of the exception may provide a more detailed exception, for example,
  if an XML parser exception occurs.
  An exception is thrown if the state is not readable.
SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Returns:
a Source for reading the XML value.
Since:
JDK 1.6 Build 79/**
     * Returns a Source for reading the XML value designated by this SQLXML instance.
     * Sources are used as inputs to XML parsers and XSLT transformers.
     * <p>
     * Sources for XML parsers will have namespace processing on by default.
     * The systemID of the Source is implementation dependent.
     * <p>
     * The SQL XML object becomes not readable when this method is called and
     * may also become not writable depending on implementation.
     * <p>
     * Note that SAX is a callback architecture, so a returned
     * SAXSource should then be set with a content handler that will
     * receive the SAX events from parsing.  The content handler
     * will receive callbacks based on the contents of the XML.
     * <pre>
     *   SAXSource saxSource = sqlxml.getSource(SAXSource.class);
     *   XMLReader xmlReader = saxSource.getXMLReader();
     *   xmlReader.setContentHandler(myHandler);
     *   xmlReader.parse(saxSource.getInputSource());
     * </pre>
     *
     * @param sourceClass The class of the source, or null.
     * If the class is null, a vendor specific Source implementation will be returned.
     * The following classes are supported at a minimum:
     * <pre>
     *   javax.xml.transform.dom.DOMSource - returns a DOMSource
     *   javax.xml.transform.sax.SAXSource - returns a SAXSource
     *   javax.xml.transform.stax.StAXSource - returns a StAXSource
     *   javax.xml.transform.stream.StreamSource - returns a StreamSource
     * </pre>
     * @return a Source for reading the XML value.
     * @throws SQLException if there is an error processing the XML value
     *   or if this feature is not supported.
     *   The getCause() method of the exception may provide a more detailed exception, for example,
     *   if an XML parser exception occurs.
     *   An exception is thrown if the state is not readable.
     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
     * this method
     * @since JDK 1.6 Build 79
     */
    @SuppressWarnings("unchecked")
    public synchronized <T extends Source>T getSource(
            Class<T> sourceClass) throws SQLException {

        checkClosed();
        checkReadable();

        final Source source = getSourceImpl(sourceClass);

        setReadable(false);
        setWritable(false);

        return (T) source;
    }

    
Returns a Result for setting the XML value designated by this SQLXML instance.

The systemID of the Result is implementation dependent.

The SQL XML object becomes not writable when this method is called and
may also become not readable depending on implementation.

Note that SAX is a callback architecture and the returned
SAXResult has a content handler assigned that will receive the
SAX events based on the contents of the XML.  Call the content
handler with the contents of the XML document to assign the values.
  SAXResult saxResult = sqlxml.getResult(SAXResult.class);
  ContentHandler contentHandler = saxResult.getXMLReader().getContentHandler();
  contentHandler.startDocument();
  // set the XML elements and attributes into the result
  contentHandler.endDocument();

Params:
resultClass – The class of the result, or null.
If resultClass is null, a vendor specific Result implementation will be returned.
The following classes are supported at a minimum:
  javax.xml.transform.dom.DOMResult - returns a DOMResult
  javax.xml.transform.sax.SAXResult - returns a SAXResult
  javax.xml.transform.stax.StAXResult - returns a StAXResult
  javax.xml.transform.stream.StreamResult - returns a StreamResult
Throws:
SQLException – if there is an error processing the XML value
  or if this feature is not supported.
  The getCause() method of the exception may provide a more detailed exception, for example,
  if an XML parser exception occurs.
  An exception is thrown if the state is not writable.
SQLFeatureNotSupportedException – if the JDBC driver does not support
this method
Returns:
Returns a Result for setting the XML value.
Since:
JDK 1.6 Build 79/**
     * Returns a Result for setting the XML value designated by this SQLXML instance.
     * <p>
     * The systemID of the Result is implementation dependent.
     * <p>
     * The SQL XML object becomes not writable when this method is called and
     * may also become not readable depending on implementation.
     * <p>
     * Note that SAX is a callback architecture and the returned
     * SAXResult has a content handler assigned that will receive the
     * SAX events based on the contents of the XML.  Call the content
     * handler with the contents of the XML document to assign the values.
     * <pre>
     *   SAXResult saxResult = sqlxml.getResult(SAXResult.class);
     *   ContentHandler contentHandler = saxResult.getXMLReader().getContentHandler();
     *   contentHandler.startDocument();
     *   // set the XML elements and attributes into the result
     *   contentHandler.endDocument();
     * </pre>
     *
     * @param resultClass The class of the result, or null.
     * If resultClass is null, a vendor specific Result implementation will be returned.
     * The following classes are supported at a minimum:
     * <pre>
     *   javax.xml.transform.dom.DOMResult - returns a DOMResult
     *   javax.xml.transform.sax.SAXResult - returns a SAXResult
     *   javax.xml.transform.stax.StAXResult - returns a StAXResult
     *   javax.xml.transform.stream.StreamResult - returns a StreamResult
     * </pre>
     * @return Returns a Result for setting the XML value.
     * @throws SQLException if there is an error processing the XML value
     *   or if this feature is not supported.
     *   The getCause() method of the exception may provide a more detailed exception, for example,
     *   if an XML parser exception occurs.
     *   An exception is thrown if the state is not writable.
     * @exception SQLFeatureNotSupportedException if the JDBC driver does not support
     * this method
     * @since JDK 1.6 Build 79
     */
    public synchronized <T extends Result>T setResult(
            Class<T> resultClass) throws SQLException {

        checkClosed();
        checkWritable();

        final T result = createResult(resultClass);

        setReadable(true);
        setWritable(false);

        return result;
    }

    
Returns:
that may be used to perform processing asynchronously./**
     * @return that may be used to perform processing asynchronously.
     */
    protected static ExecutorService getExecutorService() {

        if (JDBCSQLXML.executorService == null) {
            int      corePoolSize    = 1;
            int      maximumPoolSize = 10;
            long     keepAliveTime   = 1;
            TimeUnit unit            = TimeUnit.SECONDS;

            JDBCSQLXML.workQueue = new ArrayBlockingQueue<Runnable>(10);
            JDBCSQLXML.executorService = new ThreadPoolExecutor(corePoolSize,
                    maximumPoolSize, keepAliveTime, unit, workQueue);
        }

        return executorService;
    }

    
Throws:
SQLException – when unable to obtain a factory instance.
Returns:
with which to obtain xml transformer instances./**
     * @return with which to obtain xml transformer instances.
     * @throws java.sql.SQLException when unable to obtain a factory instance.
     */
    protected static TransformerFactory getTransformerFactory() throws SQLException {

        if (JDBCSQLXML.transformerFactory == null) {
            try {
                JDBCSQLXML.transformerFactory =
                    TransformerFactory.newInstance();
            } catch (TransformerFactoryConfigurationError ex) {
                throw Exceptions.transformFailed(ex);
            }
        }

        return JDBCSQLXML.transformerFactory;
    }

    
Throws:
SQLException – when unable to obtain the instance.
Returns:
used to perform identity transforms/**
     * @return used to perform identity transforms
     * @throws java.sql.SQLException when unable to obtain the instance.
     */
    protected static Transformer getIdentityTransformer() throws SQLException {

        if (JDBCSQLXML.identityTransformer == null) {
            try {
                JDBCSQLXML.identityTransformer =
                    getTransformerFactory().newTransformer();
            } catch (TransformerConfigurationException ex) {
                throw Exceptions.transformFailed(ex);
            }
        }

        return JDBCSQLXML.identityTransformer;
    }

    
Throws:
SQLException – when unable to obtain a factory instance.
Returns:
with which to construct DOM implementation instances./**
     * @return with which to construct DOM implementation instances.
     * @throws java.sql.SQLException when unable to obtain a factory instance.
     */
    protected static DOMImplementationRegistry getDOMImplementationRegistry() throws SQLException {

        if (domImplementationRegistry == null) {
            try {
                domImplementationRegistry =
                    DOMImplementationRegistry.newInstance();
            } catch (ClassCastException ex) {
                throw Exceptions.domInstantiation(ex);
            } catch (InstantiationException ex) {
                throw Exceptions.domInstantiation(ex);
            } catch (ClassNotFoundException ex) {
                throw Exceptions.domInstantiation(ex);
            } catch (IllegalAccessException ex) {
                throw Exceptions.domInstantiation(ex);
            }
        }

        return domImplementationRegistry;
    }

    
Throws:
SQLException – when unable to obtain the DOM
        implementation instance.
Returns:
with which to create document instances./**
     * @return with which to create document instances.
     * @throws java.sql.SQLException when unable to obtain the DOM
     *         implementation instance.
     */
    protected static DOMImplementation getDOMImplementation() throws SQLException {

        if (domImplementation == null) {
            domImplementation =
                getDOMImplementationRegistry().getDOMImplementation(
                    domFeatures);
        }

        if (domImplementation == null) {
            Exception ex = new RuntimeException("Not supported: "
                + domFeatures);

            throw Exceptions.domInstantiation(ex);
        }

        return domImplementation;
    }

    
Params:
namespaceURI – of the document element to create or null.
qualifiedName – of the document element to be created or null.
docType – of document to be created or null.
  When doctype is not null, its
  Node.ownerDocument attribute is set to the document
  being created.
Throws:
SQLException – wrapping any internal exception that occurs.
See Also:
DOMImplementation.createDocument(String, String, DocumentType)
Returns:
with its document element.
  If the NamespaceURI, qualifiedName, and
  doctype are null, the returned
  Document is empty with no document element./**
     * @param namespaceURI of the document element to create or <code>null</code>.
     * @param qualifiedName of the document element to be created or <code>null</code>.
     * @param docType of document to be created or <code>null</code>.
     *   When <code>doctype</code> is not <code>null</code>, its
     *   <code>Node.ownerDocument</code> attribute is set to the document
     *   being created.
     * @return with its document element.
     *   If the <code>NamespaceURI</code>, <code>qualifiedName</code>, and
     *   <code>doctype</code> are <code>null</code>, the returned
     *   <code>Document</code> is empty with no document element.
     * @throws java.sql.SQLException wrapping any internal exception that occurs.
     * @see org.w3c.dom.DOMImplementation#createDocument(String,String,DocumentType)
     */
    protected static Document createDocument(String namespaceURI,
            String qualifiedName, DocumentType docType) throws SQLException {

        try {
            return getDOMImplementation().createDocument(namespaceURI,
                    qualifiedName, docType);
        } catch (DOMException ex) {
            throw Exceptions.domInstantiation(ex);
        }
    }

    
Throws:
SQLException – wrapping any internal exception that occurs.
Returns:
that is empty with no document element./**
     * @return that is empty with no document element.
     * @throws java.sql.SQLException wrapping any internal exception that occurs.
     */
    protected static Document createDocument() throws SQLException {
        return createDocument(null, null, null);
    }

    
Initializes this object's SQLXML value from the given Source
object. 

Params:
source – the Source representing the SQLXML value
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Initializes this object's SQLXML value from the given Source
     * object. <p>
     *
     * @param source the Source representing the SQLXML value
     * @throws SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected void init(Source source) throws SQLException {

        if (source == null) {
            throw JDBCUtil.nullArgument("source");
        }

        Transformer           transformer =
            JDBCSQLXML.getIdentityTransformer();
        StreamResult          result      = new StreamResult();
        ByteArrayOutputStream baos        = new ByteArrayOutputStream();
        GZIPOutputStream      gzos;

        try {
            gzos = new GZIPOutputStream(baos);
        } catch (IOException ex) {
            throw Exceptions.transformFailed(ex);
        }
        result.setOutputStream(gzos);

        try {
            transformer.transform(source, result);
        } catch (TransformerException ex) {
            throw Exceptions.transformFailed(ex);
        }

        try {
            gzos.close();
        } catch (IOException ex) {
            throw Exceptions.transformFailed(ex);
        }

        byte[] data = baos.toByteArray();

        setGZipData(data);
        setReadable(true);
        setWritable(false);
    }

    
Assigns this object's SQLXML value from the designated gzipped array
of bytes.
Params:
data – the SQLXML value
Throws:
SQLException – if the argument does not represent a
     valid SQLXML value/**
     * Assigns this object's SQLXML value from the designated gzipped array
     * of bytes.
     *
     * @param data the SQLXML value
     * @throws java.sql.SQLException if the argument does not represent a
     *      valid SQLXML value
     */
    protected void setGZipData(byte[] data) throws SQLException {

        if (data == null) {
            throw JDBCUtil.nullArgument("data");
        }
        this.gzdata = data;
    }

    
Directly retrieves this object's present SQLMXL value as a gzipped
array of bytes. 

May be null, empty or invalid.
Returns:
this object's SQLMXL value as a gzipped byte array/**
     * Directly retrieves this object's present SQLMXL value as a gzipped
     * array of bytes. <p>
     *
     * May be null, empty or invalid.
     *
     * @return this object's SQLMXL value as a gzipped byte array
     */
    protected byte[] gZipData() {
        return this.gzdata;
    }

    
Retrieves this object's SQLXML value as a gzipped array of bytes,
possibly by terminating any in-progress write operations and converting
accumulated intermediate data.
Throws:
SQLException – if an underlying I/O or transform
     error occurs
Returns:
this object's SQLXML value/**
     * Retrieves this object's SQLXML value as a gzipped array of bytes,
     * possibly by terminating any in-progress write operations and converting
     * accumulated intermediate data.
     *
     * @throws java.sql.SQLException if an underlying I/O or transform
     *      error occurs
     * @return this object's SQLXML value
     */
    protected byte[] getGZipData() throws SQLException {

        byte[] bytes = gZipData();

        if (bytes != null) {
            return bytes;
        }

        if (this.domResult != null) {
            DOMSource source = new DOMSource(domResult.getNode(),
                domResult.getSystemId());
            OutputStream os     = setBinaryStreamImpl();
            StreamResult result = new StreamResult(os);

            try {
                JDBCSQLXML.identityTransformer.transform(source, result);
            } catch (TransformerException ex) {
                throw Exceptions.transformFailed(ex);
            }

            try {
                os.close();
            } catch (IOException ex) {
                throw Exceptions.transformFailed(ex);
            }
        }

        if (this.outputStream == null) {
            throw Exceptions.notReadable("No Data.");
        } else if (!this.outputStream.isClosed()) {
            throw Exceptions.notReadable(
                "Stream used for writing must be closed but is still open.");
        } else if (this.outputStream.isFreed()) {
            throw Exceptions.notReadable(
                "Stream used for writing was freed and is no longer valid.");
        }

        try {
            setGZipData(this.outputStream.toByteArray());

            return gZipData();
        } catch (IOException ex) {
            throw Exceptions.notReadable();
        } finally {
            this.freeOutputStream();
        }
    }

    
closes this object and releases the resources that it holds.
/**
     * closes this object and releases the resources that it holds.
     */
    protected synchronized void close() {

        this.closed = true;

        setReadable(false);
        setWritable(false);
        freeOutputStream();
        freeInputStream();
        freeDomResult();

        this.gzdata = null;
    }

    
Closes the input stream, if any, currently in use to read this object's
SQLXML value and nullifies the stream reference to make it eligible
for subsequent garbage collection.
/**
     * Closes the input stream, if any, currently in use to read this object's
     * SQLXML value and nullifies the stream reference to make it eligible
     * for subsequent garbage collection.
     */
    protected void freeInputStream() {

        if (this.inputStream != null) {
            try {
                this.inputStream.close();
            } catch (IOException ex) {

                // ex.printStackTrace();
            } finally {
                this.inputStream = null;
            }
        }
    }

    
Closes the output stream, if any, currently in use to write this object's
SQLXML value and nullifies the stream reference to make it eligible for
subsequent garbage collection.  The stream's data buffer reference may
also be nullified, in order to make it eligible for garbage collection
immediately, just in case an external client still holds a reference to
the output stream.
/**
     * Closes the output stream, if any, currently in use to write this object's
     * SQLXML value and nullifies the stream reference to make it eligible for
     * subsequent garbage collection.  The stream's data buffer reference may
     * also be nullified, in order to make it eligible for garbage collection
     * immediately, just in case an external client still holds a reference to
     * the output stream.
     */
    protected void freeOutputStream() {

        if (this.outputStream != null) {
            try {
                this.outputStream.free();
            } catch (IOException ex) {

                // ex.printStackTrace();
            }
            this.outputStream = null;
        }
    }

    
Checks whether this object is closed (has been freed).
Throws:
SQLException – if this object is closed./**
     * Checks whether this object is closed (has been freed).
     *
     * @throws java.sql.SQLException if this object is closed.
     */
    protected synchronized void checkClosed() throws SQLException {

        if (this.closed) {
            throw Exceptions.inFreedState();
        }
    }

    
Checks whether this object is readable.
Throws:
SQLException – if this object is not readable./**
     * Checks whether this object is readable.
     *
     * @throws java.sql.SQLException if this object is not readable.
     */
    protected synchronized void checkReadable() throws SQLException {

        if (!this.isReadable()) {
            throw Exceptions.notReadable();
        }
    }

    
Assigns this object's readability status.
Params:
readable – if true, then readable; else not readable/**
     * Assigns this object's readability status.
     *
     * @param readable if <tt>true</tt>, then readable; else not readable
     */
    protected synchronized void setReadable(boolean readable) {
        this.readable = readable;
    }

    
Checks whether this object is writable.
Throws:
SQLException – if this object is not writable./**
     * Checks whether this object is writable.
     *
     * @throws java.sql.SQLException if this object is not writable.
     */
    protected synchronized void checkWritable() throws SQLException {

        if (!this.isWritable()) {
            throw Exceptions.notWritable();
        }
    }

    
Assigns this object's writability status.
Params:
writable – if true, then writable; else not writable/**
     * Assigns this object's writability status.
     *
     * @param writable if <tt>true</tt>, then writable; else not writable
     */
    protected synchronized void setWritable(boolean writable) {
        this.writable = writable;
    }

    
Retrieves the object's readability status.
Returns:
if true, then readable; else not readable/**
     * Retrieves the object's readability status.
     *
     * @return if <tt>true</tt>, then readable; else not readable
     */
    public synchronized boolean isReadable() {
        return this.readable;
    }

    
Retrieves the object's readability status.
Returns:
if true, then writable; else not writable/**
     * Retrieves the object's readability status.
     *
     * @return if <tt>true</tt>, then writable; else not writable
     */
    public synchronized boolean isWritable() {
        return this.writable;
    }

    
Retrieves a stream representing the XML value designated by this
SQLXML instance. 

Throws:
SQLException – if there is an error processing the XML value.
Returns:
a stream containing the XML data./**
     * Retrieves a stream representing the XML value designated by this
     * SQLXML instance. <p>
     *
     * @return a stream containing the XML data.
     * @throws SQLException if there is an error processing the XML value.
     */
    protected InputStream getBinaryStreamImpl() throws SQLException {

        try {
            byte[]               data = getGZipData();
            ByteArrayInputStream bais = new ByteArrayInputStream(data);

            return new GZIPInputStream(bais);
        } catch (IOException ex) {
            throw Exceptions.transformFailed(ex);
        }
    }

    
Retrieves a reader representing the XML value designated by this
SQLXML instance. 

Throws:
SQLException – if there is an error processing the XML value.
Returns:
a reader containing the XML data./**
     * Retrieves a reader representing the XML value designated by this
     * SQLXML instance. <p>
     *
     * @return a reader containing the XML data.
     * @throws SQLException if there is an error processing the XML value.
     */
    protected Reader getCharacterStreamImpl() throws SQLException {
        return new InputStreamReader(getBinaryStreamImpl());
    }

    
Retrieves a string representing the XML value designated by this
SQLXML instance. 

Throws:
SQLException – if there is an error processing the XML value.
Returns:
a string containing the XML data./**
     * Retrieves a string representing the XML value designated by this
     * SQLXML instance. <p>
     *
     * @return a string containing the XML data.
     * @throws SQLException if there is an error processing the XML value.
     */
    protected String getStringImpl() throws SQLException {

        try {
            return StringConverter.inputStreamToString(getBinaryStreamImpl(),
                    "US-ASCII");
        } catch (IOException ex) {
            throw Exceptions.transformFailed(ex);
        }
    }

    
Retrieves a stream to completely write the XML value this SQLXML
instance represents. 

Throws:
SQLException – if there is an error processing the XML value.
Returns:
a stream to which the data can be written./**
     * Retrieves a stream to completely write the XML value this SQLXML
     * instance represents. <p>
     *
     * @return a stream to which the data can be written.
     * @throws SQLException if there is an error processing the XML value.
     */
    protected OutputStream setBinaryStreamImpl() throws SQLException {

        this.outputStream = new ClosableByteArrayOutputStream();

        try {
            return new GZIPOutputStream(this.outputStream);
        } catch (IOException ex) {
            this.outputStream = null;

            throw Exceptions.resultInstantiation(ex);
        }
    }

    
Retrieves a writer to completely write the XML value this SQLXML
instance represents. 

Throws:
SQLException – if there is an error processing the XML value.
  The getCause() method of the exception may provide a more detailed exception, for example,
  if the stream does not contain valid characters.
  An exception is thrown if the state is not writable.
Returns:
a writer to which the data can be written.
Since:
JDK 1.6 Build 79/**
     * Retrieves a writer to completely write the XML value this SQLXML
     * instance represents. <p>
     *
     * @return a writer to which the data can be written.
     * @throws SQLException if there is an error processing the XML value.
     *   The getCause() method of the exception may provide a more detailed exception, for example,
     *   if the stream does not contain valid characters.
     *   An exception is thrown if the state is not writable.
     * @since JDK 1.6 Build 79
     */
    protected Writer setCharacterStreamImpl() throws SQLException {
        return new OutputStreamWriter(setBinaryStreamImpl());
    }

    
Sets the XML value designated by this SQLXML instance using the given
String representation. 

Params:
value – the XML value
Throws:
SQLException – if there is an error processing the XML value./**
     * Sets the XML value designated by this SQLXML instance using the given
     * String representation. <p>
     *
     * @param value the XML value
     * @throws SQLException if there is an error processing the XML value.
     */
    protected void setStringImpl(String value) throws SQLException {
        init(new StreamSource(new StringReader(value)));
    }

    
Returns a Source for reading the XML value designated by this SQLXML
instance. 

Params:
sourceClass – The class of the source, or null.  If null, then a
     DOMSource is returned.
Throws:
SQLException – if there is an error processing the XML value
  or if the given sourceClass is not supported.
Returns:
a Source for reading the XML value./**
     * Returns a Source for reading the XML value designated by this SQLXML
     * instance. <p>
     *
     * @param sourceClass The class of the source, or null.  If null, then a
     *      DOMSource is returned.
     * @return a Source for reading the XML value.
     * @throws SQLException if there is an error processing the XML value
     *   or if the given <tt>sourceClass</tt> is not supported.
     */
    protected <T extends Source>T getSourceImpl(
            Class<T> sourceClass) throws SQLException {

        if (StreamSource.class.isAssignableFrom(sourceClass)) {
            return createStreamSource(sourceClass);
        } else if ((sourceClass == null)
                   || DOMSource.class.isAssignableFrom(sourceClass)) {
            return createDOMSource(sourceClass);
        } else if (SAXSource.class.isAssignableFrom(sourceClass)) {
            return createSAXSource(sourceClass);
        } else if (StAXSource.class.isAssignableFrom(sourceClass)) {
            return createStAXSource(sourceClass);
        }

        throw JDBCUtil.invalidArgument("sourceClass: " + sourceClass);
    }

    
Retrieves a new StreamSource for reading the XML value designated by this
SQLXML instance. 

Params:
sourceClass – The class of the source
Throws:
SQLException – if there is an error processing the XML
     value or if the given sourceClass is not supported.
Returns:
a new StreamSource for reading the XML value designated by this
     SQLXML instance/**
     * Retrieves a new StreamSource for reading the XML value designated by this
     * SQLXML instance. <p>
     *
     * @param sourceClass The class of the source
     * @throws java.sql.SQLException if there is an error processing the XML
     *      value or if the given <tt>sourceClass</tt> is not supported.
     * @return a new StreamSource for reading the XML value designated by this
     *      SQLXML instance
     */
    @SuppressWarnings("unchecked")
    protected <T extends Source>T createStreamSource(
            Class<T> sourceClass) throws SQLException {

        StreamSource source;

        try {
            if (sourceClass == null) source = new StreamSource();
            else {
                source = (StreamSource) sourceClass.getDeclaredConstructor().newInstance();
            }
        } catch (SecurityException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InstantiationException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (IllegalAccessException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (ClassCastException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (NoSuchMethodException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InvocationTargetException ex) {
            throw Exceptions.sourceInstantiation(ex);
        }

        Reader reader = getCharacterStreamImpl();

        source.setReader(reader);

        return (T) source;
    }

    
Retrieves a new DOMSource for reading the XML value designated by this
SQLXML instance. 

Params:
sourceClass – The class of the source
Throws:
SQLException – if there is an error processing the XML
     value or if the given sourceClass is not supported.
Returns:
a new DOMSource for reading the XML value designated by this
     SQLXML instance/**
     * Retrieves a new DOMSource for reading the XML value designated by this
     * SQLXML instance. <p>
     *
     * @param sourceClass The class of the source
     * @throws java.sql.SQLException if there is an error processing the XML
     *      value or if the given <tt>sourceClass</tt> is not supported.
     * @return a new DOMSource for reading the XML value designated by this
     *      SQLXML instance
     */
    @SuppressWarnings("unchecked")
    protected <T extends Source>T createDOMSource(
            Class<T> sourceClass) throws SQLException {

        DOMSource source;

        try {
            if (sourceClass == null) source = new DOMSource();
            else {
                source = (DOMSource) sourceClass.getDeclaredConstructor().newInstance();
            }
        } catch (SecurityException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (IllegalAccessException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InstantiationException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (ClassCastException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (NoSuchMethodException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InvocationTargetException ex) {
            throw Exceptions.sourceInstantiation(ex);
        }

        Transformer  transformer  = JDBCSQLXML.getIdentityTransformer();
        InputStream  stream       = this.getBinaryStreamImpl();
        StreamSource streamSource = new StreamSource();
        DOMResult    result       = new DOMResult();

        streamSource.setInputStream(stream);

        try {
            transformer.transform(streamSource, result);
        } catch (TransformerException ex) {
            throw Exceptions.transformFailed(ex);
        }
        source.setNode(result.getNode());
        source.setSystemId(result.getSystemId());

        return (T) source;
    }

    
Retrieves a new SAXSource for reading the XML value designated by this
SQLXML instance. 

Params:
sourceClass – The class of the source
Throws:
SQLException – if there is an error processing the XML
     value or if the given sourceClass is not supported.
Returns:
a new SAXSource for reading the XML value designated by this
     SQLXML instance/**
     * Retrieves a new SAXSource for reading the XML value designated by this
     * SQLXML instance. <p>
     *
     * @param sourceClass The class of the source
     * @throws java.sql.SQLException if there is an error processing the XML
     *      value or if the given <tt>sourceClass</tt> is not supported.
     * @return a new SAXSource for reading the XML value designated by this
     *      SQLXML instance
     */
    @SuppressWarnings("unchecked")
    protected <T extends Source>T createSAXSource(
            Class<T> sourceClass) throws SQLException {

        SAXSource source;

        try {
            if (sourceClass == null) source = new SAXSource();
            else {
                source = (SAXSource) sourceClass.getDeclaredConstructor().newInstance();
            }
        } catch (SecurityException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InstantiationException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (IllegalAccessException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (ClassCastException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (NoSuchMethodException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InvocationTargetException ex) {
            throw Exceptions.sourceInstantiation(ex);
        }

        Reader      reader      = getCharacterStreamImpl();
        InputSource inputSource = new InputSource(reader);

        source.setInputSource(inputSource);

        return (T) source;
    }

    
Retrieves a new StAXSource for reading the XML value designated by this
SQLXML instance. 

Params:
sourceClass – The class of the source
Throws:
SQLException – if there is an error processing the XML
     value or if the given sourceClass is not supported.
Returns:
a new StAXSource for reading the XML value designated by this
     SQLXML instance/**
     * Retrieves a new StAXSource for reading the XML value designated by this
     * SQLXML instance. <p>
     *
     * @param sourceClass The class of the source
     * @throws java.sql.SQLException if there is an error processing the XML
     *      value or if the given <tt>sourceClass</tt> is not supported.
     * @return a new StAXSource for reading the XML value designated by this
     *      SQLXML instance
     */
    @SuppressWarnings("unchecked")
    protected <T extends Source>T createStAXSource(
            Class<T> sourceClass) throws SQLException {

        StAXSource      source      = null;
        Constructor     sourceCtor  = null;
        Reader          reader      = null;
        XMLInputFactory factory     = null;
        XMLEventReader  eventReader = null;

        try {
            factory = XMLInputFactory.newInstance();
        } catch (FactoryConfigurationError ex) {
            throw Exceptions.sourceInstantiation(ex);
        }

        try {
            sourceCtor =
                (sourceClass == null)
                ? StAXSource.class.getConstructor(XMLEventReader.class)
                : sourceClass.getConstructor(XMLEventReader.class);
        } catch (SecurityException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (NoSuchMethodException ex) {
            throw Exceptions.sourceInstantiation(ex);
        }
        reader = getCharacterStreamImpl();

        try {
            eventReader = factory.createXMLEventReader(reader);
        } catch (XMLStreamException ex) {
            throw Exceptions.sourceInstantiation(ex);
        }

        try {
            source = (StAXSource) sourceCtor.newInstance(eventReader);
        } catch (SecurityException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (IllegalArgumentException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (IllegalAccessException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InstantiationException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InvocationTargetException ex) {
            throw Exceptions.sourceInstantiation(ex.getTargetException());
        } catch (ClassCastException ex) {
            throw Exceptions.sourceInstantiation(ex);
        }

        return (T) source;
    }

    
Retrieves a new Result for setting the XML value designated by this
SQLXML instance.
Params:
resultClass – The class of the result, or null.
Throws:
SQLException – if there is an error processing the XML
        value or the state is not writable
Returns:
for setting the XML value designated by this SQLXML instance./**
     * Retrieves a new Result for setting the XML value designated by this
     * SQLXML instance.
     *
     * @param resultClass The class of the result, or null.
     * @throws java.sql.SQLException if there is an error processing the XML
     *         value or the state is not writable
     * @return for setting the XML value designated by this SQLXML instance.
     */
    protected <T extends Result>T createResult(
            Class<T> resultClass) throws SQLException {

        checkWritable();
        setWritable(false);
        setReadable(true);

        if ((resultClass == null)
                   || StreamResult.class.isAssignableFrom(resultClass)) {
            return createStreamResult(resultClass);
        } else if (DOMResult.class.isAssignableFrom(resultClass)) {
            return createDOMResult(resultClass);
        } else if (SAXResult.class.isAssignableFrom(resultClass)) {
            return createSAXResult(resultClass);
        } else if (StAXResult.class.isAssignableFrom(resultClass)) {
            return createStAXResult(resultClass);
        }

        throw JDBCUtil.invalidArgument("resultClass: " + resultClass);
    }

    
Retrieves a new StreamResult for setting the XML value designated by this
SQLXML instance.
Params:
resultClass – The class of the result, or null.
Throws:
SQLException – if there is an error processing the XML
        value
Returns:
for setting the XML value designated by this SQLXML instance./**
     * Retrieves a new StreamResult for setting the XML value designated by this
     * SQLXML instance.
     *
     * @param resultClass The class of the result, or null.
     * @throws java.sql.SQLException if there is an error processing the XML
     *         value
     * @return for setting the XML value designated by this SQLXML instance.
     */

//  @SuppressWarnings("unchecked")
    protected <T extends Result>T createStreamResult(
            Class<T> resultClass) throws SQLException {

        StreamResult result;

        try {
            if (resultClass == null) result = new StreamResult();
            else {
                result = (StreamResult) resultClass.getDeclaredConstructor().newInstance();
            }
        } catch (SecurityException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (InstantiationException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (IllegalAccessException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (ClassCastException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (NoSuchMethodException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InvocationTargetException ex) {
            throw Exceptions.sourceInstantiation(ex);
        }

        OutputStream stream = setBinaryStreamImpl();

        result.setOutputStream(stream);

        return (T) result;
    }

    
Retrieves a new DOMResult for setting the XML value designated by this
SQLXML instance.
Params:
resultClass – The class of the result, or null.
Throws:
SQLException – if there is an error processing the XML
        value
Returns:
for setting the XML value designated by this SQLXML instance./**
     * Retrieves a new DOMResult for setting the XML value designated by this
     * SQLXML instance.
     *
     * @param resultClass The class of the result, or null.
     * @throws java.sql.SQLException if there is an error processing the XML
     *         value
     * @return for setting the XML value designated by this SQLXML instance.
     */
    @SuppressWarnings("unchecked")
    protected <T extends Result>T createDOMResult(
            Class<T> resultClass) throws SQLException {

        try {
            T result;
            if (resultClass == null) result = (T) new DOMResult();
            else {
                result = resultClass.getDeclaredConstructor().newInstance();
            }

            this.domResult = (DOMResult) result;

            return result;
        } catch (SecurityException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (InstantiationException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (IllegalAccessException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (ClassCastException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (NoSuchMethodException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InvocationTargetException ex) {
            throw Exceptions.sourceInstantiation(ex);
        }
    }

    
 Retrieves a new SAXResult for setting the XML value designated by this
 SQLXML instance.
 @param resultClass The class of the result, or null.
 @throws java.sql.SQLException if there is an error processing the XML
         value
 @return for setting the XML value designated by this SQLXML instance.
/**
     *  Retrieves a new SAXResult for setting the XML value designated by this
     *  SQLXML instance.
     *
     *  @param resultClass The class of the result, or null.
     *  @throws java.sql.SQLException if there is an error processing the XML
     *          value
     *  @return for setting the XML value designated by this SQLXML instance.
     */
    @SuppressWarnings("unchecked")
    protected <T extends Result>T createSAXResult(
            Class<T> resultClass) throws SQLException {

        SAXResult result = null;

        try {
            if (resultClass == null) result = new SAXResult();
            else {
                result = (SAXResult) resultClass.getDeclaredConstructor().newInstance();
            }
        } catch (SecurityException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (InstantiationException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (IllegalAccessException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (ClassCastException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (NoSuchMethodException ex) {
            throw Exceptions.sourceInstantiation(ex);
        } catch (InvocationTargetException ex) {
            throw Exceptions.sourceInstantiation(ex);
        }

        SAX2DOMBuilder handler = null;

        try {
            handler = new SAX2DOMBuilder();
        } catch (ParserConfigurationException ex) {
            throw Exceptions.resultInstantiation(ex);
        }
        this.domResult = new DOMResult();

        result.setHandler(handler);
        this.domResult.setNode(handler.getDocument());

        return (T) result;
    }

    
 Retrieves a new DOMResult for setting the XML value designated by this
 SQLXML instance.
 @param resultClass The class of the result, or null.
 @throws java.sql.SQLException if there is an error processing the XML
         value
 @return for setting the XML value designated by this SQLXML instance.
/**
     *  Retrieves a new DOMResult for setting the XML value designated by this
     *  SQLXML instance.
     *
     *  @param resultClass The class of the result, or null.
     *  @throws java.sql.SQLException if there is an error processing the XML
     *          value
     *  @return for setting the XML value designated by this SQLXML instance.
     */
    @SuppressWarnings("unchecked")
    protected <T extends Result>T createStAXResult(
            Class<T> resultClass) throws SQLException {

        StAXResult result = null;

        try {
            this.domResult =
                new DOMResult((new SAX2DOMBuilder()).getDocument());

            XMLOutputFactory factory = XMLOutputFactory.newInstance();
            XMLStreamWriter xmlStreamWriter =
                factory.createXMLStreamWriter(this.domResult);

            if (resultClass == null || resultClass == StAXResult.class) {
                result = new StAXResult(xmlStreamWriter);
            } else {
                Constructor ctor =
                    resultClass.getConstructor(XMLStreamWriter.class);

                result = (StAXResult) ctor.newInstance(xmlStreamWriter);
            }
        } catch (ParserConfigurationException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (SecurityException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (IllegalArgumentException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (IllegalAccessException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (InvocationTargetException ex) {
            throw Exceptions.resultInstantiation(ex.getTargetException());
        } catch (FactoryConfigurationError ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (InstantiationException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (NoSuchMethodException ex) {
            throw Exceptions.resultInstantiation(ex);
        } catch (XMLStreamException ex) {
            throw Exceptions.resultInstantiation(ex);
        }

        return (T) result;
    }

    protected void freeDomResult() {
        this.domResult = null;
    }

    
Basically just a namespace to isolate SQLXML exception generation
/**
     * Basically just a namespace to isolate SQLXML exception generation
     */
    protected static class Exceptions {

        
Construction Disabled.
/**
         * Construction Disabled.
         */
        private Exceptions() {
        }

        
 Retrieves a new SQLXML DOM instantiation exception.
Params:
cause – of the exception/**
         *  Retrieves a new SQLXML DOM instantiation exception.
         *
         * @param cause of the exception
         */
        static SQLException domInstantiation(Throwable cause) {

            Exception ex = (cause instanceof Exception) ? (Exception) cause
                    : new Exception(cause);

            return JDBCUtil.sqlException(ErrorCode.GENERAL_ERROR,
                                     "SQLXML DOM instantiation failed: "
                                     + cause, ex);
        }

        
Retrieves a new SQLXML source instantiation exception.
Params:
cause – of the exception.
Returns:
a new SQLXML source instantiation exception/**
         * Retrieves a new SQLXML source instantiation exception.
         *
         * @param cause of the exception.
         * @return a new SQLXML source instantiation exception
         */
        static SQLException sourceInstantiation(Throwable cause) {

            Exception ex = (cause instanceof Exception) ? (Exception) cause
                    : new Exception(cause);

            return JDBCUtil.sqlException(ErrorCode.GENERAL_ERROR,
                                     "SQLXML Source instantiation failed: "
                                     + cause, ex);
        }

        
Retrieves a new SQLXML result instantiation exception.
Params:
cause – of the exception.
Returns:
a new SQLXML result instantiation exception/**
         * Retrieves a new SQLXML result instantiation exception.
         *
         * @param cause of the exception.
         * @return a new SQLXML result instantiation exception
         */
        static SQLException resultInstantiation(Throwable cause) {

            Exception ex = (cause instanceof Exception) ? (Exception) cause
                    : new Exception(cause);

            return JDBCUtil.sqlException(ErrorCode.GENERAL_ERROR,
                                     "SQLXML Result instantiation failed: "
                                     + cause, ex);
        }

        
Retrieves a new SQLXML parse failed exception.
Params:
cause – of the exception.
Returns:
a new SQLXML parse failed exception/**
         * Retrieves a new SQLXML parse failed exception.
         *
         * @param cause of the exception.
         * @return a new SQLXML parse failed exception
         */
        static SQLException parseFailed(Throwable cause) {

            Exception ex = (cause instanceof Exception) ? (Exception) cause
                    : new Exception(cause);

            return JDBCUtil.sqlException(ErrorCode.GENERAL_ERROR,
                                     "parse failed: " + cause, ex);
        }

        
Retrieves a new SQLXML transform failed exception.
Params:
cause – of the exception.
Returns:
a new SQLXML parse failed exception/**
         * Retrieves a new SQLXML transform failed exception.
         *
         * @param cause of the exception.
         * @return a new SQLXML parse failed exception
         */
        static SQLException transformFailed(Throwable cause) {

            Exception ex = (cause instanceof Exception) ? (Exception) cause
                    : new Exception(cause);

            return JDBCUtil.sqlException(ErrorCode.GENERAL_ERROR,
                                     "transform failed: " + cause, ex);
        }

        
Retrieves a new SQLXML not readable exception.
Returns:
a new SQLXML not readable exception/**
         * Retrieves a new SQLXML not readable exception.
         *
         * @return a new SQLXML not readable exception
         */
        static SQLException notReadable() {
            return JDBCUtil.sqlException(ErrorCode.GENERAL_IO_ERROR,
                                     "SQLXML in not readable state");
        }

        
Retrieves a new SQLXML not readable exception.
Returns:
a new SQLXML not readable exception/**
         * Retrieves a new SQLXML not readable exception.
         *
         * @return a new SQLXML not readable exception
         */
        static SQLException notReadable(String reason) {

            return JDBCUtil.sqlException(ErrorCode.GENERAL_IO_ERROR,
                                     "SQLXML in not readable state: "
                                     + reason);
        }

        
Retrieves a new SQLXML not writable exception.
Returns:
a new SQLXML not writable exception/**
         * Retrieves a new SQLXML not writable exception.
         *
         * @return a new SQLXML not writable exception
         */
        static SQLException notWritable() {
            return JDBCUtil.sqlException(ErrorCode.GENERAL_IO_ERROR,
                                     "SQLXML in not writable state");
        }

        
Currently unused.
Returns:
never/**
         * Currently unused.
         *
         * @return never
         */
        static SQLException directUpdateByLocatorNotSupported() {
            return JDBCUtil.sqlException(ErrorCode.X_0A000,
                                     "SQLXML direct update by locator");
        }

        
Retrieves a new SQLXML in freed state exception.
Returns:
a new SQLXML in freed state exception/**
         * Retrieves a new SQLXML in freed state exception.
         *
         * @return a new SQLXML in freed state exception
         */
        static SQLException inFreedState() {
            return JDBCUtil.sqlException(ErrorCode.GENERAL_ERROR,
                                     "SQLXML in freed state");
        }
    }

    // -------------------------------------------------------------------------

    
Builds a DOM from SAX events.
/**
     * Builds a DOM from SAX events.
     */
    protected static class SAX2DOMBuilder implements ContentHandler,
            Closeable {

        /**
         *
         */
        private boolean closed;

        /**
         *
         */
        private Element currentElement;

        // --------------------- internal implementation -----------------------

        /**
         *
         */
        private Node currentNode;

        /**
         *
         */
        private Document document;

        /**
         *
         */
        private Locator locator;

        
Creates a new instance of SAX2DOMBuilder, which creates a new document. The document is available via getDocument().
Throws:
ParserConfigurationException – /**
         * <p>Creates a new instance of SAX2DOMBuilder, which creates
         * a new document. The document is available via
         * {@link #getDocument()}.</p>
         * @throws javax.xml.parsers.ParserConfigurationException
         */
        public SAX2DOMBuilder() throws ParserConfigurationException {

            DocumentBuilderFactory documentBuilderFactory;
            DocumentBuilder        documentBuilder;

            documentBuilderFactory = DocumentBuilderFactory.newInstance();

            documentBuilderFactory.setValidating(false);
            documentBuilderFactory.setNamespaceAware(true);

            documentBuilder  = documentBuilderFactory.newDocumentBuilder();
            this.document    = documentBuilder.newDocument();
            this.currentNode = this.document;
        }

        
Receive an object for locating the origin of SAX document events.
SAX parsers are strongly encouraged (though not absolutely
required) to supply a locator: if it does so, it must supply
the locator to the application by invoking this method before
invoking any of the other methods in the ContentHandler
interface.
The locator allows the application to determine the end
position of any document-related event, even if the parser is
not reporting an error.  Typically, the application will
use this information for reporting its own errors (such as
character content that does not match an application's
business rules).  The information returned by the locator
is probably not sufficient for use with a search engine.
Note that the locator will return correct information only during the invocation SAX event callbacks after startDocument returns and before endDocument is called. The application should not attempt to use it at any other time.
Params:
locator – an object that can return the location of
               any SAX document event
See Also:
Locator/**
         * Receive an object for locating the origin of SAX document events.
         *
         * <p>SAX parsers are strongly encouraged (though not absolutely
         * required) to supply a locator: if it does so, it must supply
         * the locator to the application by invoking this method before
         * invoking any of the other methods in the ContentHandler
         * interface.</p>
         *
         * <p>The locator allows the application to determine the end
         * position of any document-related event, even if the parser is
         * not reporting an error.  Typically, the application will
         * use this information for reporting its own errors (such as
         * character content that does not match an application's
         * business rules).  The information returned by the locator
         * is probably not sufficient for use with a search engine.</p>
         *
         * <p>Note that the locator will return correct information only
         * during the invocation SAX event callbacks after
         * {@link #startDocument startDocument} returns and before
         * {@link #endDocument endDocument} is called.  The
         * application should not attempt to use it at any other time.</p>
         *
         * @param locator an object that can return the location of
         *                any SAX document event
         * @see org.xml.sax.Locator
         */
        public void setDocumentLocator(Locator locator) {
            this.locator = locator;
        }

        
Retrieves the Locator. 

Returns:
the Locator/**
         * Retrieves the Locator. <p>
         * @return the Locator
         */
        public Locator getDocumentLocator() {
            return this.locator;
        }

        
Receive notification of the beginning of a document.
The SAX parser will invoke this method only once, before any other event callbacks (except for 
setDocumentLocator).
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception
See Also:
endDocument/**
         * Receive notification of the beginning of a document.
         *
         * <p>The SAX parser will invoke this method only once, before any
         * other event callbacks (except for {@link #setDocumentLocator
         * setDocumentLocator}).</p>
         *
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         * @see #endDocument
         */
        public void startDocument() throws SAXException {
            checkClosed();
        }

        
Receive notification of the end of a document.
There is an apparent contradiction between the documentation for this method and the documentation for ErrorHandler.fatalError. Until this ambiguity is resolved in a future major release, clients should make no assumptions about whether endDocument() will or will not be invoked when the parser has reported a fatalError() or thrown an exception.
The SAX parser will invoke this method only once, and it will
be the last method invoked during the parse.  The parser shall
not invoke this method until it has either abandoned parsing
(because of an unrecoverable error) or reached the end of
input.
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception
See Also:
startDocument/**
         * Receive notification of the end of a document.
         *
         * <p><strong>There is an apparent contradiction between the
         * documentation for this method and the documentation for {@link
         * org.xml.sax.ErrorHandler#fatalError}.  Until this ambiguity is
         * resolved in a future major release, clients should make no
         * assumptions about whether endDocument() will or will not be
         * invoked when the parser has reported a fatalError() or thrown
         * an exception.</strong></p>
         *
         * <p>The SAX parser will invoke this method only once, and it will
         * be the last method invoked during the parse.  The parser shall
         * not invoke this method until it has either abandoned parsing
         * (because of an unrecoverable error) or reached the end of
         * input.</p>
         *
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         * @see #startDocument
         */
        public void endDocument() throws SAXException {
            checkClosed();
            close();
        }

        
Begin the scope of a prefix-URI Namespace mapping.
The information from this event is not necessary for
normal Namespace processing: the SAX XML reader will
automatically replace prefixes for element and attribute
names when the http://xml.org/sax/features/namespaces
feature is true (the default).
There are cases, however, when applications need to
use prefixes in character data or in attribute values,
where they cannot safely be expanded automatically; the
start/endPrefixMapping event supplies the information
to the application to expand prefixes in those contexts
itself, if necessary.
Note that start/endPrefixMapping events are not guaranteed to be properly nested relative to each other: all startPrefixMapping events will occur immediately before the corresponding startElement event, and all endPrefixMapping events will occur immediately after the corresponding endElement event, but their order is not otherwise guaranteed.
There should never be start/endPrefixMapping events for the
"xml" prefix, since it is predeclared and immutable.
Params:
prefix – the Namespace prefix being declared.
     An empty string is used for the default element namespace,
     which has no prefix.
uri – the Namespace URI the prefix is mapped to
Throws:
SAXException – the client may throw
           an exception during processing
See Also:
endPrefixMapping
startElement/**
         * Begin the scope of a prefix-URI Namespace mapping.
         *
         * <p>The information from this event is not necessary for
         * normal Namespace processing: the SAX XML reader will
         * automatically replace prefixes for element and attribute
         * names when the <code>http://xml.org/sax/features/namespaces</code>
         * feature is <var>true</var> (the default).</p>
         *
         * <p>There are cases, however, when applications need to
         * use prefixes in character data or in attribute values,
         * where they cannot safely be expanded automatically; the
         * start/endPrefixMapping event supplies the information
         * to the application to expand prefixes in those contexts
         * itself, if necessary.</p>
         *
         * <p>Note that start/endPrefixMapping events are not
         * guaranteed to be properly nested relative to each other:
         * all startPrefixMapping events will occur immediately before the
         * corresponding {@link #startElement startElement} event,
         * and all {@link #endPrefixMapping endPrefixMapping}
         * events will occur immediately after the corresponding
         * {@link #endElement endElement} event,
         * but their order is not otherwise
         * guaranteed.</p>
         *
         * <p>There should never be start/endPrefixMapping events for the
         * "xml" prefix, since it is predeclared and immutable.</p>
         *
         * @param prefix the Namespace prefix being declared.
         *      An empty string is used for the default element namespace,
         *      which has no prefix.
         * @param uri the Namespace URI the prefix is mapped to
         * @throws org.xml.sax.SAXException the client may throw
         *            an exception during processing
         * @see #endPrefixMapping
         * @see #startElement
         */
        public void startPrefixMapping(String prefix,
                                       String uri) throws SAXException {
            checkClosed();
        }

        
End the scope of a prefix-URI mapping.
See startPrefixMapping for details. These events will always occur immediately after the corresponding endElement event, but the order of endPrefixMapping events is not otherwise guaranteed.
Params:
prefix – the prefix that was being mapped.
     This is the empty string when a default mapping scope ends.
Throws:
SAXException – the client may throw
           an exception during processing
See Also:
startPrefixMapping
endElement/**
         * End the scope of a prefix-URI mapping.
         *
         * <p>See {@link #startPrefixMapping startPrefixMapping} for
         * details.  These events will always occur immediately after the
         * corresponding {@link #endElement endElement} event, but the order of
         * {@link #endPrefixMapping endPrefixMapping} events is not otherwise
         * guaranteed.</p>
         *
         * @param prefix the prefix that was being mapped.
         *      This is the empty string when a default mapping scope ends.
         * @throws org.xml.sax.SAXException the client may throw
         *            an exception during processing
         * @see #startPrefixMapping
         * @see #endElement
         */
        public void endPrefixMapping(String prefix) throws SAXException {
            checkClosed();
        }

        
Receive notification of the beginning of an element.
The Parser will invoke this method at the beginning of every element in the XML document; there will be a corresponding endElement event for every startElement event (even when the element is empty). All of the element's content will be reported, in order, before the corresponding endElement event.
This event allows up to three name components for each
element:

the Namespace URI;
the local name; and
the qualified (prefixed) name.

Any or all of these may be provided, depending on the
values of the http://xml.org/sax/features/namespaces
and the http://xml.org/sax/features/namespace-prefixes
properties:

the Namespace URI and local name are required when
the namespaces property is true (the default), and are
optional when the namespaces property is false (if one is
specified, both must be);
the qualified name is required when the namespace-prefixes property
is true, and is optional when the namespace-prefixes property
is false (the default).

Note that the attribute list provided will contain only
attributes with explicit values (specified or defaulted):
#IMPLIED attributes will be omitted.  The attribute list
will contain attributes used for Namespace declarations
(xmlns* attributes) only if the
http://xml.org/sax/features/namespace-prefixes
property is true (it is false by default, and support for a
true value is optional).
Like characters(), attribute values may have characters that need more than one char value.  
Params:
uri – the Namespace URI, or the empty string if the
       element has no Namespace URI or if Namespace
       processing is not being performed
localName – the local name (without prefix), or the
       empty string if Namespace processing is not being
       performed
qName – the qualified name (with prefix), or the
       empty string if qualified names are not available
atts – the attributes attached to the element.  If
       there are no attributes, it shall be an empty
       Attributes object.  The value of this object after
       startElement returns is undefined
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception
See Also:
endElement
Attributes
AttributesImpl/**
         * Receive notification of the beginning of an element.
         *
         * <p>The Parser will invoke this method at the beginning of every
         * element in the XML document; there will be a corresponding
         * {@link #endElement endElement} event for every startElement event
         * (even when the element is empty). All of the element's content will be
         * reported, in order, before the corresponding endElement
         * event.</p>
         *
         * <p>This event allows up to three name components for each
         * element:</p>
         *
         * <ol>
         * <li>the Namespace URI;</li>
         * <li>the local name; and</li>
         * <li>the qualified (prefixed) name.</li>
         * </ol>
         *
         * <p>Any or all of these may be provided, depending on the
         * values of the <var>http://xml.org/sax/features/namespaces</var>
         * and the <var>http://xml.org/sax/features/namespace-prefixes</var>
         * properties:</p>
         *
         * <ul>
         * <li>the Namespace URI and local name are required when
         * the namespaces property is <var>true</var> (the default), and are
         * optional when the namespaces property is <var>false</var> (if one is
         * specified, both must be);</li>
         * <li>the qualified name is required when the namespace-prefixes property
         * is <var>true</var>, and is optional when the namespace-prefixes property
         * is <var>false</var> (the default).</li>
         * </ul>
         *
         * <p>Note that the attribute list provided will contain only
         * attributes with explicit values (specified or defaulted):
         * #IMPLIED attributes will be omitted.  The attribute list
         * will contain attributes used for Namespace declarations
         * (xmlns* attributes) only if the
         * <code>http://xml.org/sax/features/namespace-prefixes</code>
         * property is true (it is false by default, and support for a
         * true value is optional).</p>
         *
         * <p>Like {@link #characters characters()}, attribute values may have
         * characters that need more than one <code>char</code> value.  </p>
         *
         * @param uri the Namespace URI, or the empty string if the
         *        element has no Namespace URI or if Namespace
         *        processing is not being performed
         * @param localName the local name (without prefix), or the
         *        empty string if Namespace processing is not being
         *        performed
         * @param qName the qualified name (with prefix), or the
         *        empty string if qualified names are not available
         * @param atts the attributes attached to the element.  If
         *        there are no attributes, it shall be an empty
         *        Attributes object.  The value of this object after
         *        startElement returns is undefined
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         * @see #endElement
         * @see org.xml.sax.Attributes
         * @see org.xml.sax.helpers.AttributesImpl
         */
        public void startElement(String uri, String localName, String qName,
                                 Attributes atts) throws SAXException {

            checkClosed();

            Element element;

            if ((uri == null) || (uri.length() == 0)) {
                element = getDocument().createElement(qName);
            } else {
                element = getDocument().createElementNS(uri, qName);
            }

            if (atts != null) {
                for (int i = 0; i < atts.getLength(); i++) {
                    String attrURI   = atts.getURI(i);
                    String attrQName = atts.getQName(i);
                    String attrValue = atts.getValue(i);

                    if ((attrURI == null) || (attrURI.length() == 0)) {
                        element.setAttribute(attrQName, attrValue);
                    } else {
                        element.setAttributeNS(attrURI, attrQName, attrValue);
                    }
                }
            }
            getCurrentNode().appendChild(element);
            setCurrentNode(element);

            if (getCurrentElement() == null) {
                setCurrentElement(element);
            }
        }

        
Receive notification of the end of an element.
The SAX parser will invoke this method at the end of every element in the XML document; there will be a corresponding startElement event for every endElement event (even when the element is empty).
For information on the names, see startElement.
Params:
uri – the Namespace URI, or the empty string if the
       element has no Namespace URI or if Namespace
       processing is not being performed
localName – the local name (without prefix), or the
       empty string if Namespace processing is not being
       performed
qName – the qualified XML name (with prefix), or the
       empty string if qualified names are not available
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception/**
         * Receive notification of the end of an element.
         *
         * <p>The SAX parser will invoke this method at the end of every
         * element in the XML document; there will be a corresponding
         * {@link #startElement startElement} event for every endElement
         * event (even when the element is empty).</p>
         *
         * <p>For information on the names, see startElement.</p>
         *
         * @param uri the Namespace URI, or the empty string if the
         *        element has no Namespace URI or if Namespace
         *        processing is not being performed
         * @param localName the local name (without prefix), or the
         *        empty string if Namespace processing is not being
         *        performed
         * @param qName the qualified XML name (with prefix), or the
         *        empty string if qualified names are not available
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         */
        public void endElement(String uri, String localName,
                               String qName) throws SAXException {
            checkClosed();
            setCurrentNode(getCurrentNode().getParentNode());
        }

        
Receive notification of character data.
The Parser will call this method to report each chunk of
character data.  SAX parsers may return all contiguous character
data in a single chunk, or they may split it into several
chunks; however, all of the characters in any single event
must come from the same external entity so that the Locator
provides useful information.
The application must not attempt to read from the array
outside of the specified range.
Individual characters may consist of more than one Java
char value.  There are two important cases where this
happens, because characters can't be represented in just sixteen bits.
In one case, characters are represented in a Surrogate Pair,
using two special Unicode values. Such characters are in the so-called
"Astral Planes", with a code point above U+FFFF.  A second case involves
composite characters, such as a base character combining with one or
more accent characters. 
 Your code should not assume that algorithms using
char-at-a-time idioms will be working in character
units; in some cases they will split characters.  This is relevant
wherever XML permits arbitrary characters, such as attribute values,
processing instruction data, and comments as well as in data reported
from this method.  It's also generally relevant whenever Java code
manipulates internationalized text; the issue isn't unique to XML.
Note that some parsers will report whitespace in element content using the ignorableWhitespace method rather than this one (validating parsers must
do so).
Params:
ch – the characters from the XML document
start – the start position in the array
length – the number of characters to read from the array
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception
See Also:
ignorableWhitespace
Locator/**
         * Receive notification of character data.
         *
         * <p>The Parser will call this method to report each chunk of
         * character data.  SAX parsers may return all contiguous character
         * data in a single chunk, or they may split it into several
         * chunks; however, all of the characters in any single event
         * must come from the same external entity so that the Locator
         * provides useful information.</p>
         *
         * <p>The application must not attempt to read from the array
         * outside of the specified range.</p>
         *
         * <p>Individual characters may consist of more than one Java
         * <code>char</code> value.  There are two important cases where this
         * happens, because characters can't be represented in just sixteen bits.
         * In one case, characters are represented in a <em>Surrogate Pair</em>,
         * using two special Unicode values. Such characters are in the so-called
         * "Astral Planes", with a code point above U+FFFF.  A second case involves
         * composite characters, such as a base character combining with one or
         * more accent characters. </p>
         *
         * <p> Your code should not assume that algorithms using
         * <code>char</code>-at-a-time idioms will be working in character
         * units; in some cases they will split characters.  This is relevant
         * wherever XML permits arbitrary characters, such as attribute values,
         * processing instruction data, and comments as well as in data reported
         * from this method.  It's also generally relevant whenever Java code
         * manipulates internationalized text; the issue isn't unique to XML.</p>
         *
         * <p>Note that some parsers will report whitespace in element
         * content using the {@link #ignorableWhitespace ignorableWhitespace}
         * method rather than this one (validating parsers <em>must</em>
         * do so).</p>
         *
         * @param ch the characters from the XML document
         * @param start the start position in the array
         * @param length the number of characters to read from the array
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         * @see #ignorableWhitespace
         * @see org.xml.sax.Locator
         */
        public void characters(char[] ch, int start,
                               int length) throws SAXException {

            checkClosed();

            Node   node = getCurrentNode().getLastChild();
            String s    = new String(ch, start, length);

            if ((node != null) && (node.getNodeType() == Node.TEXT_NODE)) {
                ((Text) node).appendData(s);
            } else {
                Text text = getDocument().createTextNode(s);

                getCurrentNode().appendChild(text);
            }
        }

        
Receive notification of ignorable whitespace in element content.
Validating Parsers must use this method to report each chunk
of whitespace in element content (see the W3C XML 1.0
recommendation, section 2.10): non-validating parsers may also
use this method if they are capable of parsing and using
content models.
SAX parsers may return all contiguous whitespace in a single
chunk, or they may split it into several chunks; however, all of
the characters in any single event must come from the same
external entity, so that the Locator provides useful
information.
The application must not attempt to read from the array
outside of the specified range.
Params:
ch – the characters from the XML document
start – the start position in the array
length – the number of characters to read from the array
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception
See Also:
characters/**
         * Receive notification of ignorable whitespace in element content.
         *
         * <p>Validating Parsers must use this method to report each chunk
         * of whitespace in element content (see the W3C XML 1.0
         * recommendation, section 2.10): non-validating parsers may also
         * use this method if they are capable of parsing and using
         * content models.</p>
         *
         * <p>SAX parsers may return all contiguous whitespace in a single
         * chunk, or they may split it into several chunks; however, all of
         * the characters in any single event must come from the same
         * external entity, so that the Locator provides useful
         * information.</p>
         *
         * <p>The application must not attempt to read from the array
         * outside of the specified range.</p>
         *
         * @param ch the characters from the XML document
         * @param start the start position in the array
         * @param length the number of characters to read from the array
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         * @see #characters
         */
        public void ignorableWhitespace(char[] ch, int start,
                                        int length) throws SAXException {
            characters(ch, start, length);
        }

        
Receive notification of a processing instruction.
The Parser will invoke this method once for each processing
instruction found: note that processing instructions may occur
before or after the main document element.
A SAX parser must never report an XML declaration (XML 1.0,
section 2.8) or a text declaration (XML 1.0, section 4.3.1)
using this method.
Like characters(), processing instruction data may have characters that need more than one char
value. 
Params:
target – the processing instruction target
data – the processing instruction data, or null if
       none was supplied.  The data does not include any
       whitespace separating it from the target
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception/**
         * Receive notification of a processing instruction.
         *
         * <p>The Parser will invoke this method once for each processing
         * instruction found: note that processing instructions may occur
         * before or after the main document element.</p>
         *
         * <p>A SAX parser must never report an XML declaration (XML 1.0,
         * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
         * using this method.</p>
         *
         * <p>Like {@link #characters characters()}, processing instruction
         * data may have characters that need more than one <code>char</code>
         * value. </p>
         *
         * @param target the processing instruction target
         * @param data the processing instruction data, or null if
         *        none was supplied.  The data does not include any
         *        whitespace separating it from the target
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         */
        public void processingInstruction(String target,
                String data) throws SAXException {

            checkClosed();

            ProcessingInstruction processingInstruction;

            processingInstruction =
                getDocument().createProcessingInstruction(target, data);

            getCurrentNode().appendChild(processingInstruction);
        }

        
Receive notification of a skipped entity.
This is not called for entity references within markup constructs
such as element start tags or markup declarations.  (The XML
recommendation requires reporting skipped external entities.
SAX also reports internal entity expansion/non-expansion, except
within markup constructs.)
The Parser will invoke this method each time the entity is
skipped.  Non-validating processors may skip entities if they
have not seen the declarations (because, for example, the
entity was declared in an external DTD subset).  All processors
may skip external entities, depending on the values of the
http://xml.org/sax/features/external-general-entities
and the
http://xml.org/sax/features/external-parameter-entities
properties.
Params:
name – the name of the skipped entity.  If it is a
       parameter entity, the name will begin with '%', and if
       it is the external DTD subset, it will be the string
       "[dtd]"
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception/**
         * Receive notification of a skipped entity.
         * This is not called for entity references within markup constructs
         * such as element start tags or markup declarations.  (The XML
         * recommendation requires reporting skipped external entities.
         * SAX also reports internal entity expansion/non-expansion, except
         * within markup constructs.)
         *
         * <p>The Parser will invoke this method each time the entity is
         * skipped.  Non-validating processors may skip entities if they
         * have not seen the declarations (because, for example, the
         * entity was declared in an external DTD subset).  All processors
         * may skip external entities, depending on the values of the
         * <code>http://xml.org/sax/features/external-general-entities</code>
         * and the
         * <code>http://xml.org/sax/features/external-parameter-entities</code>
         * properties.</p>
         *
         * @param name the name of the skipped entity.  If it is a
         *        parameter entity, the name will begin with '%', and if
         *        it is the external DTD subset, it will be the string
         *        "[dtd]"
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         */
        public void skippedEntity(String name) throws SAXException {

            checkClosed();

            EntityReference entityReference =
                getDocument().createEntityReference(name);

            getCurrentNode().appendChild(entityReference);
        }

        
Closes this DOMBuilder.
/**
         * Closes this DOMBuilder.
         */
        public void close() {
            this.closed = true;
        }

        
Frees the DOMBuilder.
/**
         * Frees the DOMBuilder.
         */
        public void free() {

            close();

            this.document       = null;
            this.currentElement = null;
            this.currentNode    = null;
            this.locator        = null;
        }

        
Retrieves whether this DOMBuilder is closed.
Returns:
boolean/**
         * Retrieves whether this DOMBuilder is closed.
         *
         * @return boolean
         */
        public boolean isClosed() {
            return this.closed;
        }

        
Checks whether this DOMBuilder is closed.
Throws:
SAXException – if this DOMBuilder is closed./**
         * Checks whether this DOMBuilder is closed.
         *
         * @throws SAXException if this DOMBuilder is closed.
         */
        protected void checkClosed() throws SAXException {

            if (isClosed()) {
                throw new SAXException("content handler is closed.");    // NOI18N
            }
        }

        
Retrieves the document.
Returns:
Document/**
         * Retrieves the document.
         *
         * @return Document
         */
        public Document getDocument() {
            return this.document;
        }

        
Retrieves the current element. 

/**
         * Retrieves the current element. <p>
         */
        protected Element getCurrentElement() {
            return this.currentElement;
        }

        
Assigns the current element.
Params:
element – /**
         * Assigns the current element.
         * @param element
         */
        protected void setCurrentElement(Element element) {
            this.currentElement = element;
        }

        
Retrieves the current node. 

/**
         * Retrieves the current node. <p>
         */
        protected Node getCurrentNode() {
            return this.currentNode;
        }

        
Assigns the current node. 

Params:
node – /**
         * Assigns the current node. <p>
         * @param node
         */
        protected void setCurrentNode(Node node) {
            this.currentNode = node;
        }
    }

    
Writes to a XMLStreamWriter from SAX events. /**
     * Writes to a {@link javax.xml.stream.XMLStreamWriter XMLStreamWriter}
     * from SAX events.
     */
    public static class SAX2XMLStreamWriter implements ContentHandler,
            Closeable {

        
Namespace declarations for an upcoming element.
/**
         * Namespace declarations for an upcoming element.
         */
        private List<QualifiedName> namespaces =
            new ArrayList<QualifiedName>();

        
Whether this object is closed.
/**
         * Whether this object is closed.
         */
        private boolean closed;

        
This object's SAX locator.
/**
         * This object's SAX locator.
         */
        private Locator locator;

        
XML stream writer where events are pushed.
/**
         * XML stream writer where events are pushed.
         */
        private XMLStreamWriter writer;

        
Constructs a new SAX2XMLStreamWriter that writes SAX events to the
designated XMLStreamWriter.
Params:
writer – the writer to which to write SAX events/**
         * Constructs a new SAX2XMLStreamWriter that writes SAX events to the
         * designated XMLStreamWriter.
         *
         * @param writer the writer to which to write SAX events
         */
        public SAX2XMLStreamWriter(XMLStreamWriter writer) {

            if (writer == null) {
                throw new NullPointerException("writer");
            }
            this.writer = writer;
        }

        
Receive notification of the beginning of a document.
The SAX parser will invoke this method only once, before any other event callbacks (except for 
setDocumentLocator).
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception
See Also:
endDocument/**
         * Receive notification of the beginning of a document.
         *
         * <p>The SAX parser will invoke this method only once, before any
         * other event callbacks (except for {@link #setDocumentLocator
         * setDocumentLocator}).</p>
         *
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         * @see #endDocument
         */
        public void startDocument() throws SAXException {

            checkClosed();

            try {
                this.writer.writeStartDocument();
            } catch (XMLStreamException e) {
                throw new SAXException(e);
            }
        }

        
Receive notification of the end of a document.
There is an apparent contradiction between the documentation for this method and the documentation for ErrorHandler.fatalError. Until this ambiguity is resolved in a future major release, clients should make no assumptions about whether endDocument() will or will not be invoked when the parser has reported a fatalError() or thrown an exception.
The SAX parser will invoke this method only once, and it will
be the last method invoked during the parse.  The parser shall
not invoke this method until it has either abandoned parsing
(because of an unrecoverable error) or reached the end of
input.
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception
See Also:
startDocument/**
         * Receive notification of the end of a document.
         *
         * <p><strong>There is an apparent contradiction between the
         * documentation for this method and the documentation for {@link
         * org.xml.sax.ErrorHandler#fatalError}.  Until this ambiguity is
         * resolved in a future major release, clients should make no
         * assumptions about whether endDocument() will or will not be
         * invoked when the parser has reported a fatalError() or thrown
         * an exception.</strong></p>
         *
         * <p>The SAX parser will invoke this method only once, and it will
         * be the last method invoked during the parse.  The parser shall
         * not invoke this method until it has either abandoned parsing
         * (because of an unrecoverable error) or reached the end of
         * input.</p>
         *
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         * @see #startDocument
         */
        public void endDocument() throws SAXException {

            checkClosed();

            try {
                this.writer.writeEndDocument();
                this.writer.flush();
            } catch (XMLStreamException e) {
                throw new SAXException(e);
            }
        }

        
Receive notification of character data.
The Parser will call this method to report each chunk of
character data.  SAX parsers may return all contiguous character
data in a single chunk, or they may split it into several
chunks; however, all of the characters in any single event
must come from the same external entity so that the Locator
provides useful information.
The application must not attempt to read from the array
outside of the specified range.
Individual characters may consist of more than one Java
char value.  There are two important cases where this
happens, because characters can't be represented in just sixteen bits.
In one case, characters are represented in a Surrogate Pair,
using two special Unicode values. Such characters are in the so-called
"Astral Planes", with a code point above U+FFFF.  A second case involves
composite characters, such as a base character combining with one or
more accent characters. 
 Your code should not assume that algorithms using
char-at-a-time idioms will be working in character
units; in some cases they will split characters.  This is relevant
wherever XML permits arbitrary characters, such as attribute values,
processing instruction data, and comments as well as in data reported
from this method.  It's also generally relevant whenever Java code
manipulates internationalized text; the issue isn't unique to XML.
Note that some parsers will report whitespace in element content using the ignorableWhitespace method rather than this one (validating parsers must
do so).
Params:
ch – the characters from the XML document
start – the start position in the array
length – the number of characters to read from the array
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception
See Also:
ignorableWhitespace
Locator/**
         * Receive notification of character data.
         *
         * <p>The Parser will call this method to report each chunk of
         * character data.  SAX parsers may return all contiguous character
         * data in a single chunk, or they may split it into several
         * chunks; however, all of the characters in any single event
         * must come from the same external entity so that the Locator
         * provides useful information.</p>
         *
         * <p>The application must not attempt to read from the array
         * outside of the specified range.</p>
         *
         * <p>Individual characters may consist of more than one Java
         * <code>char</code> value.  There are two important cases where this
         * happens, because characters can't be represented in just sixteen bits.
         * In one case, characters are represented in a <em>Surrogate Pair</em>,
         * using two special Unicode values. Such characters are in the so-called
         * "Astral Planes", with a code point above U+FFFF.  A second case involves
         * composite characters, such as a base character combining with one or
         * more accent characters. </p>
         *
         * <p> Your code should not assume that algorithms using
         * <code>char</code>-at-a-time idioms will be working in character
         * units; in some cases they will split characters.  This is relevant
         * wherever XML permits arbitrary characters, such as attribute values,
         * processing instruction data, and comments as well as in data reported
         * from this method.  It's also generally relevant whenever Java code
         * manipulates internationalized text; the issue isn't unique to XML.</p>
         *
         * <p>Note that some parsers will report whitespace in element
         * content using the {@link #ignorableWhitespace ignorableWhitespace}
         * method rather than this one (validating parsers <em>must</em>
         * do so).</p>
         *
         * @param ch the characters from the XML document
         * @param start the start position in the array
         * @param length the number of characters to read from the array
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         * @see #ignorableWhitespace
         * @see org.xml.sax.Locator
         */
        public void characters(char[] ch, int start,
                               int length) throws SAXException {

            checkClosed();

            try {
                this.writer.writeCharacters(ch, start, length);
            } catch (XMLStreamException e) {
                throw new SAXException(e);
            }
        }

        
Receive notification of the beginning of an element.
The Parser will invoke this method at the beginning of every element in the XML document; there will be a corresponding endElement event for every startElement event (even when the element is empty). All of the element's content will be reported, in order, before the corresponding endElement event.
This event allows up to three name components for each
element:

the Namespace URI;
the local name; and
the qualified (prefixed) name.

Any or all of these may be provided, depending on the
values of the http://xml.org/sax/features/namespaces
and the http://xml.org/sax/features/namespace-prefixes
properties:

the Namespace URI and local name are required when
the namespaces property is true (the default), and are
optional when the namespaces property is false (if one is
specified, both must be);
the qualified name is required when the namespace-prefixes property
is true, and is optional when the namespace-prefixes property
is false (the default).

Note that the attribute list provided will contain only
attributes with explicit values (specified or defaulted):
#IMPLIED attributes will be omitted.  The attribute list
will contain attributes used for Namespace declarations
(xmlns* attributes) only if the
http://xml.org/sax/features/namespace-prefixes
property is true (it is false by default, and support for a
true value is optional).
Like characters(), attribute values may have characters that need more than one char value.  
Params:
namespaceURI – the Namespace URI, or the empty string if the
       element has no Namespace URI or if Namespace
       processing is not being performed
localName – the local name (without prefix), or the
       empty string if Namespace processing is not being
       performed
qName – the qualified name (with prefix), or the
       empty string if qualified names are not available
atts – the attributes attached to the element.  If
       there are no attributes, it shall be an empty
       Attributes object.  The value of this object after
       startElement returns is undefined
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception
See Also:
endElement
Attributes
AttributesImpl/**
         * Receive notification of the beginning of an element.
         *
         * <p>The Parser will invoke this method at the beginning of every
         * element in the XML document; there will be a corresponding
         * {@link #endElement endElement} event for every startElement event
         * (even when the element is empty). All of the element's content will be
         * reported, in order, before the corresponding endElement
         * event.</p>
         *
         * <p>This event allows up to three name components for each
         * element:</p>
         *
         * <ol>
         * <li>the Namespace URI;</li>
         * <li>the local name; and</li>
         * <li>the qualified (prefixed) name.</li>
         * </ol>
         *
         * <p>Any or all of these may be provided, depending on the
         * values of the <var>http://xml.org/sax/features/namespaces</var>
         * and the <var>http://xml.org/sax/features/namespace-prefixes</var>
         * properties:</p>
         *
         * <ul>
         * <li>the Namespace URI and local name are required when
         * the namespaces property is <var>true</var> (the default), and are
         * optional when the namespaces property is <var>false</var> (if one is
         * specified, both must be);</li>
         * <li>the qualified name is required when the namespace-prefixes property
         * is <var>true</var>, and is optional when the namespace-prefixes property
         * is <var>false</var> (the default).</li>
         * </ul>
         *
         * <p>Note that the attribute list provided will contain only
         * attributes with explicit values (specified or defaulted):
         * #IMPLIED attributes will be omitted.  The attribute list
         * will contain attributes used for Namespace declarations
         * (xmlns* attributes) only if the
         * <code>http://xml.org/sax/features/namespace-prefixes</code>
         * property is true (it is false by default, and support for a
         * true value is optional).</p>
         *
         * <p>Like {@link #characters characters()}, attribute values may have
         * characters that need more than one <code>char</code> value.  </p>
         *
         * @param namespaceURI the Namespace URI, or the empty string if the
         *        element has no Namespace URI or if Namespace
         *        processing is not being performed
         * @param localName the local name (without prefix), or the
         *        empty string if Namespace processing is not being
         *        performed
         * @param qName the qualified name (with prefix), or the
         *        empty string if qualified names are not available
         * @param atts the attributes attached to the element.  If
         *        there are no attributes, it shall be an empty
         *        Attributes object.  The value of this object after
         *        startElement returns is undefined
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         * @see #endElement
         * @see org.xml.sax.Attributes
         * @see org.xml.sax.helpers.AttributesImpl
         */
        public void startElement(String namespaceURI, String localName,
                                 String qName,
                                 Attributes atts) throws SAXException {

            checkClosed();

            try {
                int    qi     = qName.indexOf(':');
                String prefix = (qi > 0) ? qName.substring(0, qi)
                        : "";

                this.writer.writeStartElement(prefix, localName, namespaceURI);

                int length = namespaces.size();

                for (int i = 0; i < length; i++) {
                    QualifiedName ns = namespaces.get(i);

                    this.writer.writeNamespace(ns.prefix, ns.namespaceName);
                }
                namespaces.clear();

                length = atts.getLength();

                for (int i = 0; i < length; i++) {
                    this.writer.writeAttribute(atts.getURI(i),
                            atts.getLocalName(i), atts.getValue(i));
                }
            } catch (XMLStreamException e) {
                throw new SAXException(e);
            }
        }

        
Receive notification of the end of an element.
The SAX parser will invoke this method at the end of every element in the XML document; there will be a corresponding startElement event for every endElement event (even when the element is empty).
For information on the names, see startElement.
Params:
namespaceURI – the Namespace URI, or the empty string if the
       element has no Namespace URI or if Namespace
       processing is not being performed
localName – the local name (without prefix), or the
       empty string if Namespace processing is not being
       performed
qName – the qualified XML name (with prefix), or the
       empty string if qualified names are not available
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception/**
         * Receive notification of the end of an element.
         *
         * <p>The SAX parser will invoke this method at the end of every
         * element in the XML document; there will be a corresponding
         * {@link #startElement startElement} event for every endElement
         * event (even when the element is empty).</p>
         *
         * <p>For information on the names, see startElement.</p>
         *
         * @param namespaceURI the Namespace URI, or the empty string if the
         *        element has no Namespace URI or if Namespace
         *        processing is not being performed
         * @param localName the local name (without prefix), or the
         *        empty string if Namespace processing is not being
         *        performed
         * @param qName the qualified XML name (with prefix), or the
         *        empty string if qualified names are not available
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         */
        public void endElement(String namespaceURI, String localName,
                               String qName) throws SAXException {

            checkClosed();

            try {
                this.writer.writeEndElement();
            } catch (XMLStreamException e) {
                throw new SAXException(e);
            }
        }

        
Begin the scope of a prefix-URI Namespace mapping.
The information from this event is not necessary for
normal Namespace processing: the SAX XML reader will
automatically replace prefixes for element and attribute
names when the http://xml.org/sax/features/namespaces
feature is true (the default).
There are cases, however, when applications need to
use prefixes in character data or in attribute values,
where they cannot safely be expanded automatically; the
start/endPrefixMapping event supplies the information
to the application to expand prefixes in those contexts
itself, if necessary.
Note that start/endPrefixMapping events are not guaranteed to be properly nested relative to each other: all startPrefixMapping events will occur immediately before the corresponding startElement event, and all endPrefixMapping events will occur immediately after the corresponding endElement event, but their order is not otherwise guaranteed.
There should never be start/endPrefixMapping events for the
"xml" prefix, since it is predeclared and immutable.
Params:
prefix – the Namespace prefix being declared.
     An empty string is used for the default element namespace,
     which has no prefix.
uri – the Namespace URI the prefix is mapped to
Throws:
SAXException – the client may throw
           an exception during processing
See Also:
endPrefixMapping
startElement/**
         * Begin the scope of a prefix-URI Namespace mapping.
         *
         * <p>The information from this event is not necessary for
         * normal Namespace processing: the SAX XML reader will
         * automatically replace prefixes for element and attribute
         * names when the <code>http://xml.org/sax/features/namespaces</code>
         * feature is <var>true</var> (the default).</p>
         *
         * <p>There are cases, however, when applications need to
         * use prefixes in character data or in attribute values,
         * where they cannot safely be expanded automatically; the
         * start/endPrefixMapping event supplies the information
         * to the application to expand prefixes in those contexts
         * itself, if necessary.</p>
         *
         * <p>Note that start/endPrefixMapping events are not
         * guaranteed to be properly nested relative to each other:
         * all startPrefixMapping events will occur immediately before the
         * corresponding {@link #startElement startElement} event,
         * and all {@link #endPrefixMapping endPrefixMapping}
         * events will occur immediately after the corresponding
         * {@link #endElement endElement} event,
         * but their order is not otherwise
         * guaranteed.</p>
         *
         * <p>There should never be start/endPrefixMapping events for the
         * "xml" prefix, since it is predeclared and immutable.</p>
         *
         * @param prefix the Namespace prefix being declared.
         *      An empty string is used for the default element namespace,
         *      which has no prefix.
         * @param uri the Namespace URI the prefix is mapped to
         * @throws org.xml.sax.SAXException the client may throw
         *            an exception during processing
         * @see #endPrefixMapping
         * @see #startElement
         */
        public void startPrefixMapping(String prefix,
                                       String uri) throws SAXException {

            checkClosed();

            try {
                this.writer.setPrefix(prefix, uri);
                namespaces.add(new QualifiedName(prefix, uri));
            } catch (XMLStreamException e) {
                throw new SAXException(e);
            }
        }

        
End the scope of a prefix-URI mapping.
See startPrefixMapping for details. These events will always occur immediately after the corresponding endElement event, but the order of endPrefixMapping events is not otherwise guaranteed.
Params:
prefix – the prefix that was being mapped.
     This is the empty string when a default mapping scope ends.
Throws:
SAXException – the client may throw
           an exception during processing
See Also:
startPrefixMapping
endElement/**
         * End the scope of a prefix-URI mapping.
         *
         * <p>See {@link #startPrefixMapping startPrefixMapping} for
         * details.  These events will always occur immediately after the
         * corresponding {@link #endElement endElement} event, but the order of
         * {@link #endPrefixMapping endPrefixMapping} events is not otherwise
         * guaranteed.</p>
         *
         * @param prefix the prefix that was being mapped.
         *      This is the empty string when a default mapping scope ends.
         * @throws org.xml.sax.SAXException the client may throw
         *            an exception during processing
         * @see #startPrefixMapping
         * @see #endElement
         */
        public void endPrefixMapping(String prefix) throws SAXException {

            checkClosed();

            //
        }

        
Receive notification of ignorable whitespace in element content.
Validating Parsers must use this method to report each chunk
of whitespace in element content (see the W3C XML 1.0
recommendation, section 2.10): non-validating parsers may also
use this method if they are capable of parsing and using
content models.
SAX parsers may return all contiguous whitespace in a single
chunk, or they may split it into several chunks; however, all of
the characters in any single event must come from the same
external entity, so that the Locator provides useful
information.
The application must not attempt to read from the array
outside of the specified range.
Params:
ch – the characters from the XML document
start – the start position in the array
length – the number of characters to read from the array
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception
See Also:
characters/**
         * Receive notification of ignorable whitespace in element content.
         *
         * <p>Validating Parsers must use this method to report each chunk
         * of whitespace in element content (see the W3C XML 1.0
         * recommendation, section 2.10): non-validating parsers may also
         * use this method if they are capable of parsing and using
         * content models.</p>
         *
         * <p>SAX parsers may return all contiguous whitespace in a single
         * chunk, or they may split it into several chunks; however, all of
         * the characters in any single event must come from the same
         * external entity, so that the Locator provides useful
         * information.</p>
         *
         * <p>The application must not attempt to read from the array
         * outside of the specified range.</p>
         *
         * @param ch the characters from the XML document
         * @param start the start position in the array
         * @param length the number of characters to read from the array
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         * @see #characters
         */
        public void ignorableWhitespace(char[] ch, int start,
                                        int length) throws SAXException {
            characters(ch, start, length);
        }

        
Receive notification of a processing instruction.
The Parser will invoke this method once for each processing
instruction found: note that processing instructions may occur
before or after the main document element.
A SAX parser must never report an XML declaration (XML 1.0,
section 2.8) or a text declaration (XML 1.0, section 4.3.1)
using this method.
Like characters(), processing instruction data may have characters that need more than one char
value. 
Params:
target – the processing instruction target
data – the processing instruction data, or null if
       none was supplied.  The data does not include any
       whitespace separating it from the target
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception/**
         * Receive notification of a processing instruction.
         *
         * <p>The Parser will invoke this method once for each processing
         * instruction found: note that processing instructions may occur
         * before or after the main document element.</p>
         *
         * <p>A SAX parser must never report an XML declaration (XML 1.0,
         * section 2.8) or a text declaration (XML 1.0, section 4.3.1)
         * using this method.</p>
         *
         * <p>Like {@link #characters characters()}, processing instruction
         * data may have characters that need more than one <code>char</code>
         * value. </p>
         *
         * @param target the processing instruction target
         * @param data the processing instruction data, or null if
         *        none was supplied.  The data does not include any
         *        whitespace separating it from the target
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         */
        public void processingInstruction(String target,
                String data) throws SAXException {

            checkClosed();

            try {
                this.writer.writeProcessingInstruction(target, data);
            } catch (XMLStreamException e) {
                throw new SAXException(e);
            }
        }

        
Receive an object for locating the origin of SAX document events.
SAX parsers are strongly encouraged (though not absolutely
required) to supply a locator: if it does so, it must supply
the locator to the application by invoking this method before
invoking any of the other methods in the ContentHandler
interface.
The locator allows the application to determine the end
position of any document-related event, even if the parser is
not reporting an error.  Typically, the application will
use this information for reporting its own errors (such as
character content that does not match an application's
business rules).  The information returned by the locator
is probably not sufficient for use with a search engine.
Note that the locator will return correct information only during the invocation SAX event callbacks after startDocument returns and before endDocument is called. The application should not attempt to use it at any other time.
Params:
locator – an object that can return the location of
               any SAX document event
See Also:
Locator/**
         * Receive an object for locating the origin of SAX document events.
         *
         * <p>SAX parsers are strongly encouraged (though not absolutely
         * required) to supply a locator: if it does so, it must supply
         * the locator to the application by invoking this method before
         * invoking any of the other methods in the ContentHandler
         * interface.</p>
         *
         * <p>The locator allows the application to determine the end
         * position of any document-related event, even if the parser is
         * not reporting an error.  Typically, the application will
         * use this information for reporting its own errors (such as
         * character content that does not match an application's
         * business rules).  The information returned by the locator
         * is probably not sufficient for use with a search engine.</p>
         *
         * <p>Note that the locator will return correct information only
         * during the invocation SAX event callbacks after
         * {@link #startDocument startDocument} returns and before
         * {@link #endDocument endDocument} is called.  The
         * application should not attempt to use it at any other time.</p>
         *
         * @param locator an object that can return the location of
         *                any SAX document event
         * @see org.xml.sax.Locator
         */
        public void setDocumentLocator(Locator locator) {
            this.locator = locator;
        }

        
Retrieves the Locator. 

Returns:
the Locator/**
         * Retrieves the Locator. <p>
         * @return the Locator
         */
        public Locator getDocumentLocator() {
            return this.locator;
        }

        
Receive notification of a skipped entity.
This is not called for entity references within markup constructs
such as element start tags or markup declarations.  (The XML
recommendation requires reporting skipped external entities.
SAX also reports internal entity expansion/non-expansion, except
within markup constructs.)
The Parser will invoke this method each time the entity is
skipped.  Non-validating processors may skip entities if they
have not seen the declarations (because, for example, the
entity was declared in an external DTD subset).  All processors
may skip external entities, depending on the values of the
http://xml.org/sax/features/external-general-entities
and the
http://xml.org/sax/features/external-parameter-entities
properties.
Params:
name – the name of the skipped entity.  If it is a
       parameter entity, the name will begin with '%', and if
       it is the external DTD subset, it will be the string
       "[dtd]"
Throws:
SAXException – any SAX exception, possibly
           wrapping another exception/**
         * Receive notification of a skipped entity.
         * This is not called for entity references within markup constructs
         * such as element start tags or markup declarations.  (The XML
         * recommendation requires reporting skipped external entities.
         * SAX also reports internal entity expansion/non-expansion, except
         * within markup constructs.)
         *
         * <p>The Parser will invoke this method each time the entity is
         * skipped.  Non-validating processors may skip entities if they
         * have not seen the declarations (because, for example, the
         * entity was declared in an external DTD subset).  All processors
         * may skip external entities, depending on the values of the
         * <code>http://xml.org/sax/features/external-general-entities</code>
         * and the
         * <code>http://xml.org/sax/features/external-parameter-entities</code>
         * properties.</p>
         *
         * @param name the name of the skipped entity.  If it is a
         *        parameter entity, the name will begin with '%', and if
         *        it is the external DTD subset, it will be the string
         *        "[dtd]"
         * @throws org.xml.sax.SAXException any SAX exception, possibly
         *            wrapping another exception
         */
        public void skippedEntity(String name) throws SAXException {

            checkClosed();

            //
        }

        public void comment(char[] ch, int start,
                            int length) throws SAXException {

            checkClosed();

            try {
                this.writer.writeComment(new String(ch, start, length));
            } catch (XMLStreamException e) {
                throw new SAXException(e);
            }
        }

        public XMLStreamWriter getWriter() {
            return this.writer;
        }

        protected List<QualifiedName> getNamespaces() {
            return this.namespaces;
        }

        
Closes this object.
/**
         * Closes this object.
         */
        public void close() throws IOException {

            if (!this.closed) {
                this.closed = true;

                try {
                    this.writer.close();
                } catch (XMLStreamException e) {
                    throw new IOException(e);
                } finally {
                    this.writer     = null;
                    this.locator    = null;
                    this.namespaces = null;
                }
            }
        }

        
Retrieves whether this object is closed.
Returns:
boolean/**
         * Retrieves whether this object is closed.
         *
         * @return boolean
         */
        public boolean isClosed() {
            return this.closed;
        }

        
Checks whether this object is closed.
Throws:
SAXException – if this DOMBuilder is closed./**
         * Checks whether this object is closed.
         *
         * @throws SAXException if this DOMBuilder is closed.
         */
        protected void checkClosed() throws SAXException {

            if (isClosed()) {
                throw new SAXException("content handler is closed.");    // NOI18N
            }
        }

        // --------------------- internal implementation -----------------------
        protected static class QualifiedName {

            public final String namespaceName;
            public final String prefix;

            public QualifiedName(final String prefix,
                                 final String namespaceName) {
                this.prefix        = prefix;
                this.namespaceName = namespaceName;
            }
        }
    }
}