Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | 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 or views. It supports inserts, updates and deletes. The user first creates the class by passing in the table name on which these DML operations need to be done. After that, the user is free to use the insert/update/delete on this table. A typical sequence might look like 

 OracleXMLSave sav = new OracleXMLSave(conn, "emp");
 // insert processing
 sav.insertXML(xmlDoc);
 -or-
 // Update processing
  String[]tempArr = new String[2];
  tempArr[0] = "EMPNO";   // set the empno as the key for updates..
  sav.setKeyColumnList(tempArray);
 sav.updateXML(xmlDoc);
 -or-
 sav.deleteXML(xmlDoc);
 sav.close();
A lot of useful functions are provided in this class to help in identifying the key columns for update or delete and to restrict the columns being updated.

Field Summary
TypeField
static java.lang.String DATE_FORMAT
          The date format for use in setDateFormat
static int DEFAULT_BATCH_SIZE
          default insert batch size is 17
 boolean xDocIsEsc
           
 
Constructor Summary
OracleXMLSave(java.sql.Connection oconn, oracle.xml.sql.dml.OracleColumnName[] colNames)
          Constructor for internal use
OracleXMLSave(java.sql.Connection oconn, java.lang.String tabName)
          The public constructor for the Save class.
 
Method Summary
TypeMethod
 void cleanLobList()
           
 void close()
          It closes/deallocates all the context associated with this object.
 void collectTimingInfo(boolean collect)
          Internal use
 java.net.URL createURL(java.lang.String fileName)
          Deprecated. since XSU2.0 -- use the static version of this method instead
 int deleteXML(Document doc)
          Deletes the rows in the table based on the XML document
 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 specified table based on the element values in the supplied XML document.
protected  void finalize()
           
 oracle.sql.STRUCT getStructVal(Node xmlNode, oracle.xml.sql.dml.OracleColumnName colName)
          Internally used function.
 java.lang.String getTimingInfo()
          Internal use
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 the specified table, By default, the insert routine inserts the values into the table by matching the element name with the column name and inserts a null value for all elements that are missing in the input document.
 void removeXSLTParam(java.lang.String name)
          Removes the value of a top-level stylesheet parameter.
 void setBatchSize(int size)
          This call changes the batch size used during DML operations.
 void setCommitBatch(int size)
          Sets the commit batch size.
 void setDateFormat(java.lang.String mask)
          Describes to the XSU the format of the dates in the XML document.
 void setIgnoreCase(boolean ignore)
          The XSU does mapping of XML elements to database columns/attrs.
 void setKeyColumnList(java.lang.String[] keyColNames)
          Sets the list of columns to be used for identifying a particular row in the database table during update or delete.
 void setRowTag(java.lang.String rowTag)
          Names the tag used in the XML doc., to enclose the XML elements corresponding to each row value.
 void setSQLToXMLNameEscaping(boolean flag)
          This turns on or off escaping of XML tags in the case that the SQL object name, which is mapped to a XML identifier, is not a valid XML identifier.
 void setUpdateColumnList(java.lang.String[] updColNames)
          Set the column values to be updated.
 void setXSLT(java.io.Reader stylesheet, java.lang.String ref)
          Registers a XSL transform to be applied to generated XML.
 void setXSLT(java.lang.String stylesheet, java.lang.String ref)
          Registers a XSL transform to be applied to generated XML.
 void setXSLTParam(java.lang.String name, java.lang.String value)
          Sets the value of a 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 supplied 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
default insert batch size is 17

DATE_FORMAT

public static final java.lang.String DATE_FORMAT
The date format for use in setDateFormat

xDocIsEsc

public boolean xDocIsEsc
Constructor Detail

OracleXMLSave

public OracleXMLSave(java.sql.Connection oconn,
                     java.lang.String tabName)
The public constructor for the Save class.
Parameters:
oconn - Connection object (connection to the database)
tableName - The name of the table that should be updated

OracleXMLSave

public OracleXMLSave(java.sql.Connection oconn,
                     oracle.xml.sql.dml.OracleColumnName[] colNames)
Constructor for internal use
Method Detail

setXSLT

public void setXSLT(java.lang.String stylesheet,
                    java.lang.String ref)
Registers a XSL transform to be applied to generated XML. If a stylesheet was already registered, it gets replaced by the new one. To un-register the stylesheet pass in a null for the stylesheet argument.
Parameters:
stylesheet - the stylesheet URI
ref - URL for include, import and external entities

setXSLT

public void setXSLT(java.io.Reader stylesheet,
                    java.lang.String ref)
Registers a XSL transform to be applied to generated XML. If a stylesheet was already registered, it gets replaced by the new one. To un-register the stylesheet pass in a null for the stylesheet argument.
Parameters:
stylesheet - the stylesheet
ref - URL for include, import and external entities

setXSLTParam

public void setXSLTParam(java.lang.String name,
                         java.lang.String value)
