All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class de.tudarmstadt.ito.xmldbms.Map

java.lang.Object
   |
   +----de.tudarmstadt.ito.utils.XMLOutputStream
           |
           +----de.tudarmstadt.ito.xmldbms.Map

public class Map

extends XMLOutputStream

Map objects describe how XML documents are mapped to databases and vice versa. They are created by map factories, which can be found in de.tudarmstadt.ito.xmldbms.mapfactories. Map objects are opaque. That is, programmers create them with map factories and pass them to DOMToDBMS and DBMSToDOM objects, but never instantiate them directly or call methods on them.

For example, the following code creates a map from the sales.map mapping document.

    // Instantiate a new map factory from a database connection
    // and SAX parser.
    factory = new MapFactory_MapDocument(conn, parser);

    // Create a Map from sales.map.
    map = factory.createMap(new InputSource(new FileReader("sales.map")));

    // Pass the Map to DOMToDBMS.
    DOMToDBMS = new DOMToDBMS(map);
 

Map(Table[], TableMap[], Hashtable, Hashtable, Hashtable, String[], String[], boolean, boolean, DateFormat, DateFormat, DateFormat)

Construct a new Map.

closeStatements()

Close any open prepared statements.

finalize()

getCreateTableStrings()

Return an array of CREATE TABLE statements.

initColumnMetadata(ResultSet)

Initialize the column metadata for the current Connection.

serialize(OutputStream, boolean, int)

Serialize a Map in the XML-DBMS mapping language to an OutputStream.

setConnection(Connection)

Initialize the Map to use a particular Connection; usually called only by map factories.

 public Map(Table tables[],
            TableMap tableMaps[],
            Hashtable rootTableMaps,
            Hashtable classMaps,
            Hashtable rootClassMaps,
            String prefixes[],
            String uris[],
            boolean generateKeys,
            boolean emptyStringIsNull,
            DateFormat dateFormatter,
            DateFormat timeFormatter,
            DateFormat timestampFormatter)

Construct a new Map.

 public void setConnection(Connection conn) throws SQLException

Initialize the Map to use a particular Connection; usually called only by map factories.

This method sets the Connection used by the Map and retrieves various database metadata used both when transferring data and when when constructing SQL statements. Until this method is called, the Map cannot be used to transfer data or get CREATE TABLE strings. It is legal to call the serialize() method before this method is called.

Generally, this method is called only by map factories that connect to the database, such as MapFactory_MapDocument. It can be called by applications, such as to use the same Map with different database, but such use is likely to be rare. If an application calls this method, they usually call initTableMetadata() directly afterwards to initialize the Map according the the table and column metadata of the new connection.

Throws: SQLException

Thrown if a problem occurs while retrieving the database metadata.

 public void initColumnMetadata(ResultSet mappedResultSet) throws SQLException, InvalidMapException

Initialize the column metadata for the current Connection.

This method initializes the column metadata for the current Connection. This metadata is used both when transferring data and when when constructing SQL statements. Until the metadata is set, either directly or by calling this method, the Map cannot be used to transfer data or get CREATE TABLE strings.

Generally, this method is called only by map factories that connect to the database, such as MapFactory_MapDocument. It is not called by map factories that generate their own column metadata, such as MapFactory_DTD, which predicts data types and lengths.

Parameters:

mappedResultSet - The result set from which to retrieve metadata if the Map maps an element type to a table named "Result Set". Ignored (and may be null) if no such table is named.

Throws: SQLException

Thrown if a problem occurs while retrieving the metadata.

Throws: InvalidMapException

Thrown if a column is not found.

See Also:

retrieveDocument

 public void serialize(OutputStream out,
                       boolean pretty,
                       int indent) throws IOException

Serialize a Map in the XML-DBMS mapping language to an OutputStream.

Note that serialize cannot currently create the Locale element or the values FULL, LONG, MEDIUM, or SHORT in the Date, Time, and Timestamp attributes of the Patterns element.

Parameters:

out - The OutputStream.

Throws: IOException

Thrown if an I/O exception occurs.

 public void closeStatements() throws SQLException

Close any open prepared statements.

By default, Maps maintain INSERT and DELETE statements in a prepared state for later use, such as when the same Map is used to transfer data from multiple documents. The statements are closed only when the application calls this method, the Map object is deleted (such as by the garbage collector), or the database closes them when committing a transaction.

Applications can use this method to close statements and release JDBC and database resources earlier than when it might be done by the garbage collector. Because this method does not close the Connection, the Map can be reused, although it must reprepare statements as needed.

For example, consider an application that maintains a pool of Maps, one for each type of XML document for which it transfers data. If each Map is used infrequently, the application might choose to free database resources by calling closeStatements() after each use of a given Map. Although the Map must reprepare statements each time it is used, this might result in better overall performance.

closeStatement() is called by Map.finalize().

Throws: SQLException

Thrown if a problem occurs while closing statements.

 public String[] getCreateTableStrings() throws InvalidMapException, SQLException

Return an array of CREATE TABLE statements.

This method returns an array of CREATE TABLE statements in the form of strings. Generally, the calling application will edit these strings before using them.

WARNING! These strings currently use hard-coded data type names; in the future, this method should retrieve data type names from the database.

Returns:

The array of CREATE TABLE statements.

Throws: InvalidMapException

The Map contained an invalid data type.

Throws: SQLException

An error occurred retrieving metadata from the database.

 protected void finalize() throws Throwable

Overrides:

finalize in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index