The JAXB artefacts are generated using the com.sun.tools.xjc tool that ships with Java.
This parses the XML Schema and builds a set of classes based on the schema.
xjc is run using a number of additional plugins to handle the creation of fluent builders and common interfaces.
Prior to running xjc the schema undergoes an automated tidy up process to rename many of the elements to improve the class names in the JAXB model, i.e. FooComplexType becomes Foo.
The generation process is reliant on having the required version of the Event Logging XML schema in the directory event-logging-generator/schema/. This directory is ignored by source control. The Gradle build will download the schema from GitHub as long as the following line in the root build.gradle file has been set to the correct schema version.
def eventLoggingSchemaVer = "v3.1.2"The class that manages the code generation is event.logging.gen.GenClasses.
As well running xjc it copies various non-generated classes and resources into the event-logging-api module from event-logging-base which is what the published jar is ultimately built from.
As part of this copy process any packages or imports for event.logging.base are changed to event.logging to reflect their new home.
To further fine tune the code that is generated from the schema, xjc uses a bindings file simple-binding.xjb.
This allows us to do things like changing the name of generated classes or making classes implement a non-generated interface.
Note the bindings file is run against a modified version of the source schema (schema.mod.xsd) that is produced by GenClasses.
The main aim of this is to remove the suffix ComplexType from the complex types so that the Java classes don't have this as a suffix.
Because the bindings file operates against the modified schema any xpaths will need to be in terms of that scheme, i.e. @name='Foo' rather than @name='FooComplexType'.
Any changes to the schema may require changes to the bindings, e.g. the introduction of a new event action would require some additional bindings to make its class implement the EventAction interface.
Part of the build process is to compare the generated code against a previous release. This allows you to see how any change to the schema has impacted the java code. As the build is unable to determine what constitutes the previous release you need to specify it in the root build file.
ext.previousReleaseVersion = "v4.0.7_schema-v3.2.4"The Gradle build will generate the JAXB artefacts and go onto build the API jar.
The Event Logging XML schema is authored in github.com/gchq/event-logging-schema. The Event Logging XML Schema in event-logging-generator/schema/ should never be edited directly. It should always be a copy of the desired version from event-loggin-schema.
The API jar is built using Gradle. This will generate the JAXB artefacts, as well as copying the API classes, test classes and XML schema from the base module into the event-logging-api module.
All files under event-logging-api/src are transient and will be generated or copied in as part of the Gradle build.
The build is run as follows:
./gradlew clean build
To run the build with specific version number do something like:
./gradlew clean build -Pversion=v1.2.3_schema-v4.5.6
Towards the end of the build process, it will download the sources jar for the latest release of event-logging from GitHub and compare the Java source files in it to those just built. This provides a quick way of seeing the impact on the API from any changes in the schema. For example some schema changes that would not be a breaking change as far as an XML document is concerned (e.g. a rename of a complex type), would become a breaking change in the JAXB classes.
By default the build will download the -client variant of the schema from github. This is not ideal when you are making changes to the schema and want to see the impact on the JAXB library. If you want to run the build using a local copy of the schema you can do something like the following:
./buildAgainstLocalSchema.shThis will build the client variant of the schema from whatever version of the master event-logging.xsd schema is in the local event-logging-schema repo, then build event-logging from it.
The Javadoc for the library is automatically pulled from the schema annotations by jaxb2-rich-contract-plugin.
Therefore it is important to ensure that all elements, types and complex types in the schema are fully annotated to provide a rich set of javadocs.
To perform a release simply tag the master branch as follows:
git tag -a vX.Y.Z_schema-vA.B.C
Where X.Y.Z is the version of the event-logging API library and A.B.C is the version of the event-logging XMLSchema.
The two version numbers are totally independent of each other and have different life-cycles, e.g. a minor release of the schema could trigger a breaking change and major release of the API.
Equally there may be a new release of the API with an identical schema version to the previous one.
The build process will validate the tag when it is used as the version property in Travis.
When prompted to enter the commit message set the first line to event-logging-vX.Y.Z_schema-vA.B.C and lines 3+ to be the changes made, as extracted from the CHANGELOG.md file.
Once the tag is picked up by Travis, the build will be run and the build artefacts published to GitHub releases.