All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class org.xmlmiddleware.xmldbms.tools.MapManager

java.lang.Object
   |
   +----org.xmlmiddleware.xmldbms.tools.PropertyProcessor
           |
           +----org.xmlmiddleware.xmldbms.tools.MapManager

public class MapManager
extends PropertyProcessor
Simplified interface to the map factories and utilities.

Introduction

MapManager provides three interfaces for using map factories and utilities: a command line interface, a dispatch-style API, and a high-level, traditional API. The command line interface consists of a single method (main). The dispatch-style API also consists of a single method (dispatch). All other methods (writeMap, createDTD, etc.) belong to the traditional API.

The command line interface and dispatch-style API take a set of property-value pairs that describe the action to be taken. The most important of these properties are Input (how to create a map) and either Output or Output1, Output2, ... (what to create from the map).

The traditional API either creates an XMLDBMSMap object from the specified input (map file, DTD, database) or creates something from an XMLDBMSMap object (map file, DTD, set of CREATE TABLE statements).

Properties

All of MapManager's interfaces use properties. The dispatch-style API and command-line interface are entirely properties based, while the traditional API uses properties for database information (data source class, URL, etc.) and configuration information (output encoding, whether to map columns as element types or attributes, etc.).

Properties fall into the following categories:

When using the command line or the dispatch-style API, the Input and Output properties specify the actions to take. Legal values for the Input property are Map, DTD, and Database. Legal values for the Output property are Map, DTD, and SQL. (When using the traditional API, the Input and Output properties are not needed since this information is inherent in the method called.)

The following table shows which properties are used with each value of the Input property. Required properties are marked with an asterisk (*). Properties that may have more than one value are labeled (n). For example, DBName(n) means that there may be a DBName property or DBName1, DBName2, DBName3, ... properties.

Input valueInput propertiesDatabase properties Configuration properties
Map MapFile* Not used. Validate [1]
DTD DTDFile* Single set of values. Optional. [2] DatabaseName [3]
CatalogName [3]
SchemaName [3]
Prefix(n) [4]
URI(n) [4]
Database [5] RootDatabase(n)
RootCatalog(n)
RootSchema(n)
RootTable(n)*
StopDatabase(n)
StopCatalog(n)
StopSchema(n)
StopTable(n)
Set of values for each database that is read. Required. MapColumnsAs [6]
FollowPrimaryKeys [1]
FollowForeignKeys [1]
Prefix [7]
URI [7]

NOTES:
[1] Legal values are Yes (default) and No.
[2] Used to check that generated names are legal and do not conflict with existing names.
[3] Database structure to which element types and attributes are mapped.
[4] Maps namespace prefixes in DTD to namespace URIs.
[5] See MapFactory_Database for an explanation of properties.
[6] Legal values are ElementTypes (default) and Attributes.
[7] Namespace prefix and URI of generated element type names.

The following table shows which properties are used with each value of the Output property. Required properties are marked with an asterisk (*). Properties that may have more than one value are labeled (n). For example, DBName(n) means that there may be a DBName property or DBName1, DBName2, DBName3, ... properties.

Output valueInput propertiesDatabase properties Configuration properties
Map MapFile* Not used Encoding
URI(n) [1]
Prefix(n) [1]
SystemID
PublicID
Pretty [2]
Indent [3]
DTD DTDFile* Not used Encoding
Pretty [2]
SQL SQLFile* Set of values for each database used by the map. Optional. [4] Encoding
SQLSeparator [5]

NOTES:
[1] Overrides the namespace prefixes currently in the map (if any). Rarely used.
[2] Whether to pretty-print. Legal values are Yes (default) and No.
[3] Number of spaces to indent when pretty-printing. Default is 3.
[4] Used to retrieve database-specific type names.
[5] Character(s) used to separate the CREATE TABLE statements. Default is semi-colon (;) plus the line separator system property.

For a complete description of the properties used by Transfer, see ?????.

Command Line Syntax

The syntax of the command-line interface is:

   java MapManager = [=...]
 

Property/value pairs are read in order and, if a property occurs more than once, the last value is used. If a property/value pair contains spaces, the entire pair must be enclosed in quotes.

For example, the following is used to store data from the sales.xml file to the database:

   java org.xmlmiddleware.xmldbms.tools.MapManager
              DataSourceClass=JDBC1DataSource
              Driver=sun.jdbc.odbc.JdbcOdbcDriver URL=jdbc:odbc:xmldbms
              User=ron Password=ronpwd
              Input=DTD DTDFile=sales.dtd
              Output1=Map MapFile=sales.map
              Output2=SQL SQLFile=sales.sql
 

A special property, File, can be used to designate a file containing other properties. For example, if the database properties are stored in db.props, the following is equivalent to the previous command line:

   java org.xmlmiddleware.xmldbms.tools.MapManager File=db.props
              Input=DTD DTDFile=sales.dtd
              Output1=Map MapFile=sales.map
              Output2=SQL SQLFile=sales.sql
 

If more than one File property is used, the File properties must be numbered sequentially. File properties can also be used inside property files, making it possible to have a hierarchy of property files. File properties can be used from the command line and with the dispatch-style interface. They cannot be used with the traditional API.

Dispatch-style Interface

The dispatch-style interface is called that because methods are not called directly. Instead, the name of the method and its arguments are passed as properties and MapManager "dispatches" the call to the actual method based on these properties.

The dispatch-style interface consists of a single method, dispatch(). In general, applications that want to call MapManager programmatically should probably use the traditional API instead.

Traditional API

The traditional API consists of a number of methods: compileMap, createMapFromDTD, createMapFromDatabase, writeMap, createDTD, and createSQL. Some of these methods accept database properties; all of them accept configuration properties. The database and configuration properties are described above.

Version:
2.0
Author:
Ronald Bourret, Adam Flinton
See Also:
XMLDBMSProps

Constructor Index

 o MapManager(ParserUtils)
Construct a MapManager object.
 o MapManager(Properties)
Construct a MapManager object.

Method Index

 o compileMap(Properties, String)
Compiles a map file.
 o createDTD(Properties, XMLDBMSMap, String)
Creates a DTD from a map and writes it to a file.
 o createMapFromDatabase(Properties, Properties, String[], String[], String[], String[], String[], String[], String[], String[])
Creates a map from a database.
 o createMapFromDTD(Properties, Properties, String)
Creates a map from a DTD.
 o createSQL(Properties, Properties, XMLDBMSMap, String)
Creates CREATE TABLE statements from a map and writes them to a file.
 o dispatch(Properties)
Creates a map according the Input property and generates output according to one or more Output properties.
 o main(String[])
Run MapManager from a command line.
 o writeMap(Properties, XMLDBMSMap, String)
Writes a map to a file.

Constructors

 o MapManager
 public MapManager(Properties props) throws XMLMiddlewareException
Construct a MapManager object.

Parameters:
props - A Properties object containing the ParserUtilsClass property.
Throws: XMLMiddlewareException
An error occurs instantiating the ParserUtils class.
 o MapManager
 public MapManager(ParserUtils utils)
Construct a MapManager object.

Parameters:
utils - An object that implements the ParserUtils interface.

Methods

 o main
 public static void main(String args[])
Run MapManager from a command line.

See the introduction for the command line syntax.

Parameters:
args - An array of property/value pairs.
 o dispatch
 public void dispatch(Properties props) throws XMLMiddlewareException, SQLException
Creates a map according the Input property and generates output according to one or more Output properties.

For a list of valid inputs and outputs and the properties that each input or output type needs, see the introduction.

Parameters:
props - A Properties object describing the input and output(s)
Throws: SQLException
Thrown if a database error occurs.
Throws: XMLMiddlewareException
Thrown for all other errors: file not found, invalid map document, class not found, etc.
 o compileMap
 public XMLDBMSMap compileMap(Properties configProps,
                              String mapFilename) throws XMLMiddlewareException
Compiles a map file.

Parameters:
configProps - See the introduction. May be null.
mapFilename - Name of the map file.
Throws: XMLMiddlewareException
Thrown for all errors
 o createMapFromDTD
 public XMLDBMSMap createMapFromDTD(Properties dbProps,
                                    Properties configProps,
                                    String dtdFilename) throws XMLMiddlewareException, SQLException
Creates a map from a DTD.

Parameters:
dbProps - A Properties object describing the database to which to map the DTD. May be null.
configProps - See the introduction. May be null.
dtdFilename - Name of the DTD file.
Throws: SQLException
Thrown if a database error occurs.
Throws: XMLMiddlewareException
Thrown for all other errors
 o createMapFromDatabase
 public XMLDBMSMap createMapFromDatabase(Properties dbProps,
                                         Properties configProps,
                                         String rootDatabaseNames[],
                                         String rootCatalogNames[],
                                         String rootSchemaNames[],
                                         String rootTableNames[],
                                         String stopDatabaseNames[],
                                         String stopCatalogNames[],
                                         String stopSchemaNames[],
                                         String stopTableNames[]) throws XMLMiddlewareException, SQLException
Creates a map from a database.

Parameters:
dbProps - A Properties object describing the database to which to map the DTD. Required.
configProps - See the introduction. May be null.
rootDatabaseNames - See MapFactory_Database. May be null.
rootCatalogNames - See MapFactory_Database. May be null.
rootSchemaNames - See MapFactory_Database. May be null.
rootTableNames - See MapFactory_Database. Required.
stopDatabaseNames - See MapFactory_Database. May be null.
stopCatalogNames - See MapFactory_Database. May be null.
stopSchemaNames - See MapFactory_Database. May be null.
stopTableNames - See MapFactory_Database. May be null.
Throws: SQLException
Thrown if a database error occurs.
Throws: XMLMiddlewareException
Thrown for all other errors
 o writeMap
 public void writeMap(Properties configProps,
                      XMLDBMSMap map,
                      String mapFilename) throws XMLMiddlewareException
Writes a map to a file.

Parameters:
configProps - See the introduction. May be null.
map - The map
mapFilename - The name of the file to write the map to.
Throws: XMLMiddlewareException
Thrown for all other errors
 o createDTD
 public void createDTD(Properties configProps,
                       XMLDBMSMap map,
                       String dtdFilename) throws XMLMiddlewareException
Creates a DTD from a map and writes it to a file.

Parameters:
configProps - See the introduction. May be null.
map - The map
dtdFilename - The name of the file to write the DTD to.
Throws: XMLMiddlewareException
Thrown for all other errors
 o createSQL
 public void createSQL(Properties dbProps,
                       Properties configProps,
                       XMLDBMSMap map,
                       String sqlFilename) throws XMLMiddlewareException, SQLException
Creates CREATE TABLE statements from a map and writes them to a file.

Parameters:
dbProps - Properties for database to get type names, etc. from. May be null.
configProps - See the introduction. May be null.
map - The map
sqlFilename - The name of the file to write the CREATE TABLE statements to.
Throws: SQLException
Thrown if a database error occurs.
Throws: XMLMiddlewareException
Thrown for all other errors

All Packages  Class Hierarchy  This Package  Previous  Next  Index