oracle.xml.sql.dml
Class OracleXMLSave

java.lang.Object
oracle.xml.sql.dml.OracleXMLSave

public class OracleXMLSave

extends java.lang.Object

OracleXMLSave - This class supports canonical mapping from XML to object-relational tables and views. You must initially create a class by passing in the table name to which DML operations apply. You can subsequently use any of the insertion, update, and deletion methods of OracleXMLSave class on the table. Many useful functions are provided to help identify key columns for update or delete, and to restrict columns being updated. A typical sequence might look like this:

• Create class

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

• Insert

  sav.insertXML(xmlDoc);
  

• Update

  String[]tempArr = new String[2];
  
  tempArr[0] =
      EMPNO";
  
  sav.setKeyColumnList(tempArray); 
  
  sav.updateXML(xmlDoc);
     
  

• Delete

  sav.deleteXML(xmlDoc);
  
  sav.close();
  

Field Summary

static java.lang.String	DATE_FORMAT The date format for use in setDateFormat.
static int	DEFAULT_BATCH_SIZE The default insert batch size is 17 records
boolean	xDocIsEsc

Constructor Summary

OracleXMLSave(java.sql.Connection oconn, java.lang.String tabName)
Constructor for the OracleXMLSave class.

Method Summary

void	cleanLobList() This function frees all temporary LOBs
void	close() Closes the OracleXMLSave object and deallocates all context associated with it.
java.net.URL	createURL(java.lang.String fileName) Returns the URL object for a specified file or URL.
int	deleteXML(Document doc) Deletes the rows in the table based on the XML document By default, matches all XML element values with corresponding column names.
int	deleteXML(java.io.InputStream xmlStream) Deletes the rows in the table based on the XML document.
int	deleteXML(java.io.Reader xmlStream) Deletes the rows in the table based on the XML document.
int	deleteXML(java.lang.String xmlDoc) Deletes the rows in the table based on the XML document.
int	deleteXML(java.net.URL url) Deletes rows from a table based on element values of the input XML document.
protected void	finalize()
static java.net.URL	getURL(java.lang.String target) Given a file name or a URL it return a URL object.
int	insertXML(Document doc)
int	insertXML(java.io.InputStream xmlStream)
int	insertXML(java.io.Reader xmlStream)
int	insertXML(java.lang.String xmlDoc)
int	insertXML(java.net.URL url) Inserts an XML document from a specified URL into a table, By default, matches element names to column names, and sets columns with missing elements in input to null</null>.
void	removeXSLTParam(java.lang.String name) Removes the value of a top-level stylesheet parameter.
void	setBatchSize(int size) Changes the batch size used during DML operations.
void	setCommitBatch(int size) Sets the commit batch size, or the number of records inserted before a commit.
void	setDateFormat(java.lang.String mask) Specifies the format of dates used in the XML document.
void	setIgnoreCase(boolean ignore) Sets XML element names, based on XML tags, to be case insensitive when converting to database columns and attributes.
void	setKeyColumnList(java.lang.String[] keyColNames) Sets the list of columns used to identify table rows against XML input document elements prior to UPDATE and DELETE operations.
void	setPreserveWhitespace(boolean flag) Specifies whether to preserve whitespace..
void	setRowTag(java.lang.String rowTag) Names the tag for the row enclosing XML element.
void	setSQLToXMLNameEscaping(boolean flag) Determines whether to turn on XML tag escaping for SQL object names, to ensure conversion to valid XML identifiers.
void	setUpdateColumnList(java.lang.String[] updColNames) Sets and limits the list of columns for INSERT and UPDATE operations.
void	setXSLT(java.io.Reader stylesheet, java.lang.String ref) Registers an XSL transformation that should be applied to generated XML.
void	setXSLT(java.lang.String stylesheet, java.lang.String ref) Registers an XSL transformation that should be applied to generated XML.
void	setXSLTParam(java.lang.String name, java.lang.String value) Sets the value of the top-level stylesheet parameter.
int	updateXML(Document doc) Updates the table given the XML document in a DOM tree form.
int	updateXML(java.io.InputStream xmlStream) Updates the table given the XML document in a stream form.
int	updateXML(java.io.Reader xmlStream) Updates the table given the XML document in a stream form.
int	updateXML(java.lang.String xmlDoc) Updates the table given the XML document in a string form.
int	updateXML(java.net.URL url) Updates the columns in a database table, based on the element values in the input XML document.
void	useDBDates(boolean flag) Tells XSU to assume dates in XML doc are in DB format.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_BATCH_SIZE

