8
XML SQL Utility for Java

XML SQL Utility for Java (XSU) generates and stores XML from SQL queries.

This chapter contains descriptions of the following XSU classes:

• OracleXMLQuery Class
• OracleXMLSave Class
• OracleXMLSQLException Class
• OracleXMLSQLNoRowsException Class

  See Also: Oracle9i XML Developer's Kits Guide - XDK Oracle9i Supplied Java Packages Reference

---

OracleXMLQuery Class

---

Description of OracleXMLQuery

The OracleXMLQuery class generates XML given an SQL query.

---

Syntax of Oracle XMLQuery

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

---

Fields of OracleXMLQuery

Table 8-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 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 String ROW_TAG	Specifies the default tag name for the ROW elements
ROWIDATTR_TAG	public static final String ROWIDATTR_TAG	Specifies the default tag name for the ROW elements
ROWSET_TAG	public static final 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 of OracleXMLQuery

Table 8-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.
getXMLMetaData()	Transforms object-relational data, specified in the constructor, into an XML document.
getXMLSAX()	Returns the DTD or XMLSchema for the XML document.
getXMLSchema()	Transforms object-relational data, specified in the constructor, into an XML document.
getXMLString()	Generates XMLSchema(s) corresponding to the specified query.
keepObjectOpen()	Transforms object-relational data, specified in the constructor, into an XML document.
removeXSLTParam()	Has the effect of turning on and off the persistency of objects from which XML data is retrieved.
setCollIdAttrName()	Removes the value of a top-level stylesheet parameter.
setDataHeader()	Sets the name of the id attribute of the collection element's separator tag.
setDateFormat()	Sets the XML data header.
setEncoding()	Sets the format of the generated dates in the XML doc.
setErrorTag()	Sets the encoding processing instruction in the XML doc.
setException()	Sets the tag to be used to enclose the XML error docs.
setMaxRows()	Allows the user to pass in an exception to be handled by the XSU.
setMetaHeader()	Sets the maximum number of rows to be converted to XML.
setRaiseException()	Sets the XML meta header.
setRaiseNoRowsException()	Instructs the XSU whether to throw the raised exceptions.
setRowIdAttrName()	Instructs the XSU whether to throw an OracleXMLNoRowsException when the generated XML doc is empty.
setRowIdAttrValue()	Sets the name of the id attribute of the row enclosing tag.
setRowsetTag()	Specifies the scalar column whose value will be assigned to the id attribute of the row enclosing tag.
setRowTag()	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 NULLness 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, 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.

Parameter	Description
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.

Parameter	Description
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 String getXMLMetaData( int metaType,
                              boolean withVer);

Parameter	Description
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);

Parameter	Description
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 String getXMLString();	Takes no arguments.
public 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 String getXMLString( org.w3c.dom.Node root);	If not NULL, the root argument, is considered the root element of the XML doc.
public 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.

Parameter	Description
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);

Parameter	Description
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);

Parameter	Description
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);

Parameter	Description
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, the rowset. The two entities are enclosed by the tag specified through 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,
                           String docTag);

Parameter	Description
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, 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( String mask);

Parameter	Description
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( String enc)

Parameter	Description
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( String tag);

Parameter	Description
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);

Parameter	Description
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);

Parameter	Description
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);

Parameter	Description
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);

Parameter	Description
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);

Parameter	Description
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( String attrName);

Parameter	Description
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, such as 0, 1, 2, and so on.

Syntax

public void setRowIdAttrValue( String colName);

Parameter	Description
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( String tag);

Parameter	Description
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( String tag);

Parameter	Description
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);

Parameter	Description
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);

Parameter	Description
flag	Whether to turn on SQL to XML identifier escaping.

setStylesheetHeader()

Description

Sets the stylesheet header, which contains 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( String uri);	Sets stylesheet header using the stylesheet URI.
public void setStylesheetHeader( String uri, String type);	Sets the stylesheet header using the stylesheet URI and the stylesheet type.

Parameter	Description
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, String ref);	The stylesheet parameter is passed in as the data.
public void setXSLT( java.lang.String stylesheet, String ref);	The stylesheet parameter is passed in as a URI to the document.

Parameter	Description
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( String name,
                           String value);

