3. Running the Connect XML-2-DB tool

• Command line for standalone tool
• Integrating the Connect XML-2-DB library with other java applications

Connect XML-2-DB is a tool that can be run as a stand-alone program or it can be integrated into another Java application. Before you can run Connect XML-2-DB in either mode the following files have to be created:

• Mapping file
  The mapping file provides information about the database tables and columns into which the XML element and attribute data is to be inserted. Details about the format of the mapping file along with examples are provided in a later section.
• Database configuration file
  The database configuration file provides the database connection information for the database that you want to insert data into. Details about the format of the database configuration file are provided in a later section.

1. Command line for standalone tool

First ensure that the archives 'xml2db.jar' and 'xerces.jar' are listed in your 'CLASSPATH' environment variable. The command for running Connect XML-2-DB has the form:

java ExecXMLToDb [OPTIONS] DatabaseConfigFile MappingFile XMLFile input-parameters

where:

where [OPTIONS] include:

For examples, refer to the section Examples of running Connect XML-2-DB as a standalone program.

To just display the version number of this software, just provide the -v option as follows:

java ExecXMLToDb -v

There is also a .bat script, runXmlToDb.bat, in the root directory of the xml2db_ver_1_0. This script must be modified so that the variable, XML2DB_ROOT, points to the correct location that xml2db_ver_1_0 has been installed in. The variable, JDKROOT, must also point to the correct location that the JDK has been installed. If the directory that has runXmlToDb.bat is in your PATH environment variable, then you can also run Connect XML-2-DB as follows:

runXmlToDb [OPTIONS] DatabaseConfigFile MappingFile XMLFile input-parameters

2. Integrating the Connect XML-2-DB library with other java applications

Connect XML-2-DB is designed to be integrated with other Java applications. Include the jar libraries xml2db.jar and xerces.jar in your CLASSPATH variable. Refer to the section, Installing Connect XML-2-DB, for more information on setting the CLASSPATH.

The execMap() method of the class com.skyhawksystems.mappingtool.top.XmlToDB executes the same transformations done by the command line tool. For example, you could use the following code in your java application to transfer the data in the XML file, schools.xml, into database tables using the mapping file schools_map.xml and the database configuration file sqlserver_db_config.txt.

          // The information in database connection properties file will be used to
          // establish a new connection to the database.
          XMLToDb runMap1 = new XMLToDb(
                  "sqlserver_db_config.txt",   // database connection properties file
                  "schools_map.xml",           // map file name
                  "schools.xml");              // xml data file 
          try {
            runMap1.execMap();                 // run the tranformation
          } catch (Exception e) {
              System.err.println("Error: " + e.getMessage());
          } finally {
              runMap1.printNumElemsInserted(); // print summary information
          }

If a connection to the database has already been establised (using the provided INET JDBC driver) by your application and you want the Connect XML-2-DB library to use that connection, then the following code can be used:

          // A connection to the database has already been establised by your application.
          // conn is the java.sql.Connection object that represents this connection.
          // The XMlToDb library should use this connection to perform the data inserts.
          XMLToDb runMap1 = new XMLToDb(
                  conn,                        // database connection object of the type
                                               // java.sql.Connection. 
                  "schools_map.xml",           // map file name
                  "schools.xml");              // xml data file 
          try {
            runMap1.execMap();                 // run the tranformation
          } catch (Exception e) {
              System.err.println("Error: " + e.getMessage());
          } finally {
              runMap1.printNumElemsInserted(); // print summary information
          }
          // Close the connection to the database. Connect XML-2-DB does not close the connection,
          // if it did not create the connection.

To establish a connection to an ORACLE database using the provided INET JDBC driver, use the following code:

          String userName = "USERNAME"; // Replace this with the user name to be used for your database
          String password = "PASSWORD"; // Replace with the password for this user name
      
          // Replace HOSTNAME and SID with the hostname and SID of your ORACLE database.
          // The port number, 1521, should be replaced, if using another port.
          String url = "jdbc:inetora:HOSTNAME:1521:SID";  
      
          Connection conn = null;
          try {
            DriverManager.registerDriver(new com.inet.ora.OraDriver());
            conn = DriverManager.getConnection(url, userName, password);
          } catch (SQLException excp) {
            excp.printStackTrace();
            System.exit(1);
          }

To establish a connection to a SQL Server database replace the driver and the URL used above with the following:

          // Replace the HOSTNAME with the name of your host that has the database and replace DBNAME with
          // the name of the database that you want to connect to. Also, the port number should be replaced,
          // if it is different from 1433.

          String url = "jdbc:inetdae7:HOSTNAME:1433?database=DBNAME";
		  
          DriverManager.registerDriver(new com.inet.tds.TdsDriver());          

If some input parameters are mapped to database columns, then use the following code to pass in these parameters to the Connect XML-2-DB library.

          // Parameters that have to be mapped to columns defined in map-param-const
          // rules.
          String[] paramArray =  new String[2];
		  paramArray[0] = "Dec 12, 2001";
		  paramArray[1] = "San Jose";					  

          // The information in database connection properties file will be used to
          // establish a new connection to the database.
          XMLToDb runMap1 = new XMLToDb(
                  "sqlserver_db_config.txt",   // database connection properties file
                  "schools_map.xml",           // map file name
                  "schools.xml");              // xml data file 

          runMap1.setParams(paramArray);
          try {
            runMap1.execMap();                 // run the tranformation
          } catch (Exception e) {
              System.err.println("Error: " + e.getMessage());
          } finally {
              runMap1.printNumElemsInserted(); // print summary information
          }

For complete examples, refer to the section Examples of using the Connect XML-2-DB library.

The javadoc documentation on the Connect XML-2-DB classes is located in the class_docs directory.