public static int DEFAULT_BATCH_SIZE

The default insert batch size is 17 records

DATE_FORMAT

public static final java.lang.String DATE_FORMAT

The date format for use in setDateFormat.

See Also:

Constant Field Values

xDocIsEsc

public boolean xDocIsEsc

Constructor Detail

OracleXMLSave

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

Constructor for the OracleXMLSave class.

Parameters:

oconn - Connection object for accessing the database

tabName - The name of the table that should be updated

Method Detail

setPreserveWhitespace

public void setPreserveWhitespace(boolean flag)

Specifies whether to preserve whitespace..

Parameters:

flag - TRUE to preserve whitespace

useDBDates

public void useDBDates(boolean flag)

Tells XSU to assume dates in XML doc are in DB format.

Parameters:

flag - use DB dates?

setXSLT

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

Registers an XSL transformation that should be applied to generated XML. Replaces a previously registered stylesheet. To deregister the stylesheet, pass a null in the stylesheet parameter.

Parameters:

stylesheet - the stylesheet URI

ref - URL for include, import and external entities

setXSLT

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

Registers an XSL transformation that should be applied to generated XML. Replaces a previously registered stylesheet. To deregister the stylesheet, pass a null in the stylesheet parameter.

Parameters:

stylesheet - the stylesheet

ref - URL for include, import and external entities

setXSLTParam

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

Sets the value of the top-level stylesheet parameter. This value must be a valid XPath expression; string literal values have to be explicitly quoted. This method is a no-op if a stylesheet is not registered.

Parameters:

name - parameter name

value - parameter value as an XPATH expression

removeXSLTParam

public void removeXSLTParam(java.lang.String name)

Removes the value of a top-level stylesheet parameter. This method is a no-op if a stylesheet is not registered.

Parameters:

name - parameter name

setCommitBatch

public void setCommitBatch(int size)

Sets the commit batch size, or the number of records inserted before a commit. If size < 1 or the session is in "auto-commit" mode, no explicit commits are made. The default size is 0.

Parameters:

size - commit batch size

setSQLToXMLNameEscaping

public void setSQLToXMLNameEscaping(boolean flag)

Determines whether to turn on XML tag escaping for SQL object names, to ensure conversion to valid XML identifiers.

Parameters:

flag - TRUE to turn on SQL to XML escaping

setIgnoreCase

public void setIgnoreCase(boolean ignore)

Sets XML element names, based on XML tags, to be case insensitive when converting to database columns and attributes. This may affect metadata caching while creating the OracleXMLSave object.

Parameters:

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

setRowTag

public void setRowTag(java.lang.String rowTag)

Names the tag for the row enclosing XML element. Setting the rowTag to null means that top level elements of the document correspond to table rows.

Parameters:

rowTag - tag name

setDateFormat

public void setDateFormat(java.lang.String mask)

Specifies the format of dates used in the XML document. The default setting format, or date mask, is MM/dd/yyyy HH:mm:ss. The defualt override should conform to requirements of the java.text.SimpleDateFormat class. Setting the mask parameter to null</null> or empty string sets the default mask OracleXMLSave.DATE_FORMAT.

Parameters:

mask - the date mask

createURL

public java.net.URL createURL(java.lang.String fileName)

Returns the URL object for a specified file or URL. If the target parameter is not a valid URL format, "http://..." or "file://...", tries to create a URL object of the form "file://target". Returns null if the target parameter is null or an empty string.

Parameters:

fileName - The name of the file

Returns:

the URL object identifiying the target entity

getURL

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

