All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class org.xmlmiddleware.xmldbms.maps.factories.MapFactory_Database

java.lang.Object
   |
   +----org.xmlmiddleware.xmldbms.maps.factories.MapFactory_Database

public class MapFactory_Database

extends Object

Through primary key / foreign key references, the tables in a database form a graph. MapFactory_Database follows this graph and creates an XMLDBMSMap. Tables are mapped to elements with complex types and columns may be mapped either to attributes or to elements containing only PCDATA. The calling application specifies which tables to include in the map in any of a number of ways.

For example, the following code creates a map starting with the SalesOrders table.

    // Instantiate a new map factory and set the JDBC connection.
    factory = new MapFactory_Database(conn);

    // Create an XMLDBMSMap based on the graph including the SalesOrders table.
    map = factory.createMap("SalesOrders");

 

It is important to understand that an XMLDBMSMap is a directed graph. This is different from the tables in a database, which form an undirected graph. In particular, a primary key / foreign key link can be traversed in either direction; the hierarchy of an XML document forces you to choose one of those directions. That is, you can choose to traverse from primary key to foreign key (in which case, the primary key table is the parent) or from foreign key to primary key (in which case the foreign key table is the parent).

Which direction the XMLDBMSMap constructed by this class uses depends on the tables you choose as root table. For example, suppose we have the following graph of tables:

             SalesOrders
             /         \
          Lines     Customers
            |
          Parts
 

If you choose SalesOrders as the root table, then your XML documents will look like this:

    <SalesOrder>
       <Customer>
          ...
       </Customer>
       <Line>
          ...
          <Part>
             ...
          </Part>
       </Line>
       ...
    </SalesOrder>
 

On the other hand, if you choose Customers as the root table, your XML documents will look like this:

    <Customer>
       <SalesOrder>
          <Line>
             ...
             <Part>
                ...
             </Part>
          </Line>
          ...
       </SalesOrder>
       ...
    </Customer>
 

You have several different choices on how to construct the XMLDBMSMap. You can specify whether to follow primary key links (that is, links where the primary key is in the current table) and whether to following foreign key links (that is, links where the foreign key is in the current table). For example, following only primary key links in the first example above would have resulted in only the SalesOrders and Lines tables being included. Following only foreign key links would have resulted in only the SalesOrders and Customers tables being included.

You can also specify multiple root tables. This is useful when a graph has multiple leaf tables that you want to use as roots, but must be used carefully. In particular, if you start at one root and the graph leads back to another root (which is usually the case), the second root won't be processed. This can be avoided only by not following primary key links or foreign key links. For example, suppose you have the following graph, in which both the Students and Teachers tables both have primary keys:

     Students     Teachers
             \   /
            Courses
 

If you follow both primary and foreign key links and input both Teachers and Students as root tables (in that order), then the map can only generate the following XML document, since the Student table is processed by following the links from Teachers to Courses to Students:

    <Teacher>
       <Course>
          <Student>
             ...
          </Student>
          ...
       </Course>
       ...
   </Teacher>
 

On the other hand, if you only follow primary key links, then the factory does not follow the link from Courses back to Students and you can create either of the following XML documents:

    <Teacher>         <Student>
       <Course>          <Course>
          ...               ...
       </Course>         </Course>
       ...               ...
   </Teacher>         </Student>
 

The last option is that you can "trim" a graph by specifying "stop" tables. These are tables that are not included in the XMLDBMSMap. For example, in the first example above, if you only wanted to create an XML document with SalesOrders, Lines, and Parts, you could specify Customers as a stop table.

A word of final warning. No matter what options you choose, you should expect to modify your map by hand after it is generated. It is very easy to find examples of useful maps that cannot be generated from these criteria, and adding new criteria is not a high priority. In such cases, the best thing to do is to generate a map with too many tables, then remove and rearrange ClassMap and RelatedClass elements to get the map you want.

Version:

2.0

Author:

Ronald Bourret, 2001

MapFactory_Database()

Construct a new MapFactory_Database.

MapFactory_Database(Connection)

Construct a new MapFactory_Database and set the connection.

MapFactory_Database(String[], Connection[])

Construct a new MapFactory_Database and set the connections and database names.

areColumnsElementTypes()

Whether to generate child elements or attributes from columns.

columnsAreElementTypes(boolean)

Set whether to generate child elements or attributes from columns.

createMap(String, String, String)

Create a map from a single root table.

createMap(String[], String[])

Create a map for all tables in a catalog or catalogs.

createMap(String[], String[], String[])

Create a map for all tables in a schema or schemas.

createMap(String[], String[], String[], String[])

Create a map from a set of root tables.

createMap(String[], String[], String[], String[], String[], String[], String[], String[])

Create a map from a set of root tables, stopping at designated "stop" tables.

followForeignKeys()

Whether foreign key links are followed.

followForeignKeys(boolean)

Set whether foreign key links are followed.

followPrimaryKeys()

Whether primary key links are followed.

followPrimaryKeys(boolean)

Set whether primary key links are followed.

setConnection(Connection)

Set the database connection to use.

setConnections(String[], Connection[])

Set the database connections to use.

setNamespaceInfo(String, String)

Set the namespace URI and prefix of the generated element types.

 public MapFactory_Database()

Construct a new MapFactory_Database.

 public MapFactory_Database(Connection conn)

Construct a new MapFactory_Database and set the connection.

The database name is set to "Default".

Parameters:

conn - The database connection.

 public MapFactory_Database(String databaseNames[],
                            Connection connections[])

Construct a new MapFactory_Database and set the connections and database names.

Parameters:

