ASN Unmarshalling

In this section we will explain how Advance Shipping Notice (ASN) 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 asn directory with marshal and unmarshal subdirectories. unmarshal directory 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/asn,and lib.

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

• XML Documents
  • asn.xml
  • asn.xsd
  • mapping.xml
  • database.xml
  • build.xml

• Programs
  • Asn.java

• Scripts
  • asn.bat

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

• java/sample:
  • asn.xml (copied from asn by ant)
  • asn.dtd (copied from asn by ant)
  • database.xml (copied from asn by ant)
  • mapping.xml (copied from asn by ant)
  • Asn.java (copied from asn by ant)
  • Asn.class (compiled by ant)
• java/asn:
  • All XML elements' Java classes
• lib:
  • asn.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 asn.sql and XML Schema document copied from the unmarshal directory by ant:

• asn.sql
• asn.xsd

Step 2 - Create Database Objects

sqlplus userid/password@db_connect_string @asn.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 ASN XML document and its Document Type Definition (DTD). The XML Schema formally defines XML document structure and its elements data types.

The ASN XML Schema document ( asn.xsd) is created for an ASN XML document sample ( asn.xml) and its DTD document ( asn.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 ASN XML document (asn.xsd), we execute Castor Source Generator with the XML Schema document as an input. ASN 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 asn_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/asn. They are used in programs for ASN XML unmarshalling and marshalling.

Step 5 - Create XML Mapping Document

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

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

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

Run ant again and ensure that it completes successfully.

Step 6 - Unmarshal XML Document

Java program Asn.java unmarshals ASN XML document. The following tables will be populated with data from the document:

• AdvanceShippingNotice
• FromLocation
• ToLocation
• Container
• Product

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

Add the following line to "copy" target:

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

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

<target name="sample-classes" depends="asn-jar">
   <javac srcdir="${src.dir}/sample" destdir="${src.dir}/sample" includes="Asn.java"
   classpath="${lib.dir}/asn.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 Asn.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 Asn.java

Step 7 - Run unmarshal program

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

ASN Marshalling

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

• Copy all required files from unmarshal directory,
• Modify build.xml removing Source Generator target,
• Modify mapping.xml and create marshalmap.xml document in marshal directory,
• Modify Java classes that belong to ArrayList data type,
• Create Asn.java program that will marshal all ASN database tables into an ASN XML document.
• Run the Asn.java program.

Step 1 - Copy Unmarshal Directory

Marshalling currently requires several additional steps because the current version of Castor (0.9.4.1) does not has full support for Java ArrayList data type. marshal directory should be created and complete unmarshal directory should be copied to it. After that, the content of the marshal directory should be the same as the list below. All unnecessary files should be removed.

After we copy files from the unmarshal directory and remove unnecessary files, the marshal directory will contain the following XML documents, programs, and scripts:

• XML Documents
  • asn.dtd
  • asn.xml
  • mapping.xml
  • database.xml
  • build.xml

marshal directory will also contain java/sample, java/asn, that are copied from the unmarshal directory. Marshaling does not need schema directory.

Step 2 - Modify build.xml

build.xml document must be modified by

• removing asn.xsd from the copy target,
• adding marshalmap.xml to the copy target,
• removing asn-schema target,
• changing depends for the asn-classes target to prepare,copy

Step 3 - Modify mapping.xml and create marshalmap.xml

ArrayList collections are added for AdvanceShippingNotice, Container, and Product in mapping.xml and an additional marshal mapping document marshalmap.xml is created.

Step 4 - Modify Java classes that belong to ArrayList data type

All Java classes that contain ArrayList data type:

• AdvanceShippingNotice.java, AdvaneShippingNoticeDescriptor.java
• Container.java, ContainerDescriptor.java

must be modified and the following code changes have to be done:

• AdvanceShippingNotice.java changes
• AdvanceShippingNoticeDescriptor.java changes
• Container.java changes
• ContainerDescriptor.java changes

Step 5 - Create Asn.java program

Asn.java program will marshal all data from the database and create output.xml document that will have the same content as asn.xml. Save Asn.java in java/sample.

Step 6 - Run Asn.java program

Execute ant to build marshalling example:

Create asn.bat and start the script to execute ASN XML marshal program:

After successful execution, an XML document output.xml will be created in marshal directory.