Skip Headers

Oracle9i XML Reference
Release 1 (9.0.1)

Part Number A88899-01
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Go to previous page Go to next page

12
Oracle XML SQL Utility (XSU) Java API


OracleXMLQuery

Syntax

public class OracleXMLQuery extends java.lang.Object
 

java.lang.Object

oracle.xml.sql.query.OracleXMLQuery

Description

The OracleXMLQuery class does the generation of XML given a SQL query. Following is a very simple example:

  import java.sql.*;  import oracle.xml.sql.query.*;  import oracle.jdbc.driver.*;  public class sample  {    public static void main(String args[]) throws Exception    {      DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver());      Connection conn =           DriverManager.getConnection("jdbc:oracle:oci8:scott/tiger@");      OracleXMLQuery qry =  new OracleXMLQuery(conn, "select * from emp");      System.out.println(qry.getXMLString());      conn.close();    }  }   

Member Summary 

 

Fields 

 

DTD 

The DTD is used to specified that the DTD is to be generated 

ERROR_TAG 

The ERROR_TAG specifies the default tag name for the ERROR document 

MAXROWS_ALL 

The MAXROWS_ALL specifies that all rows be included in the result 

NONE 

The NONE is used to specified that no DTD is to be generated 

ROW_TAG 

The ROW_TAG specifies the default tag name for the ROW elements 

ROWIDATTR_TAG 

The ROWIDATTR_TAG specifies the default tag name for the ROW elements 

ROWSET_TAG 

The ROWSET_TAG specifies the default tag name for the document 

SCHEMA 

The SCHEMA is used to specified that no XML schema is to be generated 

SKIPROWS_ALL 

The SKIPROWS_ALL specifies that all rows be skipped in the result. 

Constructors 

 

OracleXMLQuery(Connection, ResultSet) 

Constructor for the OracleXMLQueryObject. 

OracleXMLQuery(Connection, String) 

Constructor for the OracleXMLQueryObject. 

OracleXMLQuery(OracleXMLDataSet) 

Constructor for the OracleXMLQueryObject. 

Methods 

 

close() 

Close any open resource, created by the OracleXML engine. 

getXMLDOM(int) 

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

getXMLDOM(Node) 

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

getXMLDOM(Node, int) 

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

getXMLMetaData(int, boolean) 

This functions returns the DTD or the XMLSchema for the XML document which would have been generated by a getXML call. 

getXMLSAX(ContentHandler) 

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

getXMLSchema() 

This methods generated the XML Schema(s) corresponding to the specified query. 

getXMLString() 

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

getXMLString(int) 

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

getXMLString(Node) 

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

getXMLString(Node, int) 

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

keepObjectOpen(boolean) 

The default behavior for all the getXML functions which DO NOT TAKE in a ResultSet object is to close the ResultSet object and Statement objects at the end of the call. 

removeXSLTParam(String) 

Removes the value of a top-level stylesheet parameter. 

setCollIdAttrName(String) 

Sets the name of the id attribute of the collection element's separator tag. 

setDataHeader(Reader, String) 

Sets the xml data header. 

setDateFormat(String) 

Sets the format of the generated dates in the XML doc. 

setEncoding(String) 

Sets the encoding PI (processing instruction) in the XML doc. 

setErrorTag(String) 

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

setException(Exception) 

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

setMaxRows(int) 

Sets the max number of rows to be converted to XML. 

setMetaHeader(Reader) 

Sets the XML meta header. 

setRaiseException(boolean) 

Tells the XSU to throw the raised exceptions. 

setRaiseNoRowsException(boolean) 

Tells the XSU to throw or not to throw an OracleXMLNoRowsException in the case when for one reason or another, the XML doc generated is empty. 

setRowIdAttrName(String) 

Sets the name of the id attribute of the row enclosing tag. 

setRowIdAttrValue(String) 

Specifies the scalar column whose value is to be assigned to the id attribute of the row enclosing tag. 

setRowsetTag(String) 

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

setRowTag(String) 

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

setSkipRows(int) 

Sets the number of rows to skip. 

setStylesheetHeader(String) 

