Update README.md

README.md

@@ -15,7 +15,7 @@ Contributing
 
 Building
 --------
-ade-xjc depends on JRE 7 or higher. The project uses [Apache Ant](http://ant.apache.org/) as the build tool. To build the program, run the `build.xml` file from the root of the repository with `dist` as target. 
+ade-xjc depends on JRE 7 or higher. The project uses [Apache Ant](http://ant.apache.org/) as build tool. To build the program, run the `build.xml` file from the root of the repository with `dist` as target. 
 
     % ant dist
 
@@ -44,5 +44,24 @@ To control the compilation process, ade-xjc offers the following program argumen
 
 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 the compiled JAXB classes
--------------------------------
+Sample ADE Schema compilation
+-----------------------------
+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 [Apache Ant](http://ant.apache.org/) as described above, find the example in the `ade-xjc-<version>/sample` folder.
+
+From within the `ade-xjc-<version>` folder, launch ade-xjc with the following command.
+
+    % java -jar ade-xjc.jar -clean -binding sample/binding.xjb -output sample src-gen -package ade.sub.jaxb sample/CityGML-SubsurfaceADE-0_9_0.xsd
+
+This will compile the `CityGML-SubsurfaceADE-0_9_0.xsd` schema to JAXB classes that are generated in the folder `sample/src-gen`. If you are running ade-xjc with Java 8, you will have to allow access to external XSD files by adding the following JVM argument to the above command.
+
+    -Djavax.xml.accessExternalSchema
+
+For your convience, an Ant `build.xml` file is available in the `ade-xjc-<version>/sample` folder. Run this `build.xml` file with Ant using the default target to compile the schema with the settings shown above. 
+
+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 harmonize 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 `ADEComponent` 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 `samples/handling_ade/unmarshalling_ade_using_jaxb` where you built the citygml4j library.