databaseNames - An array of names for the databases in the connections argument.

connections - An array of database connections.

 public void setNamespaceInfo(String uri,
                              String prefix)

Set the namespace URI and prefix of the generated element types.

Generated attributes are not in any namespace (are unprefixed).

Parameters:

uri - The namespace URI. May be null.

prefix - The namespace prefix. May be null, even if the uri argument is not null.

 public final boolean areColumnsElementTypes()

Whether to generate child elements or attributes from columns.

Returns:

True if child elements are generated from columns; false if attributes are generated.

 public void columnsAreElementTypes(boolean useElementTypes)

Set whether to generate child elements or attributes from columns.

Parameters:

useElementTypes - True if child elements are generated from columns; false if attributes are generated.

 public void setConnection(Connection conn)

Set the database connection to use.

The database name is set to "Default".

Parameters:

conn - The database connection.

 public void setConnections(String databaseNames[],
                            Connection connections[])

Set the database connections to use.

Parameters:

databaseNames - An array of names for the databases in the connections argument.

connections - An array of database connections.

 public boolean followPrimaryKeys()

Whether primary key links are followed.

Returns:

Whether primary key links are followed.

 public void followPrimaryKeys(boolean followPrimaryKeys)

Set whether primary key links are followed.

Parameters:

followPrimaryKeys - Whether primary key links are followed.

 public boolean followForeignKeys()

Whether foreign key links are followed.

Returns:

Whether foreign key links are followed.

 public void followForeignKeys(boolean followForeignKeys)

Set whether foreign key links are followed.

Parameters:

followForeignKeys - Whether foreign key links are followed.

 public XMLDBMSMap createMap(String rootCatalogName,
                             String rootSchemaName,
                             String rootTableName) throws SQLException, XMLMiddlewareException

Create a map from a single root table.

The map factory will follow the graph from the root table until it ends.

All tables are assumed to be in a single database named "Default".

Parameters:

rootCatalogName - Name of the root catalog. May be null.

rootSchemaName - Name of the root schema. May be null.

rootTableName - Name of the root table.

Returns:

The XMLDBMSMap.

Throws: SQLException

An error occurred accessing the database.

Throws: XMLMiddlewareException

An error occurred building the map.

 public XMLDBMSMap createMap(String rootDatabaseNames[],
                             String rootCatalogNames[],
                             String rootSchemaNames[],
                             String rootTableNames[]) throws SQLException, XMLMiddlewareException

Create a map from a set of root tables.

The map factory will follow the graph from each root table until it ends.

Parameters:

rootDatabaseNames - Names of the root databases. If any entries are null, the name "Default" is used.

rootCatalogNames - Names of the root catalogs. Entries may be null.

rootSchemaNames - Names of the root schemas. Entries may be null.

rootTableNames - Names of the root tables.

Returns:

The XMLDBMSMap.

Throws: SQLException

An error occurred accessing the database.

Throws: XMLMiddlewareException

An error occurred building the map.

 public XMLDBMSMap createMap(String rootDatabaseNames[],
                             String rootCatalogNames[],
                             String rootSchemaNames[],
                             String rootTableNames[],
                             String stopDatabaseNames[],
                             String stopCatalogNames[],
                             String stopSchemaNames[],
                             String stopTableNames[]) throws SQLException, XMLMiddlewareException

Create a map from a set of root tables, stopping at designated "stop" tables.

The map factory will follow the graph from each root table until it hits one of the designated stop tables or until the graph ends. Note that stop tables are not included in the map.

The number of stop tables is almost always different from the number of root tables since stop tables are not directly related to root tables.

Parameters:

rootDatabaseNames - Names of the root databases. If any entries are null, the name "Default" is used.

rootCatalogNames - Names of the root catalogs. Entries may be null.

rootSchemaNames - Names of the root schemas. Entries may be null.

tableNames - Names of the root tables.

stopDatabaseNames - Names of the stop databases. If any entries are null, the name "Default" is used.

stopCatalogNames - Names of the stop catalogs. Entries may be null.

stopSchemaNames - Names of the stop schemas. Entries may be null.

stopTableNames - Names of the stop tables.

Returns:

The XMLDBMSMap.

Throws: SQLException

An error occurred accessing the database.

Throws: XMLMiddlewareException

An error occurred building the map.

 public XMLDBMSMap createMap(String rootDatabaseNames[],
                             String rootCatalogNames[]) throws SQLException, XMLMiddlewareException

Create a map for all tables in a catalog or catalogs.

The map factory will follow the graph from each table in each root catalog until it ends.

Parameters:

rootDatabaseNames - Names of the root databases. If any entries are null, the name "Default" is used.

rootCatalogNames - Names of the root catalogs.

Returns:

The XMLDBMSMap.

Throws: SQLException

An error occurred accessing the database.

Throws: XMLMiddlewareException

An error occurred building the map.

 public XMLDBMSMap createMap(String rootDatabaseNames[],
                             String rootCatalogNames[],
                             String rootSchemaNames[]) throws SQLException, XMLMiddlewareException

Create a map for all tables in a schema or schemas.

The map factory will follow the graph from each table in each root schema until it ends.

Parameters:

rootDatabaseNames - Names of the root databases. If any entries are null, the name "Default" is used.

rootCatalogNames - Names of the root catalogs. Entries may be null.

rootSchemaNames - Names of the root schemas.

Returns:

The XMLDBMSMap.

Throws: SQLException

An error occurred accessing the database.

Throws: XMLMiddlewareException

An error occurred building the map.

All Packages  Class Hierarchy  This Package  Previous  Next  Index