OracleXMLSave

Overview

Package

Class

Tree

Deprecated

Index

Help

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












  
      Overview 
      Package 
    Class 
      Tree 
      Deprecated 
      Index 
      Help 
  









 PREV CLASS 
 NEXT CLASS

  FRAMES   
 NO FRAMES   
 






  SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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.

oracle.xml.sql.dml Class OracleXMLSave

DEFAULT_BATCH_SIZE

DATE_FORMAT

xDocIsEsc

OracleXMLSave

setPreserveWhitespace

setXSLT

setXSLT

setXSLTParam

removeXSLTParam

setCommitBatch

setSQLToXMLNameEscaping

setIgnoreCase

setRowTag

setDateFormat

createURL

getURL

finalize

close

cleanLobList

insertXML

insertXML

insertXML

insertXML

insertXML

updateXML

updateXML

updateXML

updateXML

updateXML

deleteXML

deleteXML

deleteXML

deleteXML

deleteXML

setBatchSize

setKeyColumnList

setUpdateColumnList

oracle.xml.sql.dml
Class OracleXMLSave