= gradle-jaxb-plugin
:exclamation:IMPORTANT PLUGIN ID CHANGES:exclamation:
This plugin is an update to the original project this was forked from.
We acknowledge and are grateful to these developers for their contributions to open source.
You can find the source code of their original using the forked from
link of this project.
In compliance with the license chosen by the original author, we are publishing this modified version since they have not kept up with the maintenance needs of the community.
To prevent possible collisions and/or confusion if the original author decides to accept our PR's or to simply begin anew, we have changed the id and package names.
In compliance with the gradle plugin submission guidelines, the plugin's id was changed from com.github.jacobono.jaxb
to org.openrepose.gradle.plugins.jaxb
.
This affects how you apply the plugin (apply plugin: 'org.openrepose.gradle.plugins.jaxb'
).
This Gradle plugin defines some conventions for XSD projects and provides some processing to ease some of the maintenance of these projects by:
xjc
task.== Using The Plugin
See this plugin's page in the https://plugins.gradle.org/plugin/org.openrepose.gradle.plugins.jaxb[gradle plugins repo].
== Setting Up The JAXB Configurations
You need the jaxb configuration to run the xjc
task, but that is the only task that requires an external dependency.
If an XJC plugin is used, then simply add it to the dependencies to have it included.
Any version of jaxb that you care to use will work.
== Plugin Tasks
There are only two tasks.
xjc
xjc
ant task on each .xsd
in the dependency tree.xsd-dependency-tree
.xsd
files configured to be parsed.xjc
depends on xsd-dependency-tree
so you don't need to run the tree task at all.
== Plugin Conventions
There are two conventions that can be overridden and one is nested in the other.
The jaxb
convention defines the conventions for the whole plugin, and the xjc
convention defines the conventions for the xjc
ant task.
You can change these defaults with a closure in your build script.
=== JAXB Plugin Convention
These are the configurable parameters for the JAXB Plugin.
.JAXB Plugin Parameters [cols="2,6,3,2"] |=== | Parameter | Description | Default | Type
| xsdDir
| Defined by each project to tell the plugin where to find the .xsd
files to parse.
| ${project.projectDir}/src/main/resources/schema
| String
| xsdIncludes
| RegEx used to produce a List of files found in xsdDir
to compile.
| **/*.xsd
| String
| episodesDir
| All generated episode files go directly under here, no subfolders.
(i.e. "build/generated-resources/episodes", "episodes", "schema/episodes", "xsd/episodes", "XMLSchema/episodes")
| ${project.buildDir}/generated-resources/episodes
| String
| bindingsDir
| User defined binding files to pass into the xjc
task.
All files are directly under this folder, no subfolders.
(i.e. "src/main/resources/schema", "bindings", "schema/bindings", "xsd/bindings", "XMLSchema/bindings")
| ${project.projectDir}/src/main/resources/schema
| String
| bindings
| RegEx used to produce a List of customization files found in bindingsDir
to bind with.
| **/*.xjb
| String
|===
=== XJC Convention
These are the configurable parameters for the JAXB Plugin's XJC interactions.
.XJC Plugin Parameters [cols="2,6,3,2"] |=== | Parameter | Description | Default | Type
|taskClassname
| Enables a custom task classname to run the XJC task if something other than JAXB is desired.
Useful if JAXB2 is required to be used.
| com.sun.tools.xjc.XJCTask
| String
|destinationDir
| The directory relative to project.rootDir
where generated code will be written to.
In order to automatically remove previously generated sources, this directory is deleted whenever the Up To Date check fails.
This should never point to a location under the main source directory.
| ${project.buildDir}/generated-sources/xjc
| String
|producesDir
| This parameter has never been used by this plugin.
It remains only for the purposes of backwards compatibility.
Consider it deprecated and that it will be removed in a future release.
| ${project.buildDir}/generated-sources/xjc
| String
|generateEpisodeFiles
| Enables the creation of the Episode files
| true
| boolean
|extension
| Run XJC compiler in extension mode
| true
| boolean
|removeOldOutput
| Only used with nested <produces>
elements, when yes
all files are deleted before XJC is run
| yes
| String
|header
| generates a header in each generated file
| true
| boolean
|generatePackage
| specify a package to generate to
| Not Defined
| String
|args
| List of extra String arguments to pass the xjc
ant task.
This is useful when activating JAXB2 plugins.
| Empty String
| List<String>
|accessExternalSchema
| Enables setting the new javax.xml.accessExternalSchema
system property that causes the plugin to not work as expected under JSE8.
| Implementation Specific
| String
|===
For more in depth description please see the https://jaxb.java.net/2.2.7/docs/ch04.html#tools-xjc-ant-task[XJC Ant Task documentation].
== Examples
=== Default Example using JAXB
If the default conventions are used, then there is nothing to configure.
=== Default Example using JAXB2
Customized to use xjc
plugins.
dependencies { jaxb "org.jvnet.jaxb2_commons:jaxb2-basics:1.11.1" jaxb 'org.jvnet.jaxb2_commons:jaxb2-basics-ant:1.11.1' jaxb 'org.jvnet.jaxb2_commons:jaxb2-basics-annotate:1.0.4' jaxb 'org.slf4j:slf4j-log4j12:1.7.25' }
== Defining The Plugin For All Projects
Create a convention for xsd projects to have a suffix of -schema
, then it is easy to write:
subprojects { project -> if(project.name.endsWith("-schema")) { apply plugin: 'org.openrepose.gradle.plugins.jaxb'
dependencies {
jaxb 'org.glassfish.jaxb:jaxb-xjc:2.2.11'
jaxb 'org.glassfish.jaxb:jaxb-runtime:2.2.11'
}
applying the plugin to all schema projects.
Another way to do this is by adding a boolean property to the gradle.properties
file in the sub-projects.
You can then use it this way:
subprojects { project -> if(Boolean.valueOf(project.getProperties().getOrDefault('doJAXB', 'false'))) { apply plugin: 'org.openrepose.gradle.plugins.jaxb'
dependencies {
jaxb 'org.glassfish.jaxb:jaxb-xjc:2.2.11'
jaxb 'org.glassfish.jaxb:jaxb-runtime:2.2.11'
}
== Other Features
=== Depend On Another Project
This lets gradle know that the xjc task of a project is dependent on the xjc task of another project. This can be achieved with:
This expresses that xsd's definitely depend on other xsd's outside of their parent folder xsdDir
.
This will run the xjc task on common
before running the xjc task of of the project this is defined in.
== Examples
You can find some small example projects using this plugin in the link:./examples[examples folder].
Simply issue ../gradlew clean build
from within it to run them all.
For a basic example of using this plugin with multiple sub-projects that have interactions, please see this https://github.com/wdschei/gradle-jaxb-plugin-test[test project].
For a real world example of this plugin, please visit the main https://github.com/rackerlabs/repose[Repose project].
== Improvements
If you have an idea that would make something a little easier, we'd love to hear about it. If you think you can make this plugin better, then simply fork it like we did and submit a pull request.