IJIS Institute Technical Advisory Committee

NIEM INDUSTRY FAQ SERIES

NIEM IEPD XML Code Generation in

May 2010
Java
This document seeks to address generation of Java classes based on
the JAXB standard. Initially it was meant to demonstrate the
similarities and differences between Axis and XFire. Since both
technologies use the JAXB-XJC tool as one of the ways to generate
Java classes for their code generation tools, this paper will address
the use of the JAXB-XJC tool.
 NIEM Industry FAQ Series

NIEM Industry FAQ Series

NIEM IEPD XML Code Generation in JAVA

What is JAXB? ................................................................................................................................................................................... 2

What is JAXB-XJC? ........................................................................................................................................................................... 2

Why use XJC instead of Axis2 wsdl2Java or CXF? ................................................................................................................... 2

How do I run XJC on a NIEM IEPD? ............................................................................................................................................... 2

Is there a way of generating a file for each namespace of an IEPD?................................................................................... 5

Why are some packages generated with a numeric postfix (Example: gov.niem.niem._core._2)? ................................. 5

Can generated code be used for multiple IEPDs? ...................................................................................................................... 5

Can I use the generated code in web services?.......................................................................................................................... 5

Should validation or other business logic be added to the generated classes? .................................................................. 5

What architectural patterns have been found successful in working with generated XML code? ................................... 6

Appendix ............................................................................................................................................................................................ 7

IJIS Institute Technical Advisory Committee Page 1

 NIEM Industry FAQ Series

NIEM Industry FAQ Series

NIEM IEPD XML Code Generation in JAVA

WHAT IS JAXB?
JAXB is the Java Architecture for XML Binding, which is an API used to make interacting with XML
documents from the Java programming language easier.

To learn more about JAXB, visit http://java.sun.com/developer/technicalArticles/WebServices/jaxb/.

Also, the Logical Entity eXchange Specification (LEXS) website has an example of using JAXB with
LEXS (NIEM), visit http://www.lexs.gov/

WHAT IS JAXB-XJC?
JAXB-XJC is JAXB‟s XML binding compiler. It provides tools for creating Java classes from an XSD
schema.

WHY USE XJC INSTEAD OF AXIS2 WSDL2JAVA OR CXF?

The Axis wsdl2Java tool will automatically generate Java Classes based on an XML Schema specified
from within a wsdl file, but is limited on the parameters that can be used when using XJC by itself. By
using the tool directly, you can have more control over the end result.

HOW DO I RUN XJC ON A NIEM IEPD?

There are many ways to execute the XJC tool on a NIEM IEPD. This paper will deal with three of them:

1. Executing XJC using the Java command;

2. Executing XJC using xjc.sh or xsh.bat; and
3. using an Eclipse plugin.

To obtain the JAXB library, navigate to https://jaxb.dev.java.net/ and download the most recent version.
Please note the EA on the version designates an „Early Access‟ version.

This package will be delivered to you as a Jar. Double-clicking the jar will unpack it in place, so ensure
that you‟ve put it somewhere that you keep your external libraries. For this example we are placing the
libraries into ~/dev/lib/JAXB.

For this example we‟ll be using the Arrest/Incident Report found here:
http://it.ojp.gov/default.aspx?area=implementationAssistance&page=1017&standard=413

IJIS Institute Technical Advisory Committee Page 2

 NIEM Industry FAQ Series

This is a fake IEPD but will demonstrate the features available to us using this tool.

Step 1
Create a project and add a folder entitled IEPD and place the folder containing the IEPD information
into it. The example workspace is located in ~/Documents/workspace, so the example setup looks like
this: ~/Documents/workspace/ClassGeneration/IEPD/Incident Report for JXDD 3.0.0.0.

Step 2
Next hit the terminal and navigate to your project. Create a new source folder called “generated.” This is
where we are going to direct the code to be generated.

Step 3
Next execute the Java -jar command like this:

java -jar ~/dev/lib/JAXB/jaxb-ri-20090708/lib/jaxb-xjc.jar -d generated IEPD/Incident\ Report\ for\

JXDD\ 3.0.0.0/

Here‟s a breakdown of the command:

~/dev/lib/JAXB/jaxb-ri-20090708/lib/jaxb-xjc.jar location of the xjc jar

-d generated the destination folder

IEPD/Incident\ Report\ for\ JXDD\ 3.0.0.0/ location of the IEPD

Step 4
Once the command is executed, the following will be displayed:

parsing a schema...

compiling a schema...

gov/ojp/it/jxdd/prerelease/unece_rec20_misc/_1_0_0/LengthType.java

gov/ojp/it/jxdd/prerelease/unece_rec20_misc/_1_0_0/ObjectFactory.java

gov/ojp/it/jxdd/prerelease/unece_rec20_misc/_1_0_0/TimeType.java

...

gov/ojp/it/jxdd/prerelease/ncic_2000_securities/_1_0_0/ObjectFactory.java

gov/ojp/it/jxdd/prerelease/ncic_2000_securities/_1_0_0/TYPSType.java

IJIS Institute Technical Advisory Committee Page 3

 NIEM Industry FAQ Series

Step 5
Once this has executed successfully return to Eclipse and hit refresh on your project. You will now have
the classes available to you in the generated source folder (shown below).