Parameter	Description
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);

Parameter	Description
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);

Parameter	Description
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();

---

OracleXMLSave Class

---

Description of OracleXMLSave

OracleXMLSave class supports canonical mapping from XML to object-relational tables or views. It supports inserts, updates and deletes. The user first creates the class by passing in the table name on which these DML operations need to be done. After that, the user is free to use the insert/update/delete on this table.

Many useful functions are provided in this class to help in identifying the key columns for update or delete and to restrict the columns being updated.

---

Syntax of OracleXMLSave

public class OracleXMLSave extends java.lang.Object
 
java.lang.Object
  |
  +--oracle.xml.sql.dml.OracleXMLSave

---

Fields of OracleXMLSave

Table 8-3 Summary of Fields of OracleXMLSave  

Field	Syntax	Description
DATE_FORMAT	public static final String DATE_FORMAT	The date format for use in setDateFormat.
DEFAULT_BATCH_SIZE	public static int DEFAULT_BATCH_SIZE	Default insert batch size is 17.
xDocIsEsc	public boolean xDocIsEsc	Indicates whether or not the xml doc has undergone SQL to XML escaping.

---

Methods of OracleXMLSave

Table 8-4 Summary of Methods of OracleXMLSave  

Method	Description
OracleXMLSave()	The public constructor for the Save class.
close()	It closes/deallocates all the context associated with this object.
deleteXML()	Deletes the rows in the table based on the XML document.
getURL()	Return a URL object given a file name or a URL.
insertXML()	Inserts an XML document into the specified table.
removeXSLTParam()	Removes the value of a top-level stylesheet parameter.
setBatchSize()	Changes the batch size used during DML operations.
setCommitBatch()	Sets the commit batch size.
setDateFormat()	Describes to the XSU the format of the dates in the XML document.
setIgnoreCase()	Instructs the XSU to perform a case-insensitive match of XML elements to database columns or attributes.
setKeyColumnList()	Sets the list of columns to be used for identifying a particular row in the database table during update or delete.
setPreserveWhitespace()	Instructs the XSU whether to preserve whitespaces.
setRowTag()	Names the tag used in the XML doc. to enclose the XML elements corresponding to each row value.
setSQLToXMLNameEscaping()	This turns on or off escaping of XML tags when an SQL object name would not make a valid XML identifier.
setUpdateColumnList()	Set the column values to be updated.
setXSLT()	Registers a XSL transform to be applied to generated XML.
setXSLTParam()	Sets the value of a top-level stylesheet parameter.
updateXML()	Updates the table given the XML document.

OracleXMLSave()

Description

The public constructor for the OracleXMLSave class.

Syntax

