9
Package oracle.xml.sql.query

This chapter describes the Java classes for XML SQL Utility for Java, which are contained in the oracle.xml.sql.query package. XML SQL Utility for Java (XSU) generates and stores XML from SQL queries.

This chapter contains these sections:

Package oracle.xml.sql.query Description

The Java classes for XML SQL Utility for Java are contained in the oracle.xml.sql.query package. XML SQL Utility for Java (XSU) generates and stores XML data to and from the database from SQL queries or result sets or tables. It achieves data transformation by mapping canonically any SQL query result to XML, and vice versa.

See Also:

Chapter 8, "Package oracle.xml.sql.dml"

OracleXMLQuery Class

Description

The OracleXMLQuery class generates XML given an SQL query.

Syntax

public class OracleXMLQuery extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.xml.sql.query.OracleXMLQuery

Fields

Table 9-1 Summary of Fields of OracleXMLQuery

Field	Syntax	Description
DTD	public static final int DTD	Specifies that the DTD is to be generated
ERROR_TAG	public static final java.lang.String ERROR_TAG	Specifies the default tag name for the ERROR document
MAXROWS_ALL	public static final int MAXROWS_ALL	Specifies that all rows be included in the result
NONE	public static final int NONE	Specifies that no DTD is to be generated
ROW_TAG	public static final java.lang.String ROW_TAG	Specifies the default tag name for the ROW elements
ROWIDATTR_TAG	public static final java.lang.String ROWIDATTR_TAG	Specifies the default tag name for the ROW elements
ROWSET_TAG	public static final java.lang.String ROWSET_TAG	Specifies the default tag name for the document
SCHEMA	public static final int SCHEMA	Specifies that an XML schema is to be generated
SKIPROWS_ALL	public static final int SKIPROWS_ALL	Specifies that all rows be skipped in the result.

Methods

Table 9-2 Summary of Methods of OracleXMLQuery

Method	Description
OracleXMLQuery(),	Class constructor.
close(),	Closes open resources created by the Oracle XML engine.
getNumRowsProcessed(),	Returns the number of rows processed.
getXMLDOM(),	Transforms data into an XML document.
getXMLDOM(),	Transforms object-relational data, specified in the constructor, into an XML document.
getXMLMetaData(),	Returns the DTD or XMLSchema for the XML document.
getXMLSAX(),	Transforms object-relational data, specified in the constructor, into an XML document.
getXMLSchema(),	Generates XMLSchema(s) corresponding to the specified query.
getXMLString(),	Transforms object-relational data, specified in the constructor, into an XML document.
keepObjectOpen(),	Has the effect of turning on and off the persistency of objects from which XML data is retrieved.
removeXSLTParam(),	Removes the value of a top-level stylesheet parameter.
setCollIdAttrName(),	Sets the name of the id attribute of the collection element's separator tag.
setDataHeader(),	Sets the XML data header.
setDateFormat(),	Sets the format of the generated dates in the XML doc.
setEncoding(),	Sets the encoding processing instruction in the XML doc.
setErrorTag(),	Sets the tag to be used to enclose the XML error docs.
setException(),	Allows the user to pass in an exception to be handled by the XSU.
setMaxRows(),	Sets the maximum number of rows to be converted to XML.
setMetaHeader(),	Sets the XML meta header.
setRaiseException(),	Instructs the XSU whether to throw the raised exceptions.
setRaiseNoRowsException(),	Instructs the XSU whether to throw an `OracleXMLNoRowsException` when the generated XML doc is empty.
setRowIdAttrName(),	Sets the name of the id attribute of the row enclosing tag.
setRowIdAttrValue(),	Specifies the scalar column whose value will be assigned to the id attribute of the row enclosing tag.
setRowsetTag(),	Sets the tag to be used to enclose the XML dataset.
setSkipRows(),	Sets the number of rows to skip.
setSQLToXMLNameEscaping(),	Has the effect of turning on and off the escaping of XML tags in cases where mapped SQL object name would not make a valid XML identifier.
setStylesheetHeader(),	Sets the stylesheet header.
setXSLT(),	Registers an XSL transform to be applied to the generated XML.
setXSLTParam(),	Sets the value of a top-level stylesheet parameter.
useLowerCaseTagNames(),	Sets the tag names to lower case.
useNullAttributeIndicator(),	Specifies if `NULL`ness is indicated by a special XML attribute or by omitting the entity from the XML document.
useTypeForCollElemTag(),	Instructs the XSU to use the collection element's type name as the collection element's tag name.
useUpperCaseTagNames(),	Sets the tag names to upper case.