XJC Using xjc.sh or xjc.bat

The procedure is the same as detailed in the above steps, the .sh or bat file calls the java -jar command
for you. This may end up prettier as you can add the command to your path.

IJIS Institute Technical Advisory Committee Page 4

 NIEM Industry FAQ Series

Using an IDE Plugin

This procedure can be tedious. You can only generate one at a time.

IS THERE A WAY OF GENERATING A FILE FOR EACH NAMESPACE OF AN

IEPD?
Yes. Each of the new classes will be generated in a package according to its namespace. Within each
package, a package-info.java file will be created. This class has a package declaration along with the
annotation @javax.xml.bind.annotation.XmlSchema(namespace=”namespace in xsd”).

WHY ARE SOME PACKAGES GENERATED WITH A NUMERIC POSTFIX

(EXAMPLE: GOV.NIEM.NIEM._CORE._2)?
When the schema is generated it uses the namespaces designated within the .xsd to determine the
package structure for the generated classes.

CAN GENERATED CODE BE USED FOR MULTIPLE IEPDS?

No. Because each IEPD has a different subset of the NIEM model the generated classes shouldn‟t be
used across multiple IEPDs.

CAN I USE THE GENERATED CODE IN WEB SERVICES?

Yes. These can be used directly as web service method parameters.

SHOULD VALIDATION OR OTHER BUSINESS LOGIC BE ADDED TO THE

GENERATED CLASSES?
No. See the question: “Can generated code be used for multiple IEPDs?” Because generated code cannot
easily be shared between IEPDs, it is generally not advisable to add custom code to the generated classes
unless this can be supported by additional code generation tooling. As well, since new versions of IEPDs
may be developed, being able to quickly regenerate the XML serialization code may be necessary. We
recommend using the generated XML serialization code as a low-layer persistence mechanism rather
than a middle-layer domain model or active record.

IJIS Institute Technical Advisory Committee Page 5

 NIEM Industry FAQ Series

WHAT ARCHITECTURAL PATTERNS HAVE BEEN FOUND SUCCESSFUL IN

WORKING WITH GENERATED XML CODE?
The committee members found the Data Mapper (Patterns of Enterprise Application Architecture,
Fowler, 2002) especially valuable when working with generated XML serialization code. Each time one
works with a new IEPD, it can be developed into a persistence library with a data mapping layer
between it and a business layer. This decouples each IEPD XML serialization library from one another
and from the rest of the architecture.

Link: http://www.martinfowler.com/eaaCatalog/dataMapper.html

IJIS Institute Technical Advisory Committee Page 6

 NIEM Industry FAQ Series

APPENDIX
The following is a list of XJC Options/Arguments that was taken from
http://www.j2ee.me/webservices/docs/2.0/tutorial/doc/JAXBUsing2.html.
Option or Argument Description
Do not perform strict validation of the input schema(s). By default, xjc performs strict validation of the
-nv source schema before processing. Note that this does not mean the binding compiler will not perform any
validation; it simply means that it will perform less-strict validation.
By default, the XJC binding compiler strictly enforces the rules outlined in the Compatibility chapter of the
JAXB Specification. In the default (strict) mode, you are also limited to using only the binding customizations
-extension defined in the specification. By using the-extensionswitch, you will be allowed to use the JAXB Vendor
Extensions.
Specify one or more external binding files to process. (Each binding file must have its own -b switch.) The
-b file syntax of the external binding files is extremely flexible. You may have a single binding file that contains
customizations for multiple schemas or you can break the customizations into multiple bindings files. In
addition, the ordering of the schema files and binding files on the command line does not matter.
By default, xjc will generate Java content classes in the current directory. Use this option to specify an
-d dir
alternate output directory. The directory must already exist; xjc will not create it for you.
Specify an alternate output directory. By default, the XJC binding compiler will generate the Java content
-p package classes in the current directory. The output directory must already exist; the XJC binding compiler will not
create it for you.
Specify the HTTP/HTTPS proxy. The format
is [user[:password]@]proxyHost[:proxyPort]. The old -host and -port options
-proxyproxy
are still supported by the Reference Implementation for backwards compatibility, but they have been
deprecated.
- Specify where to find client application class files used by
classpatharg the <jxb:javaType> and <xjc:superClass> customizations.
Specify catalog files to resolve external entity references. Supports TR9401, XCatalog, and OASIS XML
-catalogfile Catalog format. For more information, please read the XML Entity and URI Resolvers document or examine
the catalog-resolver sample application.
Force the XJC binding compiler to mark the generated Java sources read-only. By default, the XJC binding
-readOnly compiler does not write-protect the Java source files it generates.
Supress the generation of package level annotations into **/package-info.java. Using this switch
-npa
causes the generated code to internalize those annotations into the other generated classes.
Treat input schemas as W3C XML Schema (default). If you do not specify this switch, your input schemas will
-xmlschema be treated as W3C XML Schema.
-quiet Suppress compiler output, such as progress information and warnings.
-help Display a brief summary of the compiler switches.
-version Display the compiler version information.
-Xlocator Enable source location support for generated code.
-Xsync-
Generate accessor methods with the synchronized keyword.
methods
-mark-
Mark the generated code with the -@javax.annotation.Generated annotation.
generated

IJIS Institute Technical Advisory Committee Page 7