finalize

protected void finalize()

close

public void close()

Closes the OracleXMLSave object and deallocates all context associated with it.

cleanLobList

public void cleanLobList()

This function frees all temporary LOBs

insertXML

public int insertXML(java.net.URL url)

Inserts an XML document from a specified URL into a table, By default, matches element names to column names, and sets columns with missing elements in input to null</null>. To restrict insertion to a subset of a table's columns and allow the other columns to hold a default value, use the setUpdateColumnList() method. Set the key column by a setKeyColumnList() call. 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 into EMPNO, HIREDATE, and SALARY and let the default values handle the rest of the columns: String insArray = new String[3]; insArray[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 - URL to the input XML document used to populate the table

Returns:

The number of rows inserted.

insertXML

public int insertXML(java.lang.String xmlDoc)
              throws java.io.IOException

Throws:

java.io.IOException

insertXML

public int insertXML(java.io.Reader xmlStream)

insertXML

public int insertXML(java.io.InputStream xmlStream)

insertXML

public int insertXML(Document doc)

updateXML

public int updateXML(java.net.URL url)

Updates the columns in a database table, based on the element values in the input XML document. Requires a key column that contains unique identifiers of rows that must be changed. By default, uses the list of key columns to match XML elements to table rows, and updates the entire row. Each row update is treated as a separate UPDATE transaction. To restrict update to a subset of columns and allow the other columns to hold previous values, use the setUpdateColumnList() method. This has the added benefit of improving performance by caching the UPDATE statement and batching transactions. 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 - URL to the input XML document used to update the table

Returns:

The number of XML row elements processed. This may not be equivalent to the number of database rows modified if the rows selected through the XML document do not uniquely identify the table rows.

updateXML

public int updateXML(java.lang.String xmlDoc)
              throws java.io.IOException

Updates the table given the XML document in a string form. Requires a key column that contains unique identifiers of rows that must be changed. By default, uses the list of key columns to match XML elements to table rows, and updates the entire row. Each row update is treated as a separate UPDATE transaction. To restrict update to a subset of columns and allow the other columns to hold previous values, use the setUpdateColumnList() method. This has the added benefit of improving performance by caching the UPDATE statement and batching transactions.

Parameters:

xmlDoc - The string form of the XML document

Returns:

The number of XML row elements processed. This may not be equivalent to the number of database rows modified if the rows selected through the XML document do not uniquely identify the table rows.

Throws:

java.io.IOException

updateXML

public int updateXML(java.io.Reader xmlStream)

Updates the table given the XML document in a stream form. Requires a key column that contains unique identifiers of rows that must be changed. By default, uses the list of key columns to match XML elements to table rows, and updates the entire row. Each row update is treated as a separate UPDATE transaction. To restrict update to a subset of columns and allow the other columns to hold previous values, use the setUpdateColumnList() method. This has the added benefit of improving performance by caching the UPDATE statement and batching transactions.

Returns:

The number of XML row elements processed. This may not be equivalent to the number of database rows modified if the rows selected through the XML document do not uniquely identify the table rows.

updateXML

public int updateXML(java.io.InputStream xmlStream)

Updates the table given the XML document in a stream form. Requires a key column that contains unique identifiers of rows that must be changed. By default, uses the list of key columns to match XML elements to table rows, and updates the entire row. Each row update is treated as a separate UPDATE transaction. To restrict update to a subset of columns and allow the other columns to hold previous values, use the setUpdateColumnList() method. This has the added benefit of improving performance by caching the UPDATE statement and batching transactions.

Returns:

The number of XML row elements processed. This may not be equivalent to the number of database rows modified if the rows selected through the XML document do not uniquely identify the table rows.

updateXML

public int updateXML(Document doc)

Updates the table given the XML document in a DOM tree form. Requires a key column that contains unique identifiers of rows that must be changed. By default, uses the list of key columns to match XML elements to table rows, and updates the entire row. Each row update is treated as a separate UPDATE transaction. To restrict update to a subset of columns and allow the other columns to hold previous values, use the setUpdateColumnList() method. This has the added benefit of improving performance by caching the UPDATE statement and batching transactions.

