Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle® Application Server XML Java API Reference 10g Release 2 (10.1.2) Part no. B12024-03 September 2004
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

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

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

  Overrides:
    `finalize` in class `java.lang.Object`

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

    `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.
    `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.
    `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 `UPDATE`s and optional for `DELETE`s. 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.

Overview | Package | Class | Tree | Deprecated | Index | Help
| Oracle® Application Server XML Java API Reference 10g Release 2 (10.1.2) Part no. B12024-03 September 2004
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2003, 2004, Oracle. All rights reserved.