OracleXMLQuery()

Description

Class constructor for the OracleXMLQueryObject. The options are described in the following table.

Syntax	Description
public OracleXMLQuery( java.sql.Connection conn, java.sql.ResultSet rset);	Creates an OracleXMLQuery from a databse connection and a jdbc result set object.
public OracleXMLQuery( java.sql.Connection conn, java.lang.String query);	Creates an OracleXMLQuery from a databse connection and an SQL query string.
public OracleXMLQuery( oracle.xml.sql.dataset.OracleXMLDataSet dset);	Creates an OracleXMLQuery from a dataset.

Parameters

conn	database connection
rset	jdbc result set object
query	the SQL query string
dset	dataset

close()

Description

Closes any open resource, created by the OracleXML engine. This will not close for instance result set supplied by the user.

Syntax

public void close();

getNumRowsProcessed()

Description

Returns the number of rows processed.

Syntax

public long getNumRowsProcessed();

getXMLDOM()

Description

Transforms the object-relational data, specified in the constructor, into XML. Returns a representation of the XML document. The options are described in the following table.

Syntax	Description
public org.w3c.dom.Document getXMLDOM()	Returns a DOM representation of the XML document.
public org.w3c.dom.Document getXMLDOM( int metaType)	The argument is used to specify the type of XML metadata the XSU is to generate along with the XML. Currently this value is ignored, and no XML metadata is generated. Returns a string representation of the XML document.
public org.w3c.dom.Document getXMLDOM( org.w3c.dom.Node root)	If not `NULL`, the argument is considered the "root" element of the XML doc. Returns the string representation of the XML document.
public org.w3c.dom.Document getXMLDOM( org.w3c.dom.Node root, int metaType)	If not `NULL`, the `root` argument is considered the "root" element of the XML doc. The `metaType` argument is used to specify the type of XML metadata the XSU is to generate along with the XML. Currently this value is ignored, and no XML metadata is generated. Returns the string representation of the XML document.

Parameters

metaType	the type of XML metadata (NONE, SCHEMA)
root	root node to which to append the new XML

getXMLMetaData()

Description

This functions returns the DTD or the XMLSchema for the XML document which would have been generated by a getXML*() call, such as getXMLDOM(), getXMLSAX(), getXMLSchema(), or getXMLString().

Syntax

public java.lang.String getXMLMetaData( int metaType,

                    boolean withVer);

Parameters

metaType	Specifies the type of XML metadata to be generated (NONE or DTD).
withVer	Specifies whether to generate the version processing instruction

getXMLSAX()

Description

Transforms the object-relational data, specified in the constructor, into an XML document.

Syntax

public void getXMLSAX(org.xml.sax.ContentHandler sax);

Parameters

sax	ContentHandler object to be registered.

getXMLSchema()

Description

This methods generates the XML Schema(s) corresponding to the specified query; returns the XML Schema(s).

Syntax

public org.w3c.dom.Document[] getXMLSchema();

getXMLString()

Description

Transforms the object-relational data, specified in the constructor, into a XML document. Returns the string representation of the XML document. The options are described in the following table.

Syntax	Description
public java.lang.String getXMLString();	Takes no arguments.
public java.lang.String getXMLString( int metaType);	The `metaType` argument is used to specify the type of XML metadata the XSU is to generate along with the XML.
public java.lang.String getXMLString( org.w3c.dom.Node root);	If not `NULL`, the `root` argument, is considered the root element of the XML doc.
public java.lang.String getXMLString( org.w3c.dom.Node root, int metaType)	If not `NULL`, the `root` argument is considered the root element of the XML doc. The `metaType` argument is used to specify the type of XML metadata the XSU is to generate along with the XML. Note that if the `root` argument is non-`NULL`, no DTD is generated even if requested.

Parameters

metaType	The type of XML metadata (NONE, DTD, or SCHEMA, static fields of this class)
root	root node to which to append the new XML

keepObjectOpen()

Description

The default behavior for all the getXML*() functions which DO NOT TAKE in a ResultSet object, such as getXMLDOM(), getXMLSAX(), getXMLSchema(), or getXMLString(), is to close the ResultSet object and Statement objects at the end of the call. If the persistent feature is needed, where by calling getXML() repeatedly the next set of rows is obtained, this behavior must be turned off by calling this function with value TRUE. OracleXMLQuery would not close the ResultSet and Statement objects after the getXML() calls. To close the cursor state, the close() function must be called explicitly.