Sets the value of a top-level stylesheet parameter. The parameter value is expected to be a valid XPath expression (note that string literal values would therefore have to be explicitly quoted). NOTE: if no stylesheet is registered, this method is a no op.
Parameters:
name - parameter name
value - parameter value as an XPATH expression

removeXSLTParam

public void removeXSLTParam(java.lang.String name)
Removes the value of a top-level stylesheet parameter. NOTE: if no stylesheet is registered, this method is a no op.
Parameters:
name - parameter name

setCommitBatch

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

setSQLToXMLNameEscaping

public void setSQLToXMLNameEscaping(boolean flag)
This turns on or off escaping of XML tags in the case that the SQL object name, which is mapped to a XML identifier, is not a valid XML identifier.
Parameters:
flag - turn on SQL->XML escaping?

setIgnoreCase

public void setIgnoreCase(boolean ignore)
The XSU does mapping of XML elements to database columns/attrs. based on the element names (xml tags). This function tells the XSU to do this match case insensitive. This resetting of case may affect the metadata caching that is done when creating the Save object.
Parameters:
flag - ignore tag case in the XML doc? 0-false 1-true

setRowTag

public void setRowTag(java.lang.String rowTag)
Names the tag used in the XML doc., to enclose the XML elements corresponding to each row value. Setting the value of this to null implies that there is no row tag present and the top level elements of the document correspond to the rows themselves.
Parameters:
tag - tag name

setDateFormat

public void setDateFormat(java.lang.String mask)
Describes to the XSU the format of the dates in the XML document. By default, OracleXMLSave assumes that the date is in format 'MM/dd/yyyy HH:mm:ss'. You can override this default format by calling this function. The syntax of the date format patern (i.e. the date mask), should conform to the requirements of the java.text.SimpleDateFormat class. Setting the mask to null or an empty string, results the use of the default mask -- OracleXMLSave.DATE_FORMAT.
Parameters:
mask - the date mask

createURL

public java.net.URL createURL(java.lang.String fileName)
Deprecated. since XSU2.0 -- use the static version of this method instead

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()
It closes/deallocates all the context associated with this object.

getStructVal

public oracle.sql.STRUCT getStructVal(Node xmlNode,
                                      oracle.xml.sql.dml.OracleColumnName colName)
                               throws java.sql.SQLException,
                                      java.text.ParseException,
                                      java.io.IOException
Internally used function.

cleanLobList

public void cleanLobList()

collectTimingInfo

public void collectTimingInfo(boolean collect)
Internal use

getTimingInfo

public java.lang.String getTimingInfo()
Internal use

insertXML

public int insertXML(java.net.URL url)
Inserts an XML document from a specified URL into the specified table, By default, the insert routine inserts the values into the table by matching the element name with the column name and inserts a null value for all elements that are missing in the input document. By setting the list of columns to insert using the setUpdateColumnList() you can restrict the insert to only insert values into those columns and let the default values for other columns to be inserted. That is no null value would be inserted for the rest of the columns Use setKeyColumnList() to set the list of all key column. Use setUpdateColumnList() to set the list of columns to update. For example, consider the employee table emp, TABLE emp( empno NUMBER, ename VARCHAR2(20), hiredate DATE); Now, assume that you want to insert the table using an XML document OracleXMLSave save = new OracleXMLSave(conn,"emp"); save.insertXML(xmlDoc); // xmlDoc supplied.. save.close(); If you want to insert values only in to EMPNO, HIREDATE and SALARY and let the default values handle the rest of the columns, String insArray = new String[3]; insArrary[0] = "EMPNO"; insArray[1] = "HIREDATE"; insArray[2] = "SALARY"; save.setUpdateColumnList(insArray); save.insertXML(xmlDoc); // will only insert values into EMPNO, HIREDATE // and SALARY columns
Parameters:
url - The URL to the document to use to insert rows into the table
Returns:
The number of rows inserted.

insertXML

public int insertXML(java.lang.String xmlDoc)

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 supplied XML document. The update requires a list of key columns which are used to uniquely identify a row to update in the given table. By default, the update uses the list of key columns and matches the values of the corresponding elements in the XML document to identify a particular row and then updates all the columns in the table for which there is an equivalent element present in the XML document. Each ROW element present in the input document is treated as a separate update to the table. You can also supply a list of columns to update - this will make the utility update only those columns and ignore any other element present in the XML document. This is a very efficient method, since if there are more than one row present in the input XML document, the update statement itself is cached and batching is done. If not, then we need to create a new update statement for each row of the input document. Use setKeyColumnList() to set the list of all key column. Use setUpdateColumnList() to set the list of columns to update. For example, consider the employee table emp, TABLE emp( empno NUMBER, ename VARCHAR2(20), hiredate DATE); Now, assume that you want to update the table using an XML document and you want to use the values of the element EMPNO to match the right row and then only update the HIREDATE column. You can send in an XML document containing the HIREDATE value and the EMPNO value and call the updateXML routine with the setKeyColumnList() containing the EMPNO string. OracleXMLSave save = new OracleXMLSave(conn,"emp"); String[] keyArray = new String[1]; keyArray[0] = "EMPNO"; // Set EMPNO as key column save.setKeyColumnList(keyArray); // Set the key column names String[] updArray = new String[1]; updArray[0] = "HIREDATE"; // SEt hiredate as column to update save.setUpdateColumnList(updArray); save.updateXML(xmlDoc); // xmlDoc supplied.. save.close();
Parameters:
url - The URL to the document to use to update the table
Returns:
The number of XML row elements processed. Note that this may or may not be equal to the number of database rows modified based on whether the rows selected through the XML document uniquely identified the rows in the table.

