ade-xjc is a command line tool and wrapper for the XML Schema binding compiler `xjc` shipped with [JAXB](https://jaxb.java.net/). ade-xjc compiles arbitrary CityGML Application Domain Extension (ADE) schemas to a set of corresponding JAXB classes to be used with [citygml4j](https://github.com/citygml4j/citygml4j).
ade-xjc is a command line tool and wrapper for the XML Schema binding compiler `xjc` shipped with
to a set of corresponding JAXB classes to be used with [citygml4j](https://github.com/citygml4j/citygml4j).
License
-------
ade-xjc is licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0). See the `LICENSE` file for more details.
ade-xjc is licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
See the `LICENSE` file for more details.
Note that releases of the software before version 2.3.0 continue to be licensed under GNU LGPL 3.0. To request a previous release of ade-xjc under Apache License 2.0 create a GitHub issue.
Note that releases of the software before version 2.3.0 continue to be licensed under GNU LGPL 3.0.
To request a previous release of ade-xjc under Apache License 2.0 create a GitHub issue.
Latest release
--------------
The latest stable release of ade-xjc is 2.9.0.
The latest stable release of ade-xjc is 2.10.0.
Download the ade-xjc 2.9.0 release binaries [here](https://github.com/citygml4j/ade-xjc/releases/download/v2.9.0/ade-xjc-2.9.0.zip). Previous releases are available from the [releases section](https://github.com/citygml4j/ade-xjc/releases).
Download the ade-xjc 2.10.0 release binaries [here](https://github.com/citygml4j/ade-xjc/releases/download/v2.10.0/ade-xjc-2.10.0.zip).
Previous releases are available from the [releases section](https://github.com/citygml4j/ade-xjc/releases).
Contributing
------------
...
...
@@ -23,12 +28,12 @@ Contributing
Building
--------
ade-xjc requires Java 8 or higher. The project uses [Gradle](https://gradle.org/) as build system. To build the program from source, run the following command from the root of the repository.
ade-xjc requires Java 8 or higher. The project uses [Gradle](https://gradle.org/) as build system.
To build the program from source, run the following command from the root of the repository.
> gradlew installDist
This will create a folder `build/install/ade-xjc` with the following subfolders:
*`bin` -- start scripts for running ade-xjc
*`jaxb-plugins` -- optional JAXB plugins that can be used in the schema compilation
*`lib` -- the ade-xjc JAR file and its mandatory dependencies
*`license` -- license information
...
...
@@ -37,7 +42,10 @@ This will create a folder `build/install/ade-xjc` with the following subfolders:
Compiling a CityGML ADE Schema
------------------------------
ade-xjc is a command line tool. In order to launch it, open a shell environment and navigate to the `bin` folder. This folder contains the two start scripts `ade-xjc.bat` and `ade-xjc` targeted at Microsoft Windows environments and UNIX-like environments (e.g. Linux, macOS). The command below exemplifies how to run ade-xjc to compile the ADE Schema `CityGMLADE.xsd` to JAXB classes.
ade-xjc is a command line tool. In order to launch it, open a shell environment and navigate to the root folder.
This folder contains the two start scripts `ade-xjc.bat` and `ade-xjc` targeted at Microsoft Windows environments
and UNIX-like environments (e.g. Linux, macOS). The command below exemplifies how to run ade-xjc to compile the
ADE Schema `CityGMLADE.xsd` to JAXB classes.
> ade-xjc /home/user/ade/CityGMLADE.xsd
...
...
@@ -53,44 +61,70 @@ To control the compilation process, ade-xjc offers the following program argumen
|`-version, -v` | Prints version information to the console
|`-help`, `-h` | Prints a help message to the console
Note that the ade-xjc binding compiler requires that your ADE schema points to the official CityGML and GML schemas provided in the subfolder `schemas`. So please adapt all `<xs:import>` statements in your ADE schema accordingly before launching ade-xjc.
Note that the ade-xjc binding compiler requires that your ADE schema points to the official CityGML and GML
schemas provided in the subfolder `schemas`. So please adapt all `<xs:import>` statements in your ADE schema
accordingly before launching ade-xjc.
Using JAXB plugins
------------------
Starting from version 2.4.3, ade-xjc allows you to use JAXB plugins in the ADE Schema compilation. Simply put the JAXB plugin you want to use into the `jaxb-plugins` subfolder and provide the plugin-specific command line arguments when executing ade-xjc. Please refer to the documentation of the JAXB plugin to learn which command line arguments are available and how to use them.
Starting from version 2.4.3, ade-xjc allows you to use JAXB plugins in the ADE Schema compilation.
Simply put the JAXB plugin you want to use into the `jaxb-plugins` subfolder and provide the plugin-specific
command line arguments when executing ade-xjc. Please refer to the documentation of the JAXB plugin to learn
which command line arguments are available and how to use them.
The following JAXB plugins are already included and shipped with ade-xjc:
For example, if you want to augment your generated JAXB classes with setters for collections then you can use the `Setters Plugin` of the JAXB2 Basics Plugins project. This plugin is activated by the `-Xsetters` command line option and is documented [here](https://github.com/highsource/jaxb2-basics/wiki/JAXB2-Setters-Plugin). The following example shows how use this plugin with ade-xjc.
For example, if you want to augment your generated JAXB classes with setters for collections then you can
use the `Setters Plugin` of the JAXB2 Basics Plugins project. This plugin is activated by the `-Xsetters` command
line option and is documented [here](https://github.com/highsource/jaxb2-basics/wiki/JAXB2-Setters-Plugin).
The following example shows how use this plugin with ade-xjc.
ade-xjc provides the sample CityGML ADE Schema `CityGML-SubsurfaceADE-0_9_0.xsd` to illustrate the schema binding process. Once you have built the library from source with [Gradle](https://gradle.org/) as described above, find the example in the `build/install/ade-xjc/sample` folder.
ade-xjc provides the sample CityGML ADE Schema `CityGML-SubsurfaceADE-0_9_0.xsd` to illustrate the schema
binding process. Once you have built the library from source with [Gradle](https://gradle.org/) as described above,
find the example in the `build/install/ade-xjc/sample` folder.
From within the `sample` folder, launch ade-xjc with the following command.
This will compile the `CityGML-SubsurfaceADE-0_9_0.xsd` schema to JAXB classes that are generated in the folder `sample/src-gen`. For convience, two `run-sample` start scripts are provided in the `sample` folder to run ade-xjc with the above settings under Windows or UNIX-like environments.
This will compile the `CityGML-SubsurfaceADE-0_9_0.xsd` schema to JAXB classes that are generated in the folder
`sample/src-gen`. For convenience, two `run-sample` start scripts are provided in the `sample` folder to run ade-xjc
with the above settings under Windows or UNIX-like environments.
Using the generated JAXB classes
--------------------------------
ade-xjc is designed to be used with citygml4j. During compilation of the ADE Schema, ade-xjc ensures that the resulting JAXB classes perfectly combine with the JAXB classes that are shipped with citygml4j and that map the official CityGML, GML and xAL schemas. As a consequence, the citygml4j library needs to be on your classpath in order to use the generated JAXB classes.
The intended scenario is to use citygml4j to parse or write a CityGML instance document with ADE content. citygml4j provides the class `ADEGenericElement` that will give you access to the ADE content through an `org.w3c.dom.Element` DOM object. You can either manually parse or create this DOM element or, more conveniently, use the JAXB classes generated with ade-xjc for this purpose. citygml4j comes with a sample program that illustrates this scenario. The sample program is available in the subfolder `citygml4j-<version>/samples/handling_ade/generic/unmarshalling_ade_using_jaxb` where you built the citygml4j library.
Since [citygml4j 2.5.0](https://github.com/citygml4j/citygml4j/releases/tag/v2.5.0), an alternative approach for processing ADE content using citygml4j is available. It allows for extending the citygml4j object model with user-defined ADE classes that seamlessly integrate with the predefined citygml4j object model. JAXB is used for parsing and writing the ADE classes to ADE-enriched CityGML datasets. The required JAXB classes can be easily generated from the ADE XML Schema using ade-xjc. Sample programs illustrating this ADE module approach are available in the subfolder `citygml4j-<version>/samples/handling_ade/ade_context` of the citygml4j library.
Note that you need to check which version of citygml4j is supposed by your version of ade-xjc. Use the following command to find out.
ade-xjc is designed to be used with citygml4j. During compilation of the ADE Schema, ade-xjc ensures that the
resulting JAXB classes perfectly combine with the JAXB classes that are shipped with citygml4j and that map the
official CityGML, GML and xAL schemas. As a consequence, the citygml4j library needs to be on your classpath in
order to use the generated JAXB classes.
The intended scenario is to use citygml4j to parse or write a CityGML instance document with ADE content.
citygml4j provides the class `ADEGenericElement` that will give you access to the ADE content through an
`org.w3c.dom.Element` DOM object. You can either manually parse or create this DOM element or, more conveniently,
use the JAXB classes generated with ade-xjc for this purpose. citygml4j comes with a sample program that illustrates
this scenario. The sample program is available in the subfolder `citygml4j-<version>/samples/handling_ade/generic/unmarshalling_ade_using_jaxb`
where you built the citygml4j library.
Since [citygml4j 2.5.0](https://github.com/citygml4j/citygml4j/releases/tag/v2.5.0), an alternative approach for
processing ADE content using citygml4j is available. It allows for extending the citygml4j object model with
user-defined ADE classes that seamlessly integrate with the predefined citygml4j object model. JAXB is used for
parsing and writing the ADE classes to ADE-enriched CityGML datasets. The required JAXB classes can be easily
generated from the ADE XML Schema using ade-xjc. Sample programs illustrating this ADE module approach are available
in the subfolder `citygml4j-<version>/samples/handling_ade/ade_context` of the citygml4j library.
Note that you need to check which version of citygml4j is supposed by your version of ade-xjc.
Use the following command to find out.
> ade-xjc -version
The output will look similar to this:
ade-xjc version 2.9.0
XML Schema binding compiler for CityGML ADEs; use with citygml4j version 2.9.0
ade-xjc version 2.10.0
XML Schema binding compiler for CityGML ADEs; use with citygml4j version 2.10.0
