Mortgage Unmarshalling

In this section we will explain how Mortgage XML unmarshalling solution is implemented.

The following steps are involved in a Castor unmarshalling procedure:

• Create directory structure,
• Create database objects,
• Create an XML Schema for an XML document,
• Run Castor Source Generator to generate Java classes or manually create Java classes for all XML document's elements and simple types,
• Create XML mapping document,
• Write a Java program that will unmarshal the XML document,
• Run the Java program that will unmarshal the XML document.

Step 1 - Create Directory Structure

For example, for this sample we created mortgage directory that also contains schema subdirectory where final versions of XML Schema documents are located. Java compiler and ant automatically create additional subdirectories, java, java/sample, java/mortgage,and lib.

The following XML documents, programs and scripts are located in mortgage directory:

• XML Documents
  • mortgage.xml
  • mortgage.xsd
  • mapping.xml
  • marshalmap.xml
  • database.xml
  • build.xml

• Programs
  • Mortgage_marshal.java
  • Mortgage_unmarshal.java

• Scripts
  • marshal.bat
  • unmarshal.bat

Later on when ant is executed using build.xml, java, java/sample, java/mortgage, and lib directories are created and their content is:

• java/sample:
  • mortgage.xml (copied from mortgage by ant)
  • mortgage.dtd (copied from mortgage by ant)
  • database.xml (copied from mortgage by ant)
  • mapping.xml (copied from mortgage by ant)
  • Mortgage_unmarshal.java (copied from mortgage by ant)
  • Mortgage_unmarshal.class (compiled by ant)
  • Mortgage_marshal.java (copied from mortgage by ant)
  • Mortgage_marshal.class (compiled by ant)
• java/mortgage:
  • All XML elements' Java classes
• lib:
  • mortgage.jar (XML elements' Java classes jar file)

database.xml document contains database configuration details. It is used by Castor JDO database component that supports database transactions in two types of environment, client applications and J2EE servers. Make sure that your version of database.xml document contains your database configuration details (host name, port number, database connect string, database user id and password). Our database.xml example belongs to an Oracle database.

There is also schema directory that contains a SQL script mortgage.sql and XML Schema document copied from the mortgage directory by ant:

• mortgage.sql
• mortgage.xsd

Step 2 - Create Database Objects

mortgage.sql script contains SQL statements for the mortgage database objects creation. Now, you are ready to run mortgage.sql script to create the database objects. For example, if you use Oracle enter the following command at your UNIX or MS-DOS command prompt:

sqlplus userid/password@db_connect_string @mortgage.sql

where userid and password are the ones you specified in database.xml. database_connect_string is a database connect string specified in Oracle's tnsnames.ora.

Step 3 - Create XML Schema

We start with XML Schema document creation based on the mortgage XML document and its Document Type Definition (DTD). The XML Schema formally defines XML document structure and its elements data types.

The mortgage XML Schema document ( mortgage.xsd) is created for a mortgage XML document sample ( mortgage.xml) and its DTD document ( mortgage.dtd). The XML Schema is used by the Castor Source Generator to create Java classes for XML mapping.

Step 4 - Generate Java Classes

Now when we have formal XML Schema definition for the mortgage XML document (mortgage.xsd), we execute Castor Source Generator with the XML Schema document as an input. Mortgage XML software build is performed by ant and we simply run ant at this point. Before you run ant ensure that castor.dir, jdk.dir, and regexp.dir in build.xml have full directory paths that belong to your software configuration and jar file name in classpath for mortgage_classes must be changed to your Castor version (castor-0.9.4.1.jar is the one we are using).

Also, the CLASSPATH in the Control Panel's System/Environment (Windows NT/2000/XP) should be updated with the following directories if you installed Castor software in c:\:

• c:\castor-0.9.4.1\castor-0.9.4.1.jar
• c:\castor-0.9.4.1\castor-0.9.4.1-xml.jar
• c:\castor-0.9.4.1\classes12.zip (Oracle classes)

Castor Source Generator generates all Java classes required for XML mapping. These classes are located in java/mortgage. They are used in programs for the mortgage XML unmarshalling and marshalling.

Step 5 - Create XML Mapping Document

mapping.xml is an XML document used for mortgage XML mapping from the mortgage Java classes to the mortgage database tables.

Add a copy command for mapping.xml to the "copy" target in build.xml:

<copy file="${mortgage.dir}/mapping.xml" todir="${src.dir}/sample" />

Run ant again and ensure that it completes successfully.

Step 6 - Unmarshal XML Document

Java program Mortgage_unmarshal.java unmarshals mortgage XML document. Mortgage table will be populated with data from the document.

build.xml has to be updated to include Mortgage_unmarshal.java compilation:

Add the following line to "copy" target:

<copy file="${mortgage.dir}/Mortgage_unmarshal.java" todir="${src.dir}/sample"/>

Create new target "sample-classes" that will compile Mortgage_unmarshal.java:

<target name="sample-classes" depends="mortgage-jar">
   <javac srcdir="${src.dir}/sample" destdir="${src.dir}/sample" includes="Mortgage_unmarshal.java"
   classpath="${lib.dir}/mortgage.jar;${castor.dir}/castor-0.9.4.1.jar;    ${castor.dir}/classes12.zip;${jdk.dir}/tools.jar" />
</target>

Change default in build.xml project to "sample-classes".

Ensure that the database name in the following Mortgage_unmarshal.java statement:

_jdo.setDatabaseName( "ebdb" );

is the one you use. If it is "ebdb" leave it, otherwise change it to your name.

Run ant to compile Mortgage_unmarshal.java

Step 7 - Run unmarshal program

Start unmarshal.bat script to execute mortgage XML unmarshal program. Before you start the script, change all directory paths to ones that belong to your system configuration.

 

Mortgage Marshalling

The following steps have to be performed in order to implement marshalling solution:

• Create masrhalmap.xml document for mortgage marshalling,
• Create Mortgage_marshal.java program.
• Modify build.xml to include marshalmap.xml and Mortgage_marshal.java compilation.
• Run the Mortgage_marshal.java program.

Step 1 - Create marshalmap.xml

Create masrhalmap.xml document that will enable marshalling from the mortgage table to mortgage.xml document.

Step 2 - Create Mortgage_marshal.java

Mortgage_marshal.java marshals mortgage data and creates output.xml document.

Step 3 - Modify build.xml

build.xml document must be modified by

• adding marshalmap.xml and Mortgage_marshal.java to the copy target
     <copy file="${mortgage.dir}/marshalmap.xml"
       todir="${src.dir}/sample" />
     <copy file="${mortgage.dir}/Mortgage_marshal.java"      todir="${src.dir}/sample" />
• adding Mortgage_marshal.java to includes in sample-classes target
     includes="Mortgage_unmarshal.java,Mortgage_marshal.java"

Step 4 - Run Mortgage_marshal.java program

Create marshal.bat and start the script to execute mortgage marshal program. After successful execution, an XML document output.xml will be created in mortgage directory.