updateXML

public int updateXML(java.lang.String xmlDoc)
Updates the table given the XML document in a string form
Parameters:
xmlDoc - The string form of the XML document
Returns:
The number of XML elements processed
See Also:
for more information on the return value

updateXML

public int updateXML(java.io.Reader xmlStream)
Updates the table given the XML document in a stream form
Parameters:
xmlDoc - The stream form of the XML document
Returns:
The number of XML elements processed
See Also:
for more information on the return value

updateXML

public int updateXML(java.io.InputStream xmlStream)
Updates the table given the XML document in a stream form
Parameters:
xmlDoc - The stream form of the XML document
Returns:
The number of XML elements processed
See Also:
for more information on the return value

updateXML

public int updateXML(Document doc)
Updates the table given the XML document in a DOM tree form
Parameters:
xmlDoc - The DOM tree form of the XML document
Returns:
The number of XML elements processed
See Also:
for more information on the return value

deleteXML

public int deleteXML(java.net.URL url)
Deletes rows from a specified table based on the element values in the supplied XML document. By default, the delete processing matches all the element values with the corresponding column names. Each ROW element in the input document is taken as a separate delete statement on the table. By using the setKeyColumnList() you can set the list of columns that must be matched to identify the row to be deleted and ignore the other elements This is an effficient method for deleting more than one row in the table, since the delete statement is cached and batching can be employed. If not, a new delete statement has to be created for each ROW element in the input document. For example, consider the employee table emp, TABLE emp( empno NUMBER, ename VARCHAR2(20), hiredate DATE); Now, you want to delete the rows in the table using an XML document and you want to identify the row based on the EMPNO value. You can send in an XML document containing the EMPNO value and call the deleteXML routine with the setKeyColumnList() containing the EMPNO string. OracleXMLSave save = new OracleXMLSave(conn,"emp"); save.deleteXML(xmlDoc); // Deletes rows by matching all columns with the // element values in the input document. String[] deleteArray = new String[1]; deleteArray[0] = "EMPNO"; save.setKeyColumnList(deleteArray); // set the key columns save.deleteXML(xmlDoc); // only deletes rows by matching the EMPNO values
Parameters:
url - The URL to the document to use to delete the rows in the table
Returns:
The number of XML row elements processed. Note that this may or may not be equal to the number of database rows deleted based on whether the rows selected through the XML document uniquely identified the rows in the table.

deleteXML

public int deleteXML(java.lang.String xmlDoc)
Deletes the rows in the table based on the XML document
Parameters:
xmlDoc - The XML document in String form
Returns:
The number of XML ROW elements processed.
See Also:
for more infomration on the return value

deleteXML

public int deleteXML(java.io.Reader xmlStream)
Deletes the rows in the table based on the XML document
Parameters:
xmlDoc - The XML document in Stream form
Returns:
The number of XML ROW elements processed.
See Also:
for more infomration on the return value

deleteXML

public int deleteXML(java.io.InputStream xmlStream)
Deletes the rows in the table based on the XML document
Parameters:
xmlDoc - The XML document in Stream form
Returns:
The number of XML ROW elements processed.
See Also:
for more infomration on the return value

deleteXML

public int deleteXML(Document doc)
Deletes the rows in the table based on the XML document
Parameters:
xmlDoc - The XML document in DOM form
Returns:
The number of XML ROW elements processed.
See Also:
for more infomration on the return value

setBatchSize

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

setKeyColumnList

public void setKeyColumnList(java.lang.String[] keyColNames)
Sets the list of columns to be used for identifying a particular row in the database table during update or delete. This call is ignored for the insert case. The key columns must be set before updates can be done. It is optional for deletes. When this key columns is set, then the values from these tags in the XML document is used to identify the database row for update or delete. Currently, there is no way to update the values of the key columns themselves, since there is no way in the XML document to specify that case
Parameters:
keyColNames - The names of the list of columns that are used as keys

setUpdateColumnList

public void setUpdateColumnList(java.lang.String[] updColNames)
Set the column values to be updated. This is only valid for inserts and updates, and is ignored for deletes. In case of insert, the default is to insert values to all the columns in the table. In case of updates, the default is to only update the columns corresponding to the tags present in the ROW element of the XML document. When specified, these columns alone will get updated in the update or insert statement. All other elements in the document will be ignored.
Parameters:
updColNames - The string list of columns to be updated
Overview  Package   Class  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD