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:

Property-processing properties are used to process other properties. This is File.
Parser properties provide information about the XML parser / DOM implementation. These are ParserUtilsClass and Validate.
Input and output properties specify what is to be done (create a map from a DTD, write a map file, etc.). These are Input, Output, MapFile, DTDFile, SQLFile, RootDatabaseName(n), RootCatalogName(n), RootSchemaName(n), RootTableName(n), StopDatabaseName(n), StopCatalogName(n), StopSchemaName(n), and StopTableName(n). See below for details.
Database properties are used to connect to the database(s). They are DBName, DataSourceClass, User, and Password. If there is more than one database, use sequentially numbered versions of these properties -- DBName1, DBName2, etc.

When the value of DataSourceClass is "JDBC1DataSource", the Driver and URL properties are used to configure the data source. When the value of DataSourceClass is "JDBC2DataSource", the JNDIContext and JNDILookupName properties are used to configure the data source. If the main database properties are numbered, these properties must also be numbered.

Note that the DBName property is optional. If DBName is omitted, "Default" is used. This is an error if there is more than one database.
Configuration properties specify how the classes are to function. They are OrderType, DatabaseName, CatalogName, SchemaName, Prefix(n), URI(n), MapColumnsAs, FollowPrimaryKeys, FollowForeignKeys, Encoding, SystemID, PublicID, Pretty, Indent, and SQLSeparator. See below for details.

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 value	Input properties	Database 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 value	Input properties	Database 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

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

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

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.

MapManager

 public MapManager(ParserUtils utils)

Construct a MapManager object.

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

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.

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.

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

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

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

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

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

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