Adding your own Application Domain Extensions (ADE) to citygml4j¶

• Adding your own Application Domain Extensions (ADE) to citygml4j
  • citygml4j's support for ADEs
  • How to integrate CityGML ADEs into citygml4j
  • Business code examples based on your ADE implementation

citygml4j 0.1.0

citygml4j 0.2.0-1

citygml4j 1.0ea

CityGML's concept of Application Domain Extensions (ADE) offers a well-defined extension mechanism to augment the CityGML data model with application specific data. These application specific extensions are formally specified in their own ADE XML schema file and can comprise additional property elements for existing CityGML objects as well as newly defined feature types. ADEs are associated with their own XML namespace which allows for integrating ADE data into CityGML instance documents.

Unfortunately, by default, citygml4j does not understand the different XML vocabularies defined by different ADEs. The reason for this is the XML data binding approach of citygml4j which requires a set of predefined Java content classes in order to represent the content and organization of XML instance documents. This rather static way of XML handling does not support dealing with previously unknown XML data in a generic way. Accordingly, citygml4j by default ignores any XML data that is not associated with the official CityGML, GML, and xAL namespaces - and thus skips all user-defined ADE content.

However, there is of course also good news: citygml4j has been designed to support CityGML ADEs and thus can be taught additional ADE vocabularies. For this purpose, the ADE XML schema definition has to be mapped to corresponding citygml4j-compliant content classes. By registering these ADE content classes with the citygml4j library, ADE-enriched CityGML instance documents can be easily un/marshalled and processed through citygml4j. The content classes can be seamlessly integrated with existing citygml4j business code which allows for adding ADE support to your citygml4j application. citygml4j can be augmented by multiple ADEs at a time. Once implemented, the ADE content classes can be packaged as a .jar library file and shared amongst citygml4j developers.

This tutorial illustrates step by step how to incorporate CityGML Application Domain Extensions (ADE) into your citygml4j application. Please note, that a general discussion of ADEs is beyond the scope of this tutorial. If you want to learn more about ADEs, please refer to the CityGML specification documents which can be obtained from the Documents section of this site.

Please note, that whilst writing this tutorial the citygml4j library moved from version 0.1.0 to version 0.2.0. Accordingly, the examples in this tutorial are tailored to citygml4j version 0.2.0 only. In version 0.2.0, the ADE API has been slightly changed which mainly affects interface definitions. However, the ADE support is already fully functional in version 0.1.0 and the examples of this tutorial can be easily backported.

citygml4j's support for ADEs¶

Although an ADE XML schema could possibly define various extensions to the CityGML data model, the CityGML specification requires all application specific extensions to belong to one of the following two categories:

• Subclassing of CityGML feature types
  ADEs may define new feature types associated with the ADE namespace which must be derived from existing CityGML feature types. For example, new feature types could extend abstract CityGML classes like _CityObject or _AbstractBuilding or the concrete class CityFurniture. The new feature types automatically inherit all properties (i.e. attributes) and associations (i.e. relations) from the respective CityGML superclass.
• Augmenting CityGML features by additional property elements
  Existing CityGML feature types may be augmented by application specific properties in the ADE namespace. These properties may have simple or complex data types. Both GML geometries and embedded features (feature properties) are also possible. For this purpose, each CityGML feature type provides a hook in its XML schema definition which allows for attaching additional properties to it. This hook is implemented as an abstract property element of the name _GenericApplicationPropertyOf<FeatureTypeName> where <FeatureTypeName> is equal to the name of the feature type definition in which it is included. The datatype of these hooks is always xsd:anyType from the XSD namespace. New property elements specified by an ADE must be explicitly assigned to the substitution group defined by the corresponding _GenericApplicationPropertyOf<FeatureTypeName> element.

citygml4j fully supports these two extension types. First, citygml4j developers may extend exisiting content classes in order to derive new subclasses of CityGML feature types. Second, each citygml4j content class representing a CityGML feature type provides getter, setter, isSetter, and unsetter methods to retrieve, add, and delete ADE-specific properties through its ADE hook. For example, the Building class provides the parameterless method getGenericApplicationPropertyOfBuilding which returns all application specific properties attached to the Building instance. The naming of these methods follows the naming of the ADE hooks in the CityGML XML schema definition.