Sets the stylesheet header (i.e. 

setStylesheetHeader(String, String) 

Sets the stylesheet header (i.e. 

setXSLT(Reader, String) 

Registers a XSL transform to be applied to generated XML. 

setXSLT(String, String) 

Registers a XSL transform to be applied to generated XML. 

setXSLTParam(String, String) 

Sets the value of a top-level stylesheet parameter. 

useLowerCaseTagNames() 

This will set the case to be lower for all tag names. 

useNullAttributeIndicator(boolean) 

Specified weather to use an XML attribute to indicate NULLness, or to do it by omitting the inclusion of the particular entity in the XML document. 

useTypeForCollElemTag(boolean) 

By default the tag name for elements of a collection is the collection's tag name followed by "_item". 

useUpperCaseTagNames() 

This will set the case to be upper for all tag names. 

Inherited Member Summary 

Methods inherited from class java.lang.Object 

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait 

Fields

DTD

public static final int DTD

The DTD is used to specified that the DTD is to be generated

ERROR_TAG

public static final java.lang.String ERROR_TAG

The ERROR_TAG specifies the default tag name for the ERROR document

MAXROWS_ALL

public static final int MAXROWS_ALL

The MAXROWS_ALL specifies that all rows be included in the result

NONE

public static final int NONE

The NONE is used to specified that no DTD is to be generated

ROW_TAG

public static final java.lang.String ROW_TAG

The ROW_TAG specifies the default tag name for the ROW elements

ROWIDATTR_TAG

public static final java.lang.String ROWIDATTR_TAG

The ROWIDATTR_TAG specifies the default tag name for the ROW elements

ROWSET_TAG

public static final java.lang.String ROWSET_TAG

The ROWSET_TAG specifies the default tag name for the document

SCHEMA

public static final int SCHEMA

The SCHEMA is used to specified that no XML schema is to be generated

SKIPROWS_ALL

public static final int SKIPROWS_ALL

The SKIPROWS_ALL specifies that all rows be skipped in the result.

Constructors

OracleXMLQuery(Connection, ResultSet)

public  OracleXMLQuery(java.sql.Connection conn, java.sql.ResultSet rset)

Constructor for the OracleXMLQueryObject.

Parameters:

conn - database connection

rset - jdbc result set object

OracleXMLQuery(Connection, String)

public  OracleXMLQuery(java.sql.Connection conn, java.lang.String query)

Constructor for the OracleXMLQueryObject.

Parameters:

conn - database connection

query - the SQL query string

OracleXMLQuery(OracleXMLDataSet)

public  OracleXMLQuery(oracle.xml.sql.dataset.OracleXMLDataSet dset)

Constructor for the OracleXMLQueryObject.

Parameters:

conn - database connection

dset - dataset

Methods

close()

public void close()

Close any open resource, created by the OracleXML engine. This will not close for instance resultset supplied by the user

getNumRowsProcessed()

public long getNumRowsProcessed()

Returns the number of rows processed.

Returns:

number of rows processed.

getXMLDOM()

public org.w3c.dom.Document getXMLDOM()

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

Returns:

the DOM representation of the XML document

getXMLDOM(int)

public org.w3c.dom.Document getXMLDOM(int metaType)

Transforms the object-relational data, specified in the constructor, into a XML document. 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.

Parameters:

metaType - the type of XML metadata (NONE, SCHEMA)

Returns:

the string representation of the XML document

getXMLDOM(Node)

public org.w3c.dom.Document getXMLDOM(org.w3c.dom.Node root)

Transforms the object-relational data, specified in the constructor, into XML. If not NULL, the root argument, is considered the "root" element of the XML doc.

Parameters:

root - root node to which to append the new XML

Returns:

the string representation of the XML document

getXMLDOM(Node, int)

public org.w3c.dom.Document getXMLDOM(org.w3c.dom.Node root, int metaType)

Transforms the object-relational data, specified in the constructor, into XML. 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.

Parameters:

root - root node to which to append the new XML

metaType - the type of XML metadata (NONE, SCHEMA)

Returns:

the string representation of the XML document

getXMLMetaData(int, boolean)

public java.lang.String getXMLMetaData(int metaType, boolean withVer)

This functions returns the DTD or the XMLSchema for the XML document which would have been generated by a getXML call. The "metaType" parameter specifies the type of XML metadata to be generated. The withVer parameter specifies if version header is to be generated or not.

Parameters:

metaType - XML meta data type to generate (NONE or DTD)

withVer - generate the version PI ?

getXMLSAX(ContentHandler)

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

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

Parameters:

sax - ContentHandler object to be registered

getXMLSchema()

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

This methods generated the XML Schema(s) corresponding to the specified query.

Returns:

the XML Schema(s)

getXMLString()

public java.lang.String getXMLString()

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

Returns:

the string representation of the XML document

getXMLString(int)

public java.lang.String getXMLString(int metaType)

Transforms the object-relational data, specified in the constructor, into a XML document. The metaType argument is used to specify the type of XML metadata the XSU is to generate along with the XML. Valid values for the metaType argument are NONE and DTD (static fields of this class).

Parameters:

metaType - the type of XML metadata (NONE, DTD, or SCHEMA)

Returns:

the string representation of the XML document

getXMLString(Node)

public java.lang.String getXMLString(org.w3c.dom.Node root)

Transforms the object-relational data, specified in the constructor, into XML. If not NULL, the root argument, is considered the "root" element of the XML doc.

Parameters:

root - root node to which to append the new XML

Returns:

the string representation of the XML document

getXMLString(Node, int)

public java.lang.String getXMLString(org.w3c.dom.Node root, int metaType)

Transforms the object-relational data, specified in the constructor, into XML. 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. Valid values for the metaType argument are NONE and DTD (static fields of this class). Note that if the root argument is non-null, no DTD is generated even if requested.

Parameters:

root - root node to which to append the new XML

metaType - the type of XML metadata (NONE, DTD, or SCHEMA)

Returns:

the string representation of the XML document

keepObjectOpen(boolean)

public void keepObjectOpen(boolean alive)

The default behavior for all the getXML functions which DO NOT TAKE in a ResultSet object is to close the ResultSet object and Statement objects at the end of the call. If you need to use the persistant feature, where by calling getXML repeatedly you get the next set of rows, you need to turn off this behavior by calling this function with value true. i.e. OracleXMLQuery would not close the ResultSet and Statement objects after the getXML calls. You can call the close() function to explicitly close the cursor state.

Parameters:

alive - keep object open ?

removeXSLTParam(String)

public void removeXSLTParam(java.lang.String name)

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

Parameters:

name - parameter name

setCollIdAttrName(String)

public void setCollIdAttrName(java.lang.String attrName)

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

Parameters:

attrName - attribute name

setDataHeader(Reader, String)

public void setDataHeader(java.io.Reader header, java.lang.String docTag)

Sets the xml data header. The data header is an XML entity which is appended at the begining of the query-generated xml entity (ie. rowset). The two entities are enclosed by the tag specified via the docTag argument. Note that the last data header specified is the one that is used; furthermore, passing in null for the header, parameter unsets the data header.

Parameters:

header - header

tag - tag used to enclose the data header and the rowset

setDateFormat(String)

public void setDateFormat(java.lang.String mask)

Sets the format of the generated dates in the XML doc. The syntax of the date format patern (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.

Parameters:

mask - the date mask

setEncoding(String)

public void setEncoding(java.lang.String enc)

Sets the encoding PI (processing instruction) 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.

Parameters:

enc - characterset encoding of the XML doc

setErrorTag(String)

public void setErrorTag(java.lang.String tag)

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

Parameters:

tag - tag name

setException(Exception)

public void setException(java.lang.Exception e)

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

Parameters:

e - the exception to be processed by the XSU.

setMaxRows(int)

public void setMaxRows(int rows)

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

Parameters:

rows - max number of rows to generate

setMetaHeader(Reader)

public void setMetaHeader(java.io.Reader header)

Sets the XML meta header. When set, the header is inserted at the begining of the metadata part (DTD or XMLSchema) of each XML document generated by this object. Note that the last meta header specified is the one that is used; furthermore, passing in null for the header, parameter unsets the meta header.

Parameters:

header - header

setRaiseException(boolean)

public void setRaiseException(boolean flag)

Tells the XSU 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 out of the exception's message.

Parameters:

flag - throw raised exceptions?

setRaiseNoRowsException(boolean)

public void setRaiseNoRowsException(boolean flag)

Tells the XSU to throw or not to throw an OracleXMLNoRowsException in the case when for one reason or another, the XML doc generated is empty. By default, the exception is not thrown.

Parameters:

flag - throw OracleXMLNoRowsException if no data found?

setRowIdAttrName(String)

public void setRowIdAttrName(java.lang.String attrName)

Sets the name of the id attribute of the row enclosing tag. Passing null or an empty string for the tag results the row id attribute to be omitted.

Parameters:

attrName - attribute name

setRowIdAttrValue(String)

public void setRowIdAttrValue(java.lang.String colName)

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 for the colName results the row id attribute being assigned the row count value (i.e. 0, 1, 2 and so on).

Parameters:

colName - column whose value is to be assigned to the row id attr

setRowsetTag(String)

public void setRowsetTag(java.lang.String tag)

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

Parameters:

tag - tag name

setRowTag(String)

public void setRowTag(java.lang.String tag)

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

Parameters:

tag - tag name

setSkipRows(int)

public void setSkipRows(int rows)

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

Parameters:

rows - number of rows to skip

setStylesheetHeader(String)

public void setStylesheetHeader(java.lang.String uri)

Sets the stylesheet header (i.e. stylesheet processing instructions) in the generated XML doc. Note: Passing null for the uri argument will unset the stylesheet header and the stylesheet type.

Parameters:

uri - stylesheet URI

setStylesheetHeader(String, String)

public void setStylesheetHeader(java.lang.String uri, java.lang.String type)

Sets the stylesheet header (i.e. stylesheet processing instructions) in the generated XML doc. Note: Passing null for the uri argument will unset the stylesheet header and the stylesheet type.

Parameters:

uri - stylesheet URI

type - stylesheet type; defaults to 'text/xsl'

setXSLT(Reader, String)

public void setXSLT(java.io.Reader stylesheet, java.lang.String ref)

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.

Parameters:

stylesheet - the stylesheet

ref - URL for include, import and external entities

setXSLT(String, String)

public void setXSLT(java.lang.String stylesheet, java.lang.String ref)

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.

Parameters:

stylesheet - the stylesheet URI

ref - URL for include, import and external entities

setXSLTParam(String, String)

public void setXSLTParam(java.lang.String name, java.lang.String value)

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). NOTE: if no stylesheet is registered, this method is a no op.

Parameters:

name - parameter name

value - parameter value as an XPATH expression

useLowerCaseTagNames()

public void 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.

useNullAttributeIndicator(boolean)

public void useNullAttributeIndicator(boolean flag)

Specified weather to use an XML attribute to indicate NULLness, or to do it by omitting the inclusion of the particular entity in the XML document.

Parameters:

flag - use attribute to indicate null?

useTypeForCollElemTag(boolean)

public void useTypeForCollElemTag(boolean flag)

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 of true, tells the XSU to use the collection element's type name as the collection element tag name.

Parameters:

flag - use the coll. elem. type as its tag name?

useUpperCaseTagNames()

public void useUpperCaseTagNames()

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


OracleXMLSave

Syntax

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

Description

OracleXMLSave - this 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. A typical sequence might look like

 OracleXMLSave sav = new OracleXMLSave(conn, "emp"); // insert processing sav.insertXML(xmlDoc); -or- // Update processing  String[]tempArr = new String[2];  tempArr[0] = "EMPNO";   // set the empno as the key for updates..  sav.setKeyColumnList(tempArray); sav.updateXML(xmlDoc); -or- sav.deleteXML(xmlDoc); sav.close();  

A lot of 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.

Member Summary 

 

Fields 

 

DATE_FORMAT 

The date format for use in setDateFormat 

DEFAULT_BATCH_SIZE 

default insert batch size is 17 

Constructors 

 

OracleXMLSave(Connection, String) 

The public constructor for the Save class. 

Methods 

 

cleanLobList() 

 

close() 

It closes/deallocates all the context associated with this object. 

deleteXML(Document) 

Deletes the rows in the table based on the XML document 

deleteXML(InputStream) 

Deletes the rows in the table based on the XML document 

deleteXML(Reader) 

Deletes the rows in the table based on the XML document 

deleteXML(String) 

Deletes the rows in the table based on the XML document 

deleteXML(URL) 

Deletes rows from a specified table based on the element values in the supplied XML document. 

finalize() 

 

getURL(String) 

Given a file name or a URL it return a URL object. 

insertXML(Document) 

 

insertXML(InputStream) 

 

insertXML(Reader) 

 

insertXML(String) 

 

insertXML(URL) 

Inserts an XML document from a specified URL into the specified table, By default, the insert routine 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. 

removeXSLTParam(String) 

Removes the value of a top-level stylesheet parameter. 

setBatchSize(int) 

This call changes the batch size used during DML operations. 

setCommitBatch(int) 

Sets the commit batch size. 

setDateFormat(String) 

Describes to the XSU the format of the dates in the XML document. 

setIgnoreCase(boolean) 

The XSU does mapping of XML elements to database columns/attrs. 

setKeyColumnList(String[]) 

Sets the list of columns to be used for identifying a particular row in the database table during update or delete. 

setRowTag(String) 

Names the tag used in the XML doc., to enclose the XML elements corresponding to each row value. 

setUpdateColumnList(String[]) 

Set the column values to be updated. 

setXSLT(Reader, String) 

Registers a XSL transform to be applied to generated XML. 

setXSLT(String, String) 

Registers a XSL transform to be applied to generated XML. 

setXSLTParam(String, String) 

Sets the value of a top-level stylesheet parameter. 

updateXML(Document) 

Updates the table given the XML document in a DOM tree form 

updateXML(InputStream) 

Updates the table given the XML document in a stream form 

updateXML(Reader) 

Updates the table given the XML document in a stream form 

updateXML(String) 

Updates the table given the XML document in a string form 

updateXML(URL) 

Updates the columns in a database table, based on the element values in the supplied XML document. 

Inherited Member Summary 

Methods inherited from class java.lang.Object 

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait 

Fields

DATE_FORMAT

public static final java.lang.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

Constructors

OracleXMLSave(Connection, String)

public  OracleXMLSave(java.sql.Connection oconn, java.lang.String tabName)

The public constructor for the Save class.

Parameters:

oconn - Connection object (connection to the database)

tableName - The name of the table that should be updated

Methods

cleanLobList()

public void cleanLobList()

close()

public void close()

It closes/deallocates all the context associated with this object.

deleteXML(Document)

public int deleteXML(org.w3c.dom.Document doc)

Deletes the rows in the table based on the XML document

Parameters:

xmlDoc - The XML document in DOM form

Returns:

The number of XML ROW elements processed.

See Also:

deleteXML(URL)

deleteXML(InputStream)

public int deleteXML(java.io.InputStream xmlStream)

Deletes the rows in the table based on the XML document

Parameters:

xmlDoc - The XML document in Stream form

Returns:

The number of XML ROW elements processed.

See Also:

deleteXML(URL)

deleteXML(Reader)

public int deleteXML(java.io.Reader xmlStream)

Deletes the rows in the table based on the XML document

Parameters:

xmlDoc - The XML document in Stream form

Returns:

The number of XML ROW elements processed.

See Also:

deleteXML(URL)

deleteXML(String)

public int deleteXML(java.lang.String xmlDoc)

Deletes the rows in the table based on the XML document

Parameters:

xmlDoc - The XML document in String form

Returns:

The number of XML ROW elements processed.

See Also:

deleteXML(URL)

deleteXML(URL)

public int deleteXML(java.net.URL url)

Deletes rows from a specified table based on the element values in the supplied XML document. 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() you can set the list of columns that must be matched to identify the row to be deleted and ignore the other elements This is an effficient method for deleting more than one row in the table, since the delete statement is cached and batching can be employed. If not, a new delete statement has to be created for each ROW element in the input document.

For example, consider the employee table emp,

TABLE emp( empno NUMBER, ename VARCHAR2(20), hiredate DATE);

Now, you want to delete the rows in the table using an XML document and you want to identify the row based on the EMPNO value. You can send in an XML document containing the EMPNO value and call the deleteXML routine with the setKeyColumnList() containing the EMPNO string.

OracleXMLSave save = new OracleXMLSave(conn,"emp");

save.deleteXML(xmlDoc); // Deletes rows by matching all columns with the // element values in the input document.

String[] deleteArray = new String[1];

deleteArray[0] = "EMPNO";

save.setKeyColumnList(deleteArray); // set the key columns

save.deleteXML(xmlDoc); // only deletes rows by matching the EMPNO values

Parameters:

url - The URL to the document to use to delete the rows in the table

Returns:

The number of XML row elements processed. Note that 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.

finalize()

protected void finalize()

Overrides:

java.lang.Object.finalize() in class java.lang.Object

getURL(String)

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

Given a file name or a URL it return a URL object. If the argument passed is not in the valid URL format (e.g. http://.. or file://) then this method tried to fix the argument by pre-pending "file://" to the argument. If a null or an empty string are passed to it, null is returned.

Parameters:

target - file name or URL string

Returns:

the URL object identifiying the target entity

insertXML(Document)

public int insertXML(org.w3c.dom.Document doc)

insertXML(InputStream)

public int insertXML(java.io.InputStream xmlStream)

insertXML(Reader)

public int insertXML(java.io.Reader xmlStream)

insertXML(String)

public int insertXML(java.lang.String xmlDoc)

insertXML(URL)

public int insertXML(java.net.URL url)

Inserts an XML document from a specified URL into the specified table, By default, the insert routine 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 setting the list of columns to insert using the setUpdateColumnList() you can restrict the insert to only insert values into those columns and let the default values for other columns to be inserted. That is no null value would be inserted for the rest of the columns Use setKeyColumnList() to set the list of all key column. Use setUpdateColumnList() to set the list of columns to update.

For example, consider the employee table emp,

TABLE emp( empno NUMBER, ename VARCHAR2(20), hiredate DATE);

Now, assume that you want to insert the table using an XML document OracleXMLSave

save = new OracleXMLSave(conn,"emp");

save.insertXML(xmlDoc); // xmlDoc supplied..

save.close();

If you want to insert values only in to EMPNO, HIREDATE and SALARY and let the default values handle the rest of the columns,

String insArray = new String[3];

insArrary[0] = "EMPNO";

insArray[1] = "HIREDATE";

insArray[2] = "SALARY";

save.setUpdateColumnList(insArray);

save.insertXML(xmlDoc); // will only insert values into EMPNO, HIREDATE // and SALARY columns

Parameters:

url - The URL to the document to use to insert rows into the table

Returns:

The number of rows inserted.

removeXSLTParam(String)

public void removeXSLTParam(java.lang.String name)

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

Parameters:

name - parameter name

setBatchSize(int)

public void setBatchSize(int size)

This call changes the batch size used during DML operations. When performing inserts, updates or deletes, it is better to batch the operations so that the database can execute it in one shot rather than as separate statements. The flip side is that more memory is needed to hold all the bind values before the operation is done. Note that when batching is used, the commits occur only in terms of batches. So if one of the statement inside a batch fails, the whole batch is rolled back. If this behaviour is unaccepatable, then set the batch size to 1. The default batch size is DEFAULT_BATCH_SIZE;

Parameters:

size - The batch size to use for all DML

setCommitBatch(int)

public void setCommitBatch(int size)

Sets the commit batch size. The commit batch size refers to the number or records inserted after which a commit should follow. Note that if commitBatch is < 1 or the session is in "auto-commit" mode then the XSU does not make any explicit commit's. By default the commit-batch size is 0.

Parameters:

size - commit batch size

setDateFormat(String)

public void setDateFormat(java.lang.String mask)

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 patern (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, results the use of the default mask -- OracleXMLSave.DATE_FORMAT.

Parameters:

mask - the date mask

setIgnoreCase(boolean)

public void setIgnoreCase(boolean ignore)

The XSU does mapping of XML elements to database columns/attrs. based on the element names (xml tags). This function tells the XSU to do this match case insensitive. This resetting of case may affect the metadata caching that is done when creating the Save object.

Parameters:

flag - ignore tag case in the XML doc? 0-false 1-true

setKeyColumnList(String[])

public void setKeyColumnList(java.lang.String[] keyColNames)

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

Parameters:

keyColNames - The names of the list of columns that are used as keys

setRowTag(String)

public void setRowTag(java.lang.String rowTag)

Names the tag used in the XML doc., 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.

Parameters:

tag - tag name

setUpdateColumnList(String[])

public void setUpdateColumnList(java.lang.String[] updColNames)

Set the column values to be updated. This is only valid for inserts and updates, and is ignored for 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.

Parameters:

updColNames - The string list of columns to be updated

setXSLT(Reader, String)

public void setXSLT(java.io.Reader stylesheet, java.lang.String ref)

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.

Parameters:

stylesheet - the stylesheet

ref - URL for include, import and external entities

setXSLT(String, String)

public void setXSLT(java.lang.String stylesheet, java.lang.String ref)

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.

Parameters:

stylesheet - the stylesheet URI

ref - URL for include, import and external entities

setXSLTParam(String, String)

public void setXSLTParam(java.lang.String name, java.lang.String value)

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). NOTE: if no stylesheet is registered, this method is a no op.

Parameters:

name - parameter name

value - parameter value as an XPATH expression

updateXML(Document)

public int updateXML(org.w3c.dom.Document doc)

Updates the table given the XML document in a DOM tree form

Parameters:

xmlDoc - The DOM tree form of the XML document

Returns:

The number of XML elements processed

See Also:

updateXML(URL)

updateXML(InputStream)

public int updateXML(java.io.InputStream xmlStream)

Updates the table given the XML document in a stream form

Parameters:

xmlDoc - The stream form of the XML document

Returns:

The number of XML elements processed

See Also:

updateXML(URL)

updateXML(Reader)

public int updateXML(java.io.Reader xmlStream)

Updates the table given the XML document in a stream form

Parameters:

xmlDoc - The stream form of the XML document

Returns:

The number of XML elements processed

See Also:

updateXML(URL)

updateXML(String)

public int updateXML(java.lang.String xmlDoc)

Updates the table given the XML document in a string form

Parameters:

xmlDoc - The string form of the XML document

Returns:

The number of XML elements processed

See Also:

updateXML(URL)

updateXML(URL)

public int updateXML(java.net.URL url)

Updates the columns in a database table, based on the element values in the supplied XML document. 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 and then updates 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.

You can also supply a list of columns to update - this will make the utility update only those columns and ignore any other element present in the XML document. This is a very efficient method, since if there are more than one row present in the input XML document, the update statement itself is cached and batching is done. If not, then we need to create a new update statement for each row of the input document.

Use setKeyColumnList() to set the list of all key column.

Use setUpdateColumnList() to set the list of columns to update.

For example, consider the employee table emp,

TABLE emp( empno NUMBER, ename VARCHAR2(20), hiredate DATE);

Now, assume that you want to update the table using an XML document and you want to use the values of the element EMPNO to match the right row and then only update the HIREDATE column.

You can send in an XML document containing the HIREDATE value and the EMPNO value and call the updateXML routine with the setKeyColumnList() containing the EMPNO string.

OracleXMLSave save = new OracleXMLSave(conn,"emp");

String[] keyArray = new String[1];

keyArray[0] = "EMPNO"; // Set EMPNO as key column

save.setKeyColumnList(keyArray); // Set the key column names

String[] updArray = new String[1];

updArray[0] = "HIREDATE"; // SEt hiredate as column to update

save.setUpdateColumnList(updArray);

save.updateXML(xmlDoc); // xmlDoc supplied..

save.close();

Parameters:

url - The URL to the document to use to update the table

Returns:

The number of XML row elements processed. Note that this may or may not be equal to the number of database rows modified based on whether the rows selected through the XML document uniquely identified the rows in the table.


OracleXMLSQLException

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 Known Subclasses:

OracleXMLSQLNoRowsException

All Implemented Interfaces:

java.io.Serializable

Description

Member Summary 

 

Constructors 

 

OracleXMLSQLException(Exception) 

 

OracleXMLSQLException(Exception, String) 

 

OracleXMLSQLException(String) 

 

OracleXMLSQLException(String, Exception) 

 

OracleXMLSQLException(String, Exception, String) 

 

OracleXMLSQLException(String, int) 

 

OracleXMLSQLException(String, int, String) 

 

OracleXMLSQLException(String, String) 

 

Methods 

 

getErrorCode() 

 

getParentException() 

returns the original exception, if there was one; otherwise, it returns null 

getXMLErrorString() 

prints the XML error string with the given error tag name 

getXMLSQLErrorString() 

prints the SQL parameters as well in the error message 

setErrorTag(String) 

Sets the error tag name which is then used by getXMLErrorString and getXMLSQLErrorString, to generate xml error reports 

Inherited Member Summary 

Methods inherited from class java.lang.Throwable 

fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString 

Methods inherited from class java.lang.Object 

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait 

Constructors

OracleXMLSQLException(Exception)

public  OracleXMLSQLException(java.lang.Exception e)

OracleXMLSQLException(Exception, String)

public  OracleXMLSQLException(java.lang.Exception e, java.lang.String 
errorTagName)

OracleXMLSQLException(String)

public  OracleXMLSQLException(java.lang.String message)

OracleXMLSQLException(String, Exception)

public  OracleXMLSQLException(java.lang.String message, java.lang.Exception e)

OracleXMLSQLException(String, Exception, String)

public  OracleXMLSQLException(java.lang.String message, java.lang.Exception e, 
java.lang.String errorTagName)

OracleXMLSQLException(String, int)

public  OracleXMLSQLException(java.lang.String message, int errorCode)

OracleXMLSQLException(String, int, String)

public  OracleXMLSQLException(java.lang.String message, int errorCode, 
java.lang.String errorTagName)

OracleXMLSQLException(String, String)

public  OracleXMLSQLException(java.lang.String message, java.lang.String 
errorTagName)

Methods

getErrorCode()

public int getErrorCode()

getParentException()

public java.lang.Exception getParentException()

returns the original exception, if there was one; otherwise, it returns null

getXMLErrorString()

public java.lang.String getXMLErrorString()

prints the XML error string with the given error tag name

getXMLSQLErrorString()

public java.lang.String getXMLSQLErrorString()

prints the SQL parameters as well in the error message

setErrorTag(String)

public void setErrorTag(java.lang.String tagName)

Sets the error tag name which is then used by getXMLErrorString and getXMLSQLErrorString, to generate xml error reports


OracleXMLSQLNoRowsException

Syntax

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

All Implemented Interfaces:

java.io.Serializable

Member Summary 

 

Constructors 

 

OracleXMLSQLNoRowsException() 

 

OracleXMLSQLNoRowsException(String) 

 

Inherited Member Summary 

Methods inherited from interface OracleXMLSQLException 

getErrorCode(), getParentException(), getXMLErrorString(), getXMLSQLErrorString(), setErrorTag(String) 

Methods inherited from class java.lang.Throwable 

fillInStackTrace, getLocalizedMessage, getMessage, printStackTrace, printStackTrace, printStackTrace, toString 

Methods inherited from class java.lang.Object 

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait 

Constructors

OracleXMLSQLNoRowsException()

public  OracleXMLSQLNoRowsException()

OracleXMLSQLNoRowsException(String)

public OracleXMLSQLNoRowsException(java.lang.String errorTag)


Go to previous page Go to next page
Oracle
Copyright © 1996-2001, Oracle Corporation.

All Rights Reserved.
Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index