Syntax

public void keepObjectOpen( boolean alive);

Parameters

alive

Should the object be kept open?

removeXSLTParam()

Description

Removes the value of a top-level stylesheet parameter. NOTE: if no stylesheet is registered, this method is a no op.

Syntax

public void removeXSLTParam( String name);

Parameters

name	Parameter name

setCollIdAttrName()

Description

Sets the name of the id attribute of the collection element's separator tag. Passing NULL or an empty string causes the row id attribute to be omitted.

Syntax

public void setCollIdAttrName( String attrName);

Parameters

attrName

Attribute Name

setDataHeader()

Description

Sets the XML data header, the XML entity which is appended at the beginning of the query-generated XML entity (i.e., rowset). The two entities are enclosed by the tag specified via the docTag argument. The last data header specified is the one that is used. Passing in NULL for the header parameter unsets the data header.

Syntax

public void setDataHeader(  java.io.Reader header,

                    java.lang.String docTag);

Parameters

header	Header
docTag	Tag used to enclose the data header and the rowset

setDateFormat()

Description

Sets the format of the generated dates in the XML doc. The syntax of the date format pattern (i.e. the date mask), should conform to the requirements of the java.text.SimpleDateFormat class. Setting the mask to NULL or an empty string, unsets the date mask.

Syntax

public void setDateFormat( java.lang.String mask);

Parameters

mask	The data mask

setEncoding()

Description

Sets the encoding processing instruction (PI) in the XML doc. If NULL or an empty string are specified as the encoding, then the default characterset is specified in the encoding PI.

Syntax

public void setEncoding(java.lang.String enc)

Parameters

enc	Encoding of the CML doc (IANA name of encoding)

setErrorTag()

Description

Sets the tag to be used to enclose the XML error docs.

Syntax

public void setErrorTag( java.lang.String tag);

Parameters

tag

Tag name

setException()

Description

Allows the user to pass in an exception, and have the XSU handle it.

Syntax

public void setException( java.lang.Exception e);

Parameters

e	The exception to be processed by XSU

setMaxRows()

Description

Sets the maximum number of rows to be converted to XML. By default there is no maximum set. To explicitly specify no max, see MAXROWS_ALL field.

Syntax

public void setMaxRows( int rows);

Parameters

rows	Maximum number of rows to generate

setMetaHeader()

Description

Sets the XML meta header. When set, the header is inserted at the beginning of the metadata part (DTD or XMLSchema) of each XML document generated by this object. The last meta header specified is the one that is used. Setting the header to NULL or an empty string unsets the meta header.

Syntax

public void setMetaHeader( java.io.Reader header);

Parameters

header

Header

setRaiseException()

Description

Instructs the XSU whether to throw the raised exceptions. If this call isn't made, or if FALSE is passed to the flag argument, the XSU catches the SQL exceptions and generates an XML doc from the exception message.

Syntax

public void setRaiseException(boolean flag);

Parameters

flag	Should the raised exception be thrown?

setRaiseNoRowsException()

Description

Instructs the XSU whether to throw an OracleXMLNoRowsException when the generated XML doc is empty. By default, the exception is not thrown.

Syntax

public void setRaiseNoRowsException( boolean flag);

Parameters

flag	Should the `OracleXMLNoRowsException` be thrown if no data found?

setRowIdAttrName()

Description

Sets the name of the id attribute of the row enclosing tag. Passing NULL or an empty string causes the row id attribute to be omitted.

Syntax

public void setRowIdAttrName( java.lang.String attrName);

Parameters

attrName

Attribute name

setRowIdAttrValue()

Description

Specifies the scalar column whose value is to be assigned to the id attribute of the row enclosing tag. Passing NULL or an empty string causes the row id attribute to be assigned the row count value (i.e. 0, 1, 2, ...).

Syntax

public void setRowIdAttrValue( java.lang.String colName);

Parameters

colName

Column whose value will be assigned to the row id attribute

setRowsetTag()

Description

Sets the tag to be used to enclose the XML dataset.

Syntax

public void setRowsetTag( java.lang.String tag);

Parameters

tag

Tag name

setRowTag()

Description

Sets the tag to be used to enclose the XML element corresponding to a db. record.

Syntax

public void setRowTag( java.lang.String tag);