In addition, citygml4j supports subclassing of the abstract GML class gml:_Feature. By this means, citygml4j developers can introduce new feature types which are not restricted to be descendants of CityGML superclasses. Although this subclassing is not explicitly specified for CityGML ADEs, it follows the general principles for the definition of GML application schemas.

The following is not supported by citygml4j:

• As for the current version of citygml4j, subclassing of any other GML types, i.e. in particular geometry classes, is not supported. Strictly speaking, subclassing of GML geometry classes is not covered by CityGML's ADE concept either. However, it is of course allowed for all GML application schemas. Support may be added in future citygml4j versions.

How to integrate CityGML ADEs into citygml4j¶

The integration of CityGML ADEs into your citygml4j application requires four major steps to be taken. As for the current version of citygml4j, these steps mainly result from the tight coupling between citygml4j and JAXB (read more about this coupling in the tutorial on citygml4j and JAXB). Each step is discussed in detail on a separate page of this tutorial. If you read about ADEs and citygml4j for the first time, you should go through the pages step by step.

The single steps are illustrated using the example of the CityGML Noise ADE (see attached file CityGML-NoiseADE.xsd for its XML schema definition). The Noise ADE is one of the first publicly available ADEs for CityGML and deals with the application of virtual 3D city models to generate noise pollution maps. Feel free to read more about the Noise ADE in the CityGML specification document. The specification contains a complete annex on the Noise ADE and provides both its XML schema definition and corresponding example datasets. However, you are not required to have expert knowledge of the Noise ADE in order to follow this tutorial.

The citygml4j library package which you can download from the Files section contains example source code on how to integrate the Noise ADE into your citygml4j application. The source code examples merge the following steps into one single application and thus can be used as an additional guidance.

• Step 1: Binding an ADE XML schema to citygml4j-compliant JAXB classes
  A set of JAXB classes representing the ADE type definitions is a necessary prerequisite for un/marshalling ADE content through citygml4j. The binding can either be done manually or automatically with the help of citygml4j's ADE schema compiler ade-xjc.
• Step 2: Wrapping the JAXB classes with citygml4j-compliant content classes
  The JAXB classes are sufficient when it comes to un/marshalling of ADE-enriched documents using JAXB. However, they do not interact with the high-level citygml4j content classes wich are used in your business code. Thus, the second step deals with wrapping the JAXB classes by citygml4j-compliant content classes.
• Step 3: Defining the mapping between JAXB and citygml4j
  Having implemented a set of JAXB classes and corresponding wrappers which map the contents of the ADE XML schema, the next step is to explicitly define the mapping between both representations.
• Step 4: Registering the ADE implementation with citygml4j
  Finally, the ADE implementation has to been announced to citygml4j in order to enable un/marshalling of ADE-enriched documents through citygml4j.
• Optional: Converting ADE content objects between different CityGML versions
  Starting from version 0.2.0, citygml4j comes with built-in support for converting citygml4j content objects between different CityGML versions. In order to make citygml4j consider your ADE content objects in this conversion process you have to implement corresponding conversion routines for your ADE content classes and announce them to citygml4j. This step is optional.

Business code examples based on your ADE implementation¶

If you have successfully mapped the ADE XML schema to a citygml4j-compliant representation you are ready to make use of your ADE within your citygml4j business code. The following two tutorials contain very simply examples on how to write and read ADE-enriched CityGML instance documents. The example code is based on the CityGML Noise ADE implementation which has been developed in the previous section. As mentioned above, a more comprehensive example is delivered together with the citygml4j library package which can be downloaded from the Files section.

• Writing ADE-enriched CityGML datasets
  Write your first ADE-enriched CityGML instance document through citygml4j. Please read the tutorial on Writing CityGML datasets beforehand.
• Reading ADE-enriched CityGML datasets
  Read a CityGML instance document containing ADE elements and access their content within your business code. Please read the tutorial on Reading CityGML datasets beforehand.