Oracle8i XML Reference Guide Release 3 (8.1.7) Part Number A83730-01 |
|
This chapter contains the description of the XSU's java API:
public class OracleXMLSave extends java.lang.Object java.lang.Object | +--oracle.xml.sql.dml.OracleXMLSave
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.setUpdateKeyColumnList(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.
Inherited Member Summary |
---|
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
public static final java.lang.String DATE_FORMAT
public static int DEFAULT_BATCH_SIZE
default insert batch size is 17
public OracleXMLSave(java.sql.Connection oconn, java.lang.String tabName)
The public constructor for OracleXMLSave utility
public void close()
public int deleteXML(org.w3c.dom.Document doc)
Deletes records from the db. object corresponding to the records in an XML doc.
public int deleteXML(java.io.InputStream xmlStream)
Deletes records from the db. object corresponding to the records in an XML doc.
public int deleteXML(java.lang.String xmlDoc)
Deletes records from the db. object corresponding to the records in an XML doc.
public int deleteXML(java.net.URL url)
Deletes records from the db. object corresponding to the records in an XML doc.
public int insertXML(org.w3c.dom.Document doc) Inserts an XML document into a specified table. Returns the number of rows processed.
public int insertXML(java.io.InputStream xmlStream) Inserts an XML document into a specified table. Returns the number of rows processed.
public int insertXML(java.lang.String xmlDoc) Inserts an XML document into a specified table. Returns the number of rows processed.
public int insertXML(java.net.URL url) Inserts an XML document into a specified table. Returns the number of rows processed.
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.
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
public void setDateFormat(java.lang.String dateformat)
This sets the format of the date tags. By default, OracleXMLSave assumes that the date is in format 'MM/dd/yyyy HH:mm:ss' which is what is output by OracleXMLQuery is. You can override this by setting the format here. The format MUST be a valid format that can be understood by JDBC. See the JDBC documentation on java.text.SimpleDateFormat to get the list of valid date formats. This change is global. Passing a null value or an empty string resets this to the default format.
public void setIgnoreCase(boolean ignore)
setIgnoreCase ignores the case of the tag names when comparing them with the column names of the table/view. By default the tag names must be in the same case as that of the corresponding column names. Calling setIgnoreCase(true) will change it to ignore the case. Note: that after the first call to insertXML, we cache a lot of metadata. If setIgnoreCase status is changed, all the metadata has to be re-aquired.
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.
public void setRowTag(java.lang.String rowTag)
setRowTag sets the name of the ROW tag that is used to distinguish 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.
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 tags will be ignored.
public int updateXML(org.w3c.dom.Document doc)
This flavor of updateXML takes in a stream to the document
public int updateXML(java.io.InputStream xmlStream)
This flavor of updateXML takes in a stream to the document
public int updateXML(java.lang.String xmlDoc)
This flavor of updateXML takes in the XML document itself in the form of a String. Returns the number of Rows updated..!
public int updateXML(java.net.URL url)
Updates an XML document from a specified URL into a specified table, given a database connection object and a list of column names to update The column names can be null. updKeyNames lists the names of all columns for which the where clause is checked updColNames lists the column names to update.. For example, consider the employee table emp, TABLE emp( empno NUMBER, ename VARCHAR2(20), hiredate DATE); Now, you want to update the table using an XML document and you want to use the tag values EMPNO to get the right row to update and only update the hiredate values. You can send in an XML document containing the HIREDATE value and the EMPNO value and call the updateXML routine with the updKeyColNames containing the EMPNO string. 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.
Inherited Member Summary |
---|
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
public class OracleXMLQuery extends java.lang.Object java.lang.Object | +--oracle.xml.sql.query.OracleXMLQuery
The OracleXMLQuery class does the generation of XML given a SQL query. Following is a very simple example:
import java.sql.*; import oracle.xml.sql.query.*; import oracle.jdbc.driver.*; public class sample { public static void main(String args[]) throws Exception { DriverManager.registerDriver(new oracle.jdbc.driver.OracleDriver()); Connection conn = DriverManager.getConnection("jdbc:oracle:oci8:scott/tiger@"); OracleXMLQuery qry = new OracleXMLQuery(conn, "select * from emp"); System.out.println(qry.getXMLString()); conn.close(); } }
Inherited Member Summary |
---|
Methods inherited from class java.lang.Object |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
public static final int DTD
The DTD is used to specified that the DTD is to be generated
public static final java.lang.String ERROR_TAG
The ERROR_TAG specifies the default tag name for the ERROR document
public static final int MAXROWS_ALL
The MAXROWS_NONE specifies that all rows be included in the result
public static final int NONE
The NONE is used to specified that no DTD is to be generated
public static final java.lang.String ROW_TAG
The ROW_TAG specifies the default tag name for the ROW elements
public static final java.lang.String ROWIDATTR_TAG
The ROWIDATTR_TAG specifies the default tag name for the ROW elements
public static final java.lang.String ROWSET_TAG
The ROWSET_TAG specifies the default tag name for the document
public static final int SKIPROWS_ALL
The SKIPROWS_ALL specifies that all rows be skipped in the result This is the same as saying MAXROWS_NONE
public OracleXMLQuery(java.sql.Connection conn, java.sql.ResultSet rset)
public OracleXMLQuery(java.sql.Connection conn, java.lang.String sqlString)
public OracleXMLQuery(oracle.xml.sql.dataset.OracleXMLDataSet dset)
public void close()
close any open resource, created by the OracleXML engine. This will not close for instance resultset supplied by the user
public oracle.xml.sql.query.Document getXMLDOM()
getXMLDOM returns a DOM representation of the XML document using the OracleXMLDocGenDOM class to generate the DOM tree
public oracle.xml.sql.query.Document getXMLDOM(oracle.xml.sql.query.Node root)
The root node is also passed in. All the children created are appended to this root node. The return value is the whole document (the owner document of the root Node).
public oracle.xml.sql.query.Document getXMLDOM(oracle.xml.sql.query.Node root, int metaType)
This method returns a Document object containing the XML doc. The method takes a Node object which, if not NULL, is treated as the "root" node for the DOM tree of the XML doc. The other parameter is used to specify the type of XML metadata to be generated, if any.
public java.lang.String getXMLMetaData(int metaType, boolean withVersion)
This functions returns the DTD for the XML document which would have been generated by a getXML call. The "metaType" parameter specifies the type of XML metadata to be generated. Valid values is DTD. The withVersion parameter specifies if version header is to be generated or not.
public void getXMLMetaData(int metaType, boolean withVersion, oracle.xml.sql.docgen.OracleXMLDocGen doc)
public java.lang.String getXMLString()
getXMLString returns a string representation of the XML document using the OracleXMLDocGenString class to create the string; generates no DTD.
public java.lang.String getXMLString(int metaType)
getXMLString returns a string representation of the XML document using the OracleXMLDocGenString class to create the string.
public java.lang.String getXMLString(oracle.xml.sql.query.Node root)
All the children created are appended to this root node. A new ROWTAG tag is created under this root node and the children are added.
public java.lang.String getXMLString(oracle.xml.sql.query.Node root, int metaType)
This method returns a String object containing the XML doc. The method takes a Node object which, if not NULL, is treated as the "root" node for the DOM tree of the XML doc. The other parameter is used to specify the type of XML metadata to be generated, if any. Valid values are OracleXMLQuery.NONE and OracleXMLQuery.DTD. Note that when the root is non-null, no DTD is generated even if requested.
public void keepObjectOpen(boolean alive) The default behavior for all the getXML functions which DO NOT TAKE in a ResultSet object is to close the ResultSet object and Statement objects at the end of the call. If you need to use the persistant feature, where by calling getXML repeatedly you get the next set of rows, you need to turn off this behavior by calling this function with value true. i.e. OracleXMLQuery would not close the ResultSet and Statement objects after the getXML calls. You can call the close() function to explicitly close the cursor state.
public void setCollIdAttrName(java.lang.String collIdAttr)
Sets the collection element's id-attribute name. Passing in a null, or an empty string with inhibit the printing of the collIDAttr which is also the default behaviour.
public void setDataHeader(java.io.Reader header, java.lang.String docTag)
Sets the XML data header. When set, the header is inserted at the begining of the data part of each XML document generated by this object. The docTag parameter specifies the tag name to be used to enclose the XML resulting from adding the "header" and the generated XML. To unset the header, call this function with null passed in for the "header" parameter.
public void setDateFormat(java.lang.String mask)
Sets the format of the generated dates in the XML doc. 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, unsets the date mask.
mask
- the date mask
public void setEncoding(java.lang.String enc)
Sets the encoding PI (processing instruction) in the XML doc. If null
or an empty string are specified as the encoding, then the default characterset is specified in the encoding PI.
enc
- characterset encoding of the XML doc
public void setErrorTag(java.lang.String errorName)
setErrorTag sets the name of the error tag (default "ERROR") in case an error is raised. Remember that when an error is raised NO DTD is generated.
public void setException(java.lang.Exception e)
Allows the user to pass in an exception, and have the XSU handle it.
public void setMaxRows(int maxRows)
This sets the maximum number of rows to be retreived from the query result after "skipRows" number of rows are skipped You can use one of MAXROWS_NONE, MAXROWS_ALL, MAXROWS_DEFAULT
public void setMetaHeader(java.io.Reader header)
Sets the XML meta header. When set, the header is inserted at the begining of the metadata part (e.g. DTD) of each XML document generated by this object. To unset the header, call this function with null passed in for the "header" parameter.
public void setRaiseException(boolean exp)
setRaiseException function when called with the value true, will raise exceptions such as no-data found, instead of returning a NULL row out. You might want to catch the exception and handle the case
public void setRaiseNoRowsException(boolean exp)
set this to true to raise an Exception if no data is found default is false, meaning if no rows are found an empty document instance will be given Remember that setting this would raise the OracleXMLSQLException even if the actual ResultSet generated Data but because of the maxRows and skipRows parameter, no Rows were selected.
public void setRowIdAttrName(java.lang.String rowIdTag)
This sets the name of the attribute "ID" used in the row separator. By giving a value of null, you can turn off the ID printing
public void setRowIdAttrValue(java.lang.String colName)
This makes the ROW tag's id attribute to have the same value as that of the column name specified. The column must be a scalar column. A value of null would revert it to the default behaviour which is the row count.
public void setRowsetTag(java.lang.String rowsetName)
Sets the tag name which is to be used as markup for each resulting record/row. The default tag name is "ROW"; a null or empty string implies that each row is not to be markup encapsulated (i.e. no row separators are to be used. In this situation the result set produced by the query can either contain many record which are one column wide, or one record which is many columns wide.
public void setRowTag(java.lang.String rowTagName)
Sets the tag name which is to be used as markup for each resulting record/row. The default tag name is "ROW"; a null or empty string implies that each row is not to be markup encapsulated (i.e. no row separators are to be used. In this situation the result set produced by the query can either contain many record which are one column wide, or one record which is many columns wide.
public void setSkipRows(int skipRows)
This sets the number of rows to skip before printing the the result You can use one of SKIPROWS_NONE, SKIPROWS_ALL, SKIPROWS_DEFAULT
public void setStylesheetHeader(java.lang.String styleSheetURI)
public void setStylesheetHeader(java.lang.String styleSheetURI, java.lang.String styleSheetType)
public void setXSLT()
Registers a stylesheet 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
or an empty string for the stylesheet
argument.
public void setXSLT()
Registers a stylesheet 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
or an empty string for the stylesheet
argument.
public void useLowerCaseTagNames()
This will set the case to be lower for all tag names. Note, make this call after all the desired tags have been set.
public void useNullAttributeIndicator(boolean useNullAttr)
Specified weather to use an XML attribute to indicate NULLness; or to do it by omitting the inclusion of the particular entity in the XML document.
public void useUpperCaseTagNames()
This will set the case to be upper for all tag names. Note, make this call after all the desired tags have been set.
oracle.xml.sql.OracleXMLSQLExceptionpublic class OracleXMLSQLException extends java.lang.RuntimeException java.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--java.lang.RuntimeException | +--oracle.xml.sql.OracleXMLSQLException
OracleXMLSQLNoRowsException
java.io.Serializable
public OracleXMLSQLException(java.lang.Exception e)
public OracleXMLSQLException(java.lang.Exception e, java.lang.String errorTagName)
public OracleXMLSQLException(java.lang.String message)
public OracleXMLSQLException(java.lang.String message, java.lang.Exception e)
public OracleXMLSQLException(java.lang.String message, java.lang.Exception e, java.lang.String errorTagName)
public OracleXMLSQLException(java.lang.String message, int errorCode)
public OracleXMLSQLException(java.lang.String message, int errorCode, java.lang.String errorTagName)
public OracleXMLSQLException(java.lang.String message, java.lang.String errorTagName)
public int getErrorCode()
public java.lang.Exception getParentException()
returns the original exception, if there was one; otherwise, it returns null
public java.lang.String getXMLErrorString()
prints the XML error string with the given error tag name
public java.lang.String getXMLSQLErrorString()
prints the SQL parameters as well in the error message
public void setErrorTag(java.lang.String tagName)
Sets the error tag name which is then used by getXMLErrorString and getXMLSQLErrorString, to generate xml error reports
oracle.xml.sql.OracleXMLSQLNoRowsExceptionpublic class OracleXMLSQLNoRowsException extends OracleXMLSQLExceptionjava.lang.Object | +--java.lang.Throwable | +--java.lang.Exception | +--java.lang.RuntimeException | +--OracleXMLSQLException
| +--oracle.xml.sql.OracleXMLSQLNoRowsException
java.io.Serializable
Member Summary |
|
---|---|
Constructors |
|
OracleXMLSQLNoRowsException() |
|
OracleXMLSQLNoRowsException(String) |
|
public OracleXMLSQLNoRowsException()
public OracleXMLSQLNoRowsException(java.lang.String errorTag)
|
![]() Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
|