Returns:

The number of XML row elements processed. This may not be equivalent to the number of database rows modified if the rows selected through the XML document do not uniquely identify the table rows.

deleteXML

public int deleteXML(java.net.URL url)

Deletes rows from a table based on element values of the input XML document. By default, matches all XML element values with corresponding column names. Each row deletion is treated as a separate DELETE transaction. You can use a partial matching approach and limit the number of elements used to identify a row by using the setKeyColumnList() method. This has the added benefit of improving performance by caching the DELETE statement and batching transactions. 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 - URL to the XML document used to identify rows for deletion from the table

Returns:

The number of XML row elements processed. This may not be equivalent to the number of database rows deleted if the rows selected through the XML document do not uniquely identify the table rows.

deleteXML

public int deleteXML(java.lang.String xmlDoc)
              throws java.io.IOException

Deletes the rows in the table based on the XML document. By default, matches all XML element values with corresponding column names. Each row deletion is treated as a separate DELETE transaction. You can use a partial matching approach and limit the number of elements used to identify a row by using the setKeyColumnList() method. This has the added benefit of improving performance by caching the DELETE statement and batching transactions.

Parameters:

xmlDoc - The XML document in String form

Returns:

The number of XML row elements processed. This may not be equivalent to the number of database rows deleted if the rows selected through the XML document do not uniquely identify the table rows.

Throws:

java.io.IOException

deleteXML

public int deleteXML(java.io.Reader xmlStream)

Deletes the rows in the table based on the XML document. By default, matches all XML element values with corresponding column names. Each row deletion is treated as a separate DELETE transaction. You can use a partial matching approach and limit the number of elements used to identify a row by using the setKeyColumnList() method. This has the added benefit of improving performance by caching the DELETE statement and batching transactions.

Returns:

The number of XML row elements processed. This may not be equivalent to the number of database rows deleted if the rows selected through the XML document do not uniquely identify the table rows.

deleteXML

public int deleteXML(java.io.InputStream xmlStream)

Deletes the rows in the table based on the XML document. By default, matches all XML element values with corresponding column names. Each row deletion is treated as a separate DELETE transaction. You can use a partial matching approach and limit the number of elements used to identify a row by using the setKeyColumnList() method. This has the added benefit of improving performance by caching the DELETE statement and batching transactions.

Returns:

The number of XML row elements processed. This may not be equivalent to the number of database rows deleted if the rows selected through the XML document do not uniquely identify the table rows.

deleteXML

public int deleteXML(Document doc)

Deletes the rows in the table based on the XML document By default, matches all XML element values with corresponding column names. Each row deletion is treated as a separate DELETE transaction. You can use a partial matching approach and limit the number of elements used to identify a row by using the setKeyColumnList() method. This has the added benefit of improving performance by caching the DELETE statement and batching transactions.

Returns:

The number of XML row elements processed. This may not be equivalent to the number of database rows deleted if the rows selected through the XML document do not uniquely identify the table rows.

setBatchSize

public void setBatchSize(int size)

Changes the batch size used during DML operations. Batching operations improves performance by reducing the overhead of individual database access read/write operations to a single one. More memory is needed to hold the statements prior to a commit, as commits occur once per batch. If a single statement fails, the entire batch is rolled back. If this behavior is unaccepatable, set size to 1. The default batch size is DEFAULT_BATCH_SIZE.

Parameters:

size - The batch size used for all DMLs.

setKeyColumnList

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

Sets the list of columns used to identify table rows against XML input document elements prior to UPDATE and DELETE operations. This call is mandatory for UPDATEs and optional for DELETEs. Update and deletion based on key column values is a no-op.

Parameters:

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

setUpdateColumnList

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

Sets and limits the list of columns for INSERT and UPDATE operations. Only these columns will be updated, leaving other values in the record in their previous states. Only values of these columns will be added when inserting a new record, setting other values to the pre-defined table default.

Parameters:

updColNames - The string list of columns to be updated.