Parameters

tag

Tag name

setSkipRows()

Description

Sets the number of rows to skip. By default 0 rows are skipped. To skip all the rows use SKIPROWS_ALL.

Syntax

public void setSkipRows(int rows);

Parameters

rows	Number of rows to skip.

setSQLToXMLNameEscaping()

Description

This turns on or off escaping of XML tags in the case that the SQL object name, which is mapped to a XML identifier, is not a valid XML identifier.

Syntax

public void setSQLToXMLNameEscaping( boolean flag);

Parameters

flag	Whether to turn on SQL to XML identifier escaping.

setStylesheetHeader()

Description

Sets the stylesheet header (i.e. stylesheet processing instructions) in the generated XML doc. Passing NULL in the argument will unset the stylesheet header and the stylesheet type. The options are described in the following table.

Syntax	Description
public void setStylesheetHeader( java.lang.String uri);	Sets stylesheet header using the stylesheet URI.
public void setStylesheetHeader( java.lang.String uri, java.lang.String type);	Sets the stylesheet header using the stylesheet URI and the stylesheet type.

Parameters

uri	Stylesheet URI
type	Stylesheet type; defaults to 'text/xsl'

setXSLT()

Description

Registers a XSL transform to be applied to generated XML. If a stylesheet is already registered, it is replaced by the new one. To un-register the stylesheet, pass in NULL value for the argument. The options are described in the following table.

Syntax	Description
public void setXSLT( java.io.Reader stylesheet, java.lang.String ref);	The stylesheet parameter is passed in as the data.
public void setXSLT(j ava.lang.String stylesheet, java.lang.String ref);	The stylesheet parameter is passed in as a URI to the document.

Parameters

stylesheet	The stylesheet.
ref	URL for include, import and external entities.

setXSLTParam()

Description

Sets the value of a top-level stylesheet parameter. The parameter value is expected to be a valid XPath expression; therefore the string literal values have to be explicitly quoted). If no stylesheet is registered, this method is a no op.

Syntax

public void setXSLTParam( java.lang.String name,

                    java.lang.String value);

Parameters

name	Parameter name
value	Parameter value as an XPATH expression

useLowerCaseTagNames()

Description

This will set the case to be lower for all tag names. Note, make this call after all the desired tags have been set.

Syntax

public void useLowerCaseTagNames();

useNullAttributeIndicator()

Description

Specifies if NULLness is indicated by a special XML attribute or by omitting the entity from the XML document.

Syntax

public void useNullAttributeIndicator(boolean flag);

Parameters

flag	Should the attribute be used to indicate `NULL`?

useTypeForCollElemTag()

Description

By default, the tag name for elements of a collection is the collection's tag name followed by "_item". This method, when called with argument value of TRUE, instructs the XSU to use the collection element's type name as the collection element's tag name.

Syntax

public void useTypeForCollElemTag( boolean flag);

Parameters

flag	Should the column element type be used to indicate its tag name?

useUpperCaseTagNames()

Description

Sets all tag names to upper case. This call should be made only after all the desired tags have been set.

Syntax

public void useUpperCaseTagNames();

OracleXMLSQLException Class

Description

Class for managing all exceptions thrown by the XSU.

Syntax

public class OracleXMLSQLException extends java.lang.RuntimeException
 
java.lang.Object
  |
  +--java.lang.Throwable
        |
        +--java.lang.Exception
              |
              +--java.lang.RuntimeException
                    |
                    +--oracle.xml.sql.OracleXMLSQLException

Direct Subclasses of OracleXMLSQLException

OracleXMLSQLNoRowsException Class

Implemented Interfaces of OracleXMLSQLException

java.io.Serializable

Methods of OracleXMLSQLException

Table 9-3 Summary of Methods of OracleXMLSQLException

Method	Description
OracleXMLSQLException()	Creates a new OracleXMLSQLException.
getErrorCode()	Returns the SQL error code thrown.
getParentException()	Returns the original exception, if there was one; otherwise, returns `NULL`.
getXMLErrorString()	Prints XML error string with given error tag name.
getXMLSQLErrorString()	Prints the SQL parameters in the error message.
setErrorTag()	Sets error tag used to generate XML error reports.

OracleXMLSQLException()

Description

Creates a new OracleXMLSQLException. The options are described in the following table.

