Skip navigation links

Oracle® Database XML Java API Reference
12c Release 1 (12.1)

E15981-09


oracle.xml.sql.dml
Class OracleXMLSave

java.lang.Object
  extended by 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 the OracleXMLSave class on the table. Many useful functions are provided to help identify key columns for UPDATE or DELETE, and to restrict the set of columns being updated. A typical sequence might look like this:


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.
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 the comparison mode.
 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
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 the comparison mode. When driving DML (INSERT, UPDATE, DELETE) from an XML document, the XML element names and attribute names, based on XML tags, are compared to the list of column names. Using ignore = true causes the comparison to be case insensitive by converting both values to upper case, using the Locale for English (i.e., java.util.Locale.ENGLISH). This may affect metadata caching while creating the OracleXMLSave object. It can also have unexpected effects when using names that contain non-English characters (i.e., characters that are outside of the range of US ASCII).
Parameters:
ignore - ignore tag case in the XML doc?

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 default 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

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.
Parameters:
xmlDoc - The stream 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.

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.
Parameters:
xmlDoc - The stream 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.

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.
Parameters:
xmlDoc - The DOM tree 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.

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.
Parameters:
xmlDoc - The XML document in Stream 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.

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.
Parameters:
xmlDoc - The XML document in Stream 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.

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.
Parameters:
xmlDoc - The XML document in DOM 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.

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.

Skip navigation links

Oracle® Database XML Java API Reference
12c Release 1 (12.1)

E15981-09


Copyright © 2003, 2014, Oracle and/or its affiliates. All rights reserved.