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
Describes how an XML document is mapped to a database and vice versa; for limited use.

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);

Version:
1.01
Author:
Ronald Bourret, Technical University of Darmstadt

Constructor Index

 o Map(Table[], TableMap[], Hashtable, Hashtable, Hashtable, String[], String[], boolean, boolean, DateFormat, DateFormat, DateFormat)
Construct a new Map.

Method Index

 o closeStatements()
Close any open prepared statements.
 o getCreateTableStrings()
Return an array of CREATE TABLE statements.
 o initColumnMetadata(ResultSet)
Initialize the column metadata for the current Connection.
 o serialize(OutputStream, boolean, int)
Serialize a Map in the XML-DBMS mapping language to an OutputStream.
 o setConnection(Connection)
Initialize the Map to use a particular Connection; usually called only by map factories.

Constructors

 o Map
 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.

Methods

 o setConnection
 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.
 o initColumnMetadata
 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
 o serialize
 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.
 o closeStatements
 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.
 o getCreateTableStrings
 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.

All Packages  Class Hierarchy  This Package  Previous  Next  Index