public  OracleXMLSave( java.sql.Connection oconn,
                       String tabName;

Parameter	Description
oconn	Connection object (connection to the database)
tableName	The name of the table that should be updated

close()

Description

Closes/deallocates all the context associated with this object.

Syntax

public void close();

deleteXML()

Description

Deletes the rows in the table based on the XML document. Returns the number of XML ROW elements processed. This may or may not be equal to the number of database rows deleted based on whether the rows selected through the XML document uniquely identified the rows in the table.

By default, the delete processing matches all the element values with the corresponding column names. Each ROW element in the input document is taken as a separate delete statement on the table. By using the setKeyColumnList(), the list of columns that must be matched to identify the row to be deleted is set, and other elements are ignored. This is an efficient method for deleting more than one row in the table if matching is employed (since the delete statement is cached). Otherwise, a new delete statement has to be created for each ROW element in the input document. The options are described in the following table.

Syntax	Description
public int deleteXML( org.w3c.dom.Document doc);	XML document is in DOM form.
public int deleteXML( java.io.InputStream xmlStream);	XML document is in Stream form.
public int deleteXML( java.io.Reader xmlReader);	XML document is in Reader form.
public int deleteXML( String xmlDoc);	XML document is in String form.
public int deleteXML ( java.net.URL url);	XML document is accessed through the URL.

Parameter	Description
doc	The XML document in DOM form.
xmlStream	The XML document in Stream form.
xmlReader	The XML document in Reader form.
xmlDoc	The XML document in String form.
url	The URL to the document to use to delete the rows in the table.

getURL()

Description

Returns a URL object identifying the target entity, given a file name or a URL. If the argument passed is not in a valid URL format, such as "http://..." or "file://...", then this method attempts to correct the argument by pre-pending "file://". If a NULL or an empty string are passed to it, NULL is returned.

Syntax

public static java.net.URL getURL( String target);

Parameter	Description
target	File name or URL string.

insertXML()

Description

Inserts an XML document into the specified table. Returns the number of rows inserted.

• Inserts the values into the table by matching the element name with the column name, and inserts a NULL value for all elements that are missing in the input document. By using the setUpdateColumnList(), no NULL values would be inserted for the rest of the columns; instead, default values would be used.
• To set the list of all key column, use setKeyColumnList().
• To set the list of columns to update, use setUpdateColumnList().

The options are described in the following table.

Syntax	Description
public int insertXML( org.w3c.dom.Document doc);	Inserts an XML document from a DOM.
public int insertXML( java.io.InputStream xmlStream);	Inserts an XML document from an InputStream.
public int insertXML( java.io.Reader xmlStream);	Inserts an XML document from a Reader.
public int insertXML( String xmlDoc);	Inserts an XML document from a String.
public int insertXML( java.net.URL url);	Inserts an XML document from a URL.

Parameter	Description
doc	DOM for inserting rows into the table.
xmlStream	Stream of data used for inserting rows into the table.
xmlDOC	String used for inserting rows into the table.
url	The URL to the document used for inserting rows into the table.

removeXSLTParam()

Description

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

Syntax

public void removeXSLTParam( String name);

Parameter	Description
name	Parameter name

setBatchSize()

Description

Changes the batch size used during DML operations. When performing inserts, updates or deletes, it is recommended to batch the operations to minimize I/O cycles; however, this requires more cache for storing the bind values while the operations are executing. When batching is used, the commits occur only in terms of batches. If a single statement inside a batch fails, the entire batch is rolled back. If this behavior is undesirable, set batch size to 1. The default batch size is DEFAULT_BATCH_SIZE.

Syntax

public void setBatchSize( int size);

Parameter	Description
size	The batch size to use for all DML.

setCommitBatch()

Description

Sets the commit batch size, which refers to the number of records inserted after which a commit must follow. If size < 1, or the session is in "auto-commit" mode, the XSU does not make any explicit commits. Default commit-batch size is 0.

Syntax

public void setCommitBatch( int size);

Parameter	Description
size	Commit batch size.

setDateFormat()

Description

Describes to the XSU the format of the dates in the XML document. By default, OracleXMLSave assumes that the date is in format 'MM/dd/yyyy HH:mm:ss'. You can override this default format by calling this function. The syntax of the date format pattern, the date mask, should conform to the requirements of the java.text.SimpleDateFormat class. Setting the mask to NULL or an empty string, causes the use of the default mask -- OracleXMLSave.DATE_FORMAT.

Syntax

public void setDateFormat( String mask);

Parameter	Description
mask	The date mask.

setIgnoreCase()

Description

The XSU performs mapping of XML elements to database columns or attributes based on the element names (XML tags). This function instructs the XSU to perform a case-insensitive match. This may affect the metadata caching performed when creating the Save object.

Syntax

public void setIgnoreCase( boolean ignore);

Parameter	Description
flag	Should the tag case in the XML doc be ignored?

setKeyColumnList()

Description

Sets the list of columns to be used for identifying a particular row in the database table during update or delete. This call is ignored for the insert case. The key columns must be set before updates can be done. It is optional for deletes. When this key columns is set, then the values from these tags in the XML document is used to identify the database row for update or delete. Currently, there is no way to update the values of the key columns themselves, since there is no way in the XML document to specify that case.

Syntax

public void setKeyColumnList( String[] keyColNames);

Parameter	Description
keyColNames	The names of the list of columns that are used as keys.

setPreserveWhitespace()

Description

Instructs the XSU whether to preserve whitespaces.

Syntax

public void setPreserveWhitespace( boolean flag);

Parameter	Description
flag	Should the whitespaces be preserved?

setRowTag()

Description

Names the tag used in the XML doc so to enclose the XML elements corresponding to each row value. Setting the value of this to NULL implies that there is no row tag present, and the top level elements of the document correspond to the rows themselves.

Syntax

public void setRowTag( String rowTag);

Parameter	Description
tag	Tag name.

setSQLToXMLNameEscaping()

Description

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

Syntax

public void setSQLToXMLNameEscaping( boolean flag);

Parameter	Description
flag	Should the SQL to XML escaping be turned on?

setUpdateColumnList()

Description

Set the column values to be updated. Applies to inserts and updates, not deletes.

• In case of insert, the default is to insert values to all the columns in the table.
• In case of updates, the default is to only update the columns corresponding to the tags present in the ROW element of the XML document. When specified, these columns alone will get updated in the update or insert statement. All other elements in the document will be ignored.

Syntax

public void setUpdateColumnList( String[] updColNames);

Parameter	Description
updColNmaes	The string list of columns to be updated.

setXSLT()

Description

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

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

Parameter	Description
stylesheet	The stylesheet URI.
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 (note that string literal values would therefore have to be explicitly quoted). If no stylesheet is registered, this method is a no op.

Syntax

public void setXSLTParam( String name,
                          String value);

Parameter	Description
name	Parameter name.
value	Parameter value as an XPATH expression.

updateXML()

Description

Updates the table given the XML document. Returns the number of XML elements processed. This may or may not be equal to the number of database rows modified, depending on whether the rows selected through the XML document uniquely identify the rows in the table.

• The update requires a list of key columns which are used to uniquely identify a row to update in the given table. By default, the update uses the list of key columns and matches the values of the corresponding elements in the XML document to identify a particular row, subsequently updating all the columns in the table for which there is an equivalent element present in the XML document. Each ROW element present in the input document is treated as a separate update to the table.
• A a list of columns to update can be supplied to update only desired columns and ignore any other elements present in the XML document. This is a very efficient method, because if there are more than one row present in the input XML document, the update statement itself is cached and batched.
• To set the list of all key column, use setKeyColumnList().
• To set the list of columns to update, use setUpdateColumnList().

The options are described in the following table.

Syntax	Description
public int updateXML( org.w3c.dom.Document doc);	Updates the table given the XML document in a DOM tree form.
public int updateXML( java.io.InputStream xmlStream);	Updates the table given the XML document in a stream form.
public int updateXML( java.io.Reader xmlStream);	Updates the table given the XML document in a stream form.
public int updateXML( String xmlDoc);	Updates the table given the XML document in a string form.
public int updateXML( java.net.URL url);	Updates the columns in a database table, based on the element values in the supplied XML document.

Parameter	Description
doc	The DOM tree form of the XML document
xmlStream	The stream form of the XML document
xmlDoc	The string form of the XML document
url	The URL to the document to use to update the table

---

OracleXMLSQLException Class

---

Description of OracleXMLSQLException

Class for managing all exceptions thrown by the XSU.

---

Syntax of OracleXMLSQLException

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 8-5 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( Exception e);	Sets the parent exception as passed in.
public OracleXMLSQLException( Exception e, String errorTagName);	Sets the error tag name as passed in.
public OracleXMLSQLException( String message);	Sets the error message to be returned.
public OracleXMLSQLException( String message, j Exception e);	Sets the parent exception and the error message to be returned.
public OracleXMLSQLException( String message, Exception e, String errorTagName);	Sets the error message, parent exception, and error tag to be used.
public OracleXMLSQLException( String message, int errorCode);	Sets the error message and SQL error code.
public OracleXMLSQLException( String message, int errorCode, String errorTagName);	Sets the eror message, SQL error code, and the error tag to be used.
public OracleXMLSQLException( String message, String errorTagName);	Sets the error message and the error tag to be used.

Parameter	Description
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 String getXMLErrorString();

getXMLSQLErrorString()

Description

Prints the SQL parameters as well in the error message.

Syntax

public 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( String tagName);

Parameter	Description
tagName	The tag name of the error

---

OracleXMLSQLNoRowsException Class

---

Description of OracleXMLSQLNoRowsException

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

---

Syntax of OracleXMLSQLNoRowsException

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 of OracleXMLSQLNoRowsException

OracleXMLSQLNoRowsException()

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

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

Parameter	Description
errorTag	The error tag.