All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class de.tudarmstadt.ito.xmldbms.DBMSToDOM

java.lang.Object
   |
   +----de.tudarmstadt.ito.xmldbms.DBMSToDOM

public class DBMSToDOM

extends Object

DBMSToDOM transfers data from the database to a DOM tree according to a particular Map. The caller must provide a DocumentFactory for the DOM implementation they are using (many are available in de.tudarmstadt.ito.domutils), a Map object, and information about how to retrieve the data. The latter can be one or more table names and key values, a DocumentInfo object, or a result set.

For example, the following code transfers data for sales order number 123 from the Sales table to a DOM tree using Oracle's DOM implementation:

    // Use a user-defined function to create a map.
    Map map = createMap("sales.map", conn);

    // Create a new DBMSToDOM object.
    DBMSToDOM dbmsToDOM = new DBMSToDOM(map, new DF_Oracle());

    // Create a key and retrieve the data.
    Object[] key = {new Integer(123)};
    Document doc = dbmsToDOM.retrieveDocument("Sales", key);
 

Currently, no DOM implementations allow the namespace of an element or attribute to be set. Therefore, the caller can choose whether element and attribute names are prefixed according to the namespace prefixes in the Map. This is useful if the DOM tree will be serialized as an XML document. It might cause problems if the DOM tree is to be used directly, as the DOM implementation will not correctly return the base name, the namespace URI, or the qualified name. That is, it will return the prefixed name as the base name and qualified name and null as the namespace URI. By default, namespace prefixes are not used.

Version:

1.01

Author:

Ronald Bourret, Technical University of Darmstadt

DBMSToDOM()

Construct a new DBMSToDOM object.

DBMSToDOM(Map, DocumentFactory)

Construct a new DBMSToDOM object and set the Map and DocumentFactory objects.

getDocumentFactory()

Get the current DocumentFactory.

getMap()

Get the current Map.

retrieveDocument(DocumentInfo)

Construct a DOM Document according to the information in a DocumentInfo object.

retrieveDocument(ResultSet)

Construct a DOM Document from a result set.

retrieveDocument(String, Object[])

Construct a DOM Document from the specified table.

retrieveDocument(String[], Object[][])

Construct a DOM Document from the specified tables.

setDocumentFactory(DocumentFactory)

Set the current DocumentFactory.

setMap(Map)

Set the current Map.

usePrefixes(boolean)

State whether element and attribute names should be prefixed according to the namespace prefixes in the Map.

 public DBMSToDOM()

Construct a new DBMSToDOM object.

 public DBMSToDOM(Map map,
                  DocumentFactory factory)

Construct a new DBMSToDOM object and set the Map and DocumentFactory objects.

 public Map getMap()

Get the current Map.

Returns:

The current Map.

 public void setMap(Map map)

Set the current Map.

Parameters:

map - The current Map.

 public DocumentFactory getDocumentFactory()

Get the current DocumentFactory.

Returns:

The current DocumentFactory.

 public void setDocumentFactory(DocumentFactory factory)

Set the current DocumentFactory.

Parameters:

factory - The current DocumentFactory.

 public void usePrefixes(boolean usePrefixes)

State whether element and attribute names should be prefixed according to the namespace prefixes in the Map.

Parameters:

usePrefixes - Whether to use prefixes.

 public Document retrieveDocument(ResultSet rs) throws InvalidMapException, SQLException, DocumentFactoryException

Construct a DOM Document from a result set.

In the simplest case, this method simply constructs a DOM Document from the result set. Depending on the Map, data may be retrieved from subordinate tables as well. Note that the Map must map an element type to a table named "Result Set".

If the result set contains more than one row, the Map must specify an ignored root type; otherwise, a DOMException is thrown.

This method closes the result set.

Parameters:

rs - The result set.

Throws: DocumentFactoryException

Thrown if an error occurs creating an empty Document.

Throws: DOMException

Thrown if a DOM error occurs. One possible cause of this is that the result set contains more than one row and there was no ignored root element type.

Throws: InvalidMapException

Thrown if the Map is not set or more than one ignored root type is specified.

Throws: SQLException

Thrown if an error occurs retrieving data from the database.

 public Document retrieveDocument(String tableNames[],
                                  Object keys[][]) throws InvalidMapException, SQLException, DocumentFactoryException

Construct a DOM Document from the specified tables.

In the simplest case, this method simply constructs a DOM Document from the specified tables and rows. Depending on the Map, data may be retrieved from subordinate tables as well.

If more than one row is retrieved from the specified tables, the Map must specify an ignored root type; otherwise, a DOMException is thrown.

Parameters:

tableNames - The names of the tables from which to retrieve data.

keys - The keys used to retrieve data. There must be the same number of keys as tables.

Throws: DocumentFactoryException

Thrown if an error occurs creating an empty Document.

Throws: DOMException

Thrown if a DOM error occurs. One possible cause of this is that more than one row was retrieved from the specified tables and there was no ignored root element type.

Throws: InvalidMapException

Thrown if the Map is not set or more than one ignored root type is specified.

Throws: SQLException

Thrown if an error occurs retrieving data from the database.

 public Document retrieveDocument(String tableName,
                                  Object key[]) throws DOMException, InvalidMapException, SQLException, DocumentFactoryException

Construct a DOM Document from the specified table.

In the simplest case, this method simply constructs a DOM Document from the row(s) in the specified table. Depending on the Map, data may be retrieved from subordinate tables as well.

If more than one row is retrieved from the specified table, the Map must specify an ignored root type; otherwise, a DOMException is thrown.

Parameters:

tableName - The name of the table from which to retrieve data.

key - The key used to retrieve data.

Throws: DocumentFactoryException

Thrown if an error occurs creating an empty Document.

Throws: DOMException

Thrown if a DOM error occurs. One possible cause of this is that more than one row retrieved from the specified table and there was no ignored root element type.

Throws: InvalidMapException

Thrown if the Map is not set or more than one ignored root type is specified.

Throws: SQLException

Thrown if an error occurs retrieving data from the database.

 public Document retrieveDocument(DocumentInfo docInfo) throws DOMException, InvalidMapException, SQLException, DocumentFactoryException

Construct a DOM Document according to the information in a DocumentInfo object.

In the simplest case, this method simply constructs a DOM Document from the row(s) specified in the DocumentInfo object. Depending on the Map, data may be retrieved from subordinate tables as well.

If more than one row is retrieved from the tables specified in the DocumentInfo object, the Map must specify an ignored root type; otherwise, a DOMException is thrown.

Parameters:

docInfo - The DocumentInfo specifying which rows to retrieve.

Throws: DocumentFactoryException

Thrown if an error occurs creating an empty Document.

Throws: DOMException

Thrown if a DOM error occurs. One possible cause of this is that more than one row retrieved from the specified tables and there was no ignored root element type.

Throws: InvalidMapException

Thrown if the Map is not set or more than one ignored root type is specified.

Throws: SQLException

Thrown if an error occurs retrieving data from the database.

All Packages  Class Hierarchy  This Package  Previous  Next  Index