Syntax	Description
public OracleXMLSQLException( java.lang.Exception e);	Sets the parent exception as passed in.
public OracleXMLSQLException( java.lang.Exception e, java.lang.String errorTagName);	Sets the error tag name as passed in.
public OracleXMLSQLException( java.lang.String message);	Sets the error message to be returned.
public OracleXMLSQLException( java.lang.String message, java.lang.Exception e);	Sets the parent exception and the error message to be returned.
public OracleXMLSQLException( java.lang.String message, java.lang.Exception e, java.lang.String errorTagName);	Sets the error message, parent exception, and error tag to be used.
public OracleXMLSQLException( java.lang.String message, int errorCode);	Sets the error message and SQL error code.
public OracleXMLSQLException( java.lang.String message, int errorCode, java.lang.String errorTagName);	Sets the eror message, SQL error code, and the error tag to be used.
public OracleXMLSQLException(j ava.lang.String message, java.lang.String errorTagName);	Sets the error message and the error tag to be used.

Parameters

e	The exception.
errorTagName	The error tag name.
message	The error message.
errorCode	the SQL error code.

getErrorCode()

Description

Returns the SQL error code thrown.

Syntax

public int getErrorCode();

getParentException()

Description

Returns the original exception, if there was one; otherwise, returns NULL.

Syntax

public java.lang.Exception getParentException();

getXMLErrorString()

Description

Prints the XML error string with the given error tag name.

Syntax

public java.lang.String getXMLErrorString();

getXMLSQLErrorString()

Description

Prints the SQL parameters as well in the error message.

Syntax

public java.lang.String getXMLSQLErrorString();

setErrorTag()

Description

Sets the error tag name, which is then used by getXMLErrorString() and getXMLSQLErrorString()to generate XML error reports.

Syntax

public void setErrorTag(java.lang.String tagName);

Parameters

tagName

The tag name of the error

OracleXMLSQLNoRowsException Class

Description

The exception that can be thrown when no rows are found.

Syntax

public class OracleXMLSQLNoRowsException extends OracleXMLSQLException

java.lang.Object
 |
 +--java.lang.Throwable
     |
     +--java.lang.Exception
          |
          +--java.lang.RuntimeException
               |
              +--OracleXMLSQLException
                   |
                   +--oracle.xml.sql.OracleXMLSQLNoRowsException

Implemented Interfaces of OracleXMLSQLNoRowsException

java.io.Serializable

Methods

OracleXMLSQLNoRowsException()

Creates a new OracleXMLSQLNoRowsException. The options are described in the following table.

Syntax	Description
public OracleXMLSQLNoRowsException();	Default class constructor.
public OracleXMLSQLNoRowsException( java.lang.String errorTag);	Sets the error tag as the passed in argument.

Parameters

errorTag

The error tag.

Inherited Members of OracleXMLSQLNoRowsException

Table 9-4 Summary of Inherited Members of OracleCMLSQLNoRowsException

Member	Inherited from
getErrorCode()	OracleXMLSQLException Class
getParentException()	OracleXMLSQLException Class
getXMLErrorString()	OracleXMLSQLException Class
getXMLSQLErrorString()	OracleXMLSQLException Class
setErrorTag()	OracleXMLSQLException Class

9 Package oracle.xml.sql.query

Package oracle.xml.sql.query Description

OracleXMLQuery Class

Description

Syntax

Fields

Table 9-1 Summary of Fields of OracleXMLQuery

Methods

Table 9-2 Summary of Methods of OracleXMLQuery

OracleXMLQuery()

Description

Parameters

close()

Description

Syntax

getNumRowsProcessed()

Description

Syntax

getXMLDOM()

Description

Parameters

getXMLMetaData()

Description

Syntax

Parameters

getXMLSAX()

Description

Syntax

Parameters

getXMLSchema()

Description

Syntax

getXMLString()

Description

Parameters

keepObjectOpen()

Description

Syntax

Parameters

removeXSLTParam()

Description

Syntax

Parameters

setCollIdAttrName()

Description

Syntax

Parameters

setDataHeader()

Description

Syntax

Parameters

setDateFormat()

Description

Syntax

Parameters

setEncoding()

Description

Syntax

Parameters

setErrorTag()

Description

Syntax

Parameters

setException()

Description

Syntax

Parameters

setMaxRows()

Description

Syntax

Parameters

setMetaHeader()

Description

Syntax

Parameters

setRaiseException()

Description

Syntax

Parameters

setRaiseNoRowsException()

9
Package oracle.xml.sql.query