XMLPARSE operator

XMLPARSE is a SQL/XML operator that you use to parse a character string expression into a Derby XML value.

You can use the result of this operator temporarily or you can store the result permanently in Derby XML columns. Whether temporary or permanent, you can use the XML value as an input to the other Derby XML operators, such as XMLEXISTS and XMLQUERY.

Syntax

XMLPARSE ( DOCUMENT stringValueExpression PRESERVE WHITESPACE )

DOCUMENT: Required keyword that describes the type of XML input that Derby can parse. Derby can only parse string expressions that constitute well-formed XML documents. This is because Derby uses a JAXP parser to parse all string values. The JAXP parser expects the stringValueExpression to constitute a well-formed XML document. If the string does not constitute a well-formed document, JAXP throws an error. Derby catches the error and throws the error as a SQLException.
stringValueExpression: Any expression that evaluates to a SQL character type, such as CHAR, VARCHAR, LONG VARCHAR, or CLOB. The stringValueExpression argument can also be a parameter. You must use the CAST function when you specify the parameter to indicate the type of value that is bound into the parameter. Derby must verify that the parameter is the correct data type before the value is parsed as an XML document. If a parameter is specified without the CAST function, or if the CAST is to a non-character datatype, Derby throws an error.
PRESERVE WHITESPACE: Required keywords that describe how Derby handles whitespace between consecutive XML nodes. When the PRESERVE WHITESPACE keywords are used, Derby preserves whitespace as dictated by the SQL/XML rules for preserving whitespace.

For more information on what constitutes a well-formed XML document, see the following specification: http://www.w3.org/TR/REC-xml/#sec-well-formed.

Restriction: The SQL/XML standard dictates that the argument to the XMLPARSE operator can also be a binary string. However, Derby only supports character string input for the XMLPARSE operator.

Examples

To insert a simple XML document into the xcol XML column in the x_table table, use the following statement:

INSERT INTO x_table VALUES (1, XMLPARSE(DOCUMENT '
        <roster>
          <student age="18">AB</student>
          <student age="23">BC</student>
          <student>NOAGE</student>
        </roster>'
      PRESERVE WHITESPACE)
    )

To insert a large XML document into the xcol XML column in the x_table table, from JDBC use the following statement:

INSERT INTO x_table VALUES(2, XMLPARSE (DOCUMENT 
        CAST (? AS CLOB) 
      PRESERVE WHITESPACE)
    )

You should bind into the statement using the setCharacterStream() method, or any other JDBC setXXX method that works for the CAST target type.

Usage note

Derby requires that a JAXP parser (such as Apache Xerces) and Apache Xalan are listed in the Java classpath for the XML functions to work. If either the JAXP parser or Xalan is missing from the classpath, attempts to use the XMLPARSE operator will result in an error. In some situations, you may need to take steps to place the parser and Xalan in your classpath. See "XML data types and operators" in the Derby Developer's Guide for details.