All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class org.xmlmiddleware.xmldbms.DOMToDBMS 

java.lang.Object
   |
   +----org.xmlmiddleware.xmldbms.DOMToDBMS
public class DOMToDBMS
extends Object
Transfers data from the database to a DOM tree.

DOMToDBMS transfers data from a DOM tree to the database according to a particular XMLDBMSMap and Actions object. The caller must provide a TransferInfo object, which contains the map and database handlers, a DOM Element or Document, and one or more actions to be taken when storing this data in the database.

For example, the following code transfers data from orders.xml according to the map document orders.map and the action document orders.act:

    // Create the XMLDBMSMap object with a user-defined function.
    map = createMap("orders.map");
    // Create the Actions object with a user-defined function.
    actions = createActions(map, "orders.act");
    // Create a new DOMToDBMS object.
    domToDBMS = new DOMToDBMS();
    // Create a data source and data handler for our database, then
    // bundle these into a TransferInfo object.
    ds = new JDBC1DataSource("sun.jdbc.odbc.JdbcOdbcDriver", "jdbc:odbc:xmldbms");
    handler = new GenericHandler(ds, null, null);
    ti = new TransferInfo(map, null, handler);
    // Open the document and call storeDocument to transfer the data.
    utils = new ParserUtilsXerces();
    doc = utils.openDocument(new InputSource(new FileInputStream("orders.xml")));
    domToDBMS.storeDocument(ti, doc, actions);

DOMToDBMS stores data starting with the first element it finds that is mapped as a class. It continues processing along a given branch until it finds an element that is not mapped. It then continues with the sibling of that element. Thus, DOMToDBMS stores data from one or more contiguous fragments of the DOM tree.

Version:
2.0
Author:
Sean Walter

Constructor Index

o DOMToDBMS()
Create a DOMToDBMS object.

Method Index

o addKeyGenerator(String, KeyGenerator)
Add a key generator by name

Applications call this method only if the map requires XML-DBMS to generate primary keys.

o getCommitMode()
Get the commit mode.
o getExceptions()
Returns a chain of all SQLExceptions generated while processing the last document.
o getWarnings()
Returns a chain of all SQLWarnings generated while processing the last document.
o isFilterSetReturned()
Whether storeDocument returns a FilterSet or a null.
o removeAllKeyGenerators()
Remove all key generators.
o removeKeyGenerator(String)
Remove a key generator.
o setCommitMode(int)
Set the commit mode.
o setFilterSetReturned(boolean)
Sets whether storeDocument returns a FilterSet or a null.
o stopOnException(boolean)
Defines how SQLExceptions are handled.
o storeDocument(TransferInfo, Document, Actions)
Store a DOM tree in the database using a set of actions.
o storeDocument(TransferInfo, Document, int)
Store a DOM tree in the database using a single action.
o storeDocument(TransferInfo, Element, Actions)
Store part of a document in the database using a set of actions.
o storeDocument(TransferInfo, Element, int)
Store part of a document in the database using a single action.

Constructors

o DOMToDBMS 
 public DOMToDBMS()
Create a DOMToDBMS object.

Returns:
The DOMToDBMS object.

Methods

o setCommitMode 
 public void setCommitMode(int commitMode)
Set the commit mode.

The commit mode must be one of DataHandler.COMMIT_AFTERSTATEMENT, COMMIT_AFTERDOCUMENT, COMMIT_NONE, or COMMIT_NOTRANSACTIONS. The default is COMMIT_AFTERSTATEMENT.

Parameters:
commitMode - The commit mode.
o getCommitMode 
 public int getCommitMode()
Get the commit mode.

Returns:
The mode.
o setFilterSetReturned 
 public void setFilterSetReturned(boolean value)
Sets whether storeDocument returns a FilterSet or a null.

storeDocument can return a FilterSet describing the document it processes. This can be used at a later point in time to retrieve the document. Whether such a FilterSet is useful depends on the application. As a general rule, it is not useful for data-centric applications. For these applications, XML is usually a data transport and documents have no persistent identity. It is useful for document-centric applications, for which documents do have a persistent identity.

By default, storeDocument returns a null. This saves some processing time, although the amount saved is likely to be noticeable only for very large documents.

Parameters:
value - Whether storeDocument returns a FilterSet
o isFilterSetReturned 
 public boolean isFilterSetReturned()
Whether storeDocument returns a FilterSet or a null.

For more information, see setFilterSetReturned.

Returns:
Whether storeDocument returns a FilterSet
o addKeyGenerator 
 public void addKeyGenerator(String name,
                             KeyGenerator generator)
Add a key generator by name

Applications call this method only if the map requires XML-DBMS to generate primary keys. (This does not include database-generated keys.)

Parameters:
name - The logical name of the key generator.
generator - An object that implements the KeyGenerator interface
o removeKeyGenerator 
 public void removeKeyGenerator(String name)
Remove a key generator.

Parameters:
name - The logical name of the key genenerator.
o removeAllKeyGenerators 
 public void removeAllKeyGenerators()
Remove all key generators.

o stopOnException 
 public void stopOnException(boolean stopOnException)
Defines how SQLExceptions are handled.

When an exception occurs, one of two things happens. If this is set to false, then the exception is added to the list returned by getExceptions and processing continues at the next class element. If this is set to true, then processing stops at the first exception.

By default, processing stops on exceptions.

Parameters:
stopOnException - Stop or not.
o getWarnings 
 public SQLWarning getWarnings()
Returns a chain of all SQLWarnings generated while processing the last document.

Returns:
The chain. Null if there were no SQLWarnings.
o getExceptions 
 public SQLException getExceptions()
Returns a chain of all SQLExceptions generated while processing the last document.

Returns:
The chain. Null if there were no SQLExceptions or stopOnException is set to true.
o storeDocument 
 public FilterSet storeDocument(TransferInfo transInfo,
                                Document doc,
                                int action) throws SQLException, XMLMiddlewareException
Store a DOM tree in the database using a single action.

Parameters:
transInfo - TransferInfo object containing the map and DataHandlers.
doc - The DOM document to store.
action - Action to take on the document.
Returns:
Null or a FilterSet describing the stored data. See setFilterSetReturned().
o storeDocument 
 public FilterSet storeDocument(TransferInfo transInfo,
                                Document doc,
                                Actions actions) throws SQLException, XMLMiddlewareException
Store a DOM tree in the database using a set of actions.

Parameters:
transInfo - TransferInfo object containing the map and DataHandlers.
doc - The DOM document to store.
action - Actions to take on various elements of the document.
Returns:
Null or a FilterSet describing the stored data. See setFilterSetReturned().
o storeDocument 
 public FilterSet storeDocument(TransferInfo transInfo,
                                Element el,
                                int action) throws SQLException, XMLMiddlewareException
Store part of a document in the database using a single action.

Parameters:
transInfo - TransferInfo object containing the map and DataHandlers.
el - Element defining the part of the document to store.
action - Action to take on the tree.
Returns:
Null or a FilterSet describing the stored data. See setFilterSetReturned().
o storeDocument 
 public FilterSet storeDocument(TransferInfo transInfo,
                                Element el,
                                Actions actions) throws SQLException, XMLMiddlewareException
Store part of a document in the database using a set of actions.

Parameters:
transInfo - TransferInfo object containing the map and DataHandlers.
el - Element defining the part of the document to store.
action - Actions to take on various elements of the tree.
Returns:
Null or a FilterSet describing the stored data. See setFilterSetReturned(). 
All Packages  Class Hierarchy  This Package  Previous  Next  Index