Skip Headers

Oracle® XML Reference 10g (9.0.4) Part Number B10926-01 |
Home | Contents | Index

# 7
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: Oracle Application Developer's Guide - XML

## OracleXMLQuery Class

The OracleXMLQuery class generates XML given an SQL query.

#### Syntax

    public class OracleXMLQuery extends java.lang.Object

##### Table 7-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.

##### Table 7-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 `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()

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()

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()

Returns the number of rows processed.

#### Syntax

    public long getNumRowsProcessed();

## getXMLDOM()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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()

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

#### Syntax

    public void setErrorTag( String tag);

Parameter | Description
--- | ---
    tag
| Tag name

## setException()

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()

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()

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()

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()

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()

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()

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()

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

#### Syntax

    public void setRowsetTag( String tag);

Parameter | Description
--- | ---
    tag
| Tag name

## setRowTag()

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()

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()

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()

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()

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()

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()

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()

Specifies if `NULL`ness 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()

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()

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

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

    public class OracleXMLSave extends java.lang.Object

##### Table 7-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.

##### Table 7-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()

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()

Closes/deallocates all the context associated with this object.

#### Syntax

    public void close();

## deleteXML()

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()

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()

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()

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()

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()

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()

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()

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()

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()

Instructs the XSU whether to preserve whitespaces.

#### Syntax

    public void setPreserveWhitespace( boolean flag);

Parameter | Description
--- | ---
    flag
| Should the whitespaces be preserved?

## setRowTag()

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()

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()

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()

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()

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()

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 used to uniquely identify rows to update. 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, updating all columns that have an equivalent element in the XML document. Each ROW element 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

Class for managing all exceptions thrown by the XSU.

#### Syntax

    public class OracleXMLSQLException extends java.lang.RuntimeException

##### Table 7-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()

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()

Returns the SQL error code thrown.

#### Syntax

    public int getErrorCode();

## getParentException()

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

#### Syntax

    public java.lang.Exception getParentException();

## getXMLErrorString()

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

#### Syntax

    public String getXMLErrorString();

## getXMLSQLErrorString()

Prints the SQL parameters as well in the error message.

#### Syntax

    public String getXMLSQLErrorString();

## setErrorTag()

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

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

#### Syntax

    public class OracleXMLSQLNoRowsException extends OracleXMLSQLException

## 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.

| Copyright © 2001, 2003 Oracle Corporation. All Rights Reserved. |
Home | Contents | Index