jaxb-gradle-plugin
jaxb-gradle-plugin copied to clipboard
Gradle JAXB code generation plugin
= JAXB Gradle Plugin :latestRevision: 6.0.0 :toc: :icons: font
[CAUTION]
The default configuration was adapted for Jakarta XML Binding 3.0.1.
Starting with version 6, the plugin is working only with Gradle 8.0 or higher.
== Summary This plugin generates Java code from schema files (see https://jaxb.java.net/jaxb20-ea/docs/xjcTask.html[com.sun.tools.xjc.XJCTask]) or schema files from existing Java code (see https://jaxb.java.net/jaxb20-ea/docs/schemagenTask.html[com.sun.tools.jxc.SchemaGenTask]).
== Usage To apply the JAXB Gradle Plugin to your projects, add the following in your build script:
++++
Groovy
++++[source,groovy] [subs=+attributes] .build.gradle
plugins { id 'com.intershop.gradle.jaxb' version '{latestRevision}' }
jaxb { // generate java code from schema javaGen { //generates a 'project' schema file from existing java code name { schema = file('schema.xsd') binding = file('binding.xjb') } }
//generates schema from java code
schemaGen {
//generates java code for project from project schema
name {
javaFiles = fileTree(dir: 'src/main/java', include: 'com/corporate/annotated/**/binding/**/*.java')
namespaceconfigs = [ 'http://www.corporate.com/xml/ns/corporate/feature/1.0' : 'feature.xsd' ]
}
}
}
++++
++++
Kotlin
++++[source,kotlin] [subs=+attributes] .build.gradle.kts
plugins { id("com.intershop.gradle.jaxb") version "{latestRevision}" }
jaxb { // generate java code from schema javaGen { //generates a 'project' schema file from existing java code register("name") { schema = file("schema.xsd") binding = file("binding.xjb") } }
//generates schema from java code
schemaGen {
//generates java code for project from project schema
register("name") {
javaFiles = fileTree("dir" to "src/main/java", "include" to "com/corporate/annotated/**/binding/**/*.java")
namespaceconfigs = mapOf("http://www.corporate.com/xml/ns/corporate/feature/1.0" to "feature.xsd")
}
}
}
++++
If the JavaBasePlugin is applied to the project, generated java sources will be added to the specified source set. Per default the main source set is used.
IMPORTANT: This plugin uses the following dependencies: + com.sun.xml.bind:jaxb-xjc:3.0.1 + com.sun.xml.bind:jaxb-jxc:3.0.1 + com.sun.xml.bind:jaxb-impl:3.0.1 + com.sun.xml.bind:jaxb-core:3.0.1 + org.glassfish.jaxb:jaxb-runtime:3.0.1 + jakarta.xml.bind:jakarta.xml.bind-api:3.0.1 + jakarta.activation:jakarta.activation-api:2.0.1 +
It is possible to overwrite the project dependency configuration 'jaxb', if you want use an other version of JAXB. It is also possible to add additional dependencies to the configured "jaxb" with the configuration "jaxbext".
== Tasks
The JAXB Gradle plugin adds one task jaxb
to the project. This task depends on all other plugin task. It is a task added for each configuration in schemaGen and javaGen.
[cols="25%,30%,45%", width="95%, options="header"]
|===
|Task name |Type |Description
|jaxb | Task | Overall jaxb
code generation task of a project. This task depends on all jaxbJavaGen
and jaxbSchemaGen
tasks.
|jaxbJavaGen
== Project Extension 'jaxb'
This plugin adds an extension jaxb
to the project.
=== Methods [cols="20%,15%,65%", width="95%", options="header"] |=== |Method | Values | Description |javaGen |<<javaGen, SchemaToJava>> | This contains all Java code generation configurations. |schemaGen |<<schemaGen, JavaToSchema>>| This contains all schema code generation configurations. |===
==== [[javaGen]]Object 'javaGen' (SchemaToJava)
===== Properties
[cols="17%,17%,15%,51%", width="90%, options="header"] |=== |Property | Type | Default value | Description
|outputDir | File
| <project.buildDir>/generated/jaxb/java/<config name>
| Generated code will be written under this directory.
|args | List<String>
| []
| Additional command line arguments passed to the XJC (-use-runtime, -schema, -dtd, -relaxng, -Xlocator, -Xsync-methods)
|sourceSetName | String
| 'main'
| Generated source code will be added to the source set.
|encoding | String
| 'UTF-8'
| specify character encoding for generated source files
|strictValidation | boolean
| false
| perform strict validation of the input schema
|extension | boolean
| false
| allow vendor extensions - do not strictly follow the +
compatibility rules and app E.2 from the JAXB Spec
|header | boolean
| false
| Generate a header in each generated file indicating that this file is generated by such and such version of JAXB RI when. +
If this value is false '-no-header' will be added to the command line parameter list.
|packageName | String
| 'generated'
| If specified, generated code will be placed under this Java package.
|schema | File
| null
| A schema file to be compiled.
|binding | File
| null
| An external binding file that will be applied to the schema file.
|catalog | File
| null
| Specify the catalog file to resolve external entity references. Support TR9401, XCatalog, and OASIS XML Catalog format. See the catalog-resolver sample for details.
|schemas | FileCollection
| null
| To compile more than one schema at the same time, use this configuration.
|bindings | FileCollection
| null
| To specify more than one external binding file at the same time, use this configuration.
|targetVersion | String
| '2.2'
| Specifies the runtime environment in which the generated code is supposed to run. Expects also 2.0 or 2.1 values. This allows more up-to-date versions of XJC to be used for developing applications that run on earlier JAXB versions.
|language | String
| 'XMLSCHEMA'
| Specifies the schema language to compile. Supported values are "WSDL", "XMLSCHEMA", and "WSDL." Case insensitive.
|antTaskClassName | String
| 'com.sun.tools.xjc.XJCTask'
| The JAXB tools (e.g. XJC) bundled with the JDK are relocated to a package not matching the JAXB-RI. There are a lot of XJC plugins around compiled against the JAXB-RI which cannot be used with the JAXB tools bundled with the JDK due to this. When configuring the plugin to use the JAXB-RI Ant task instead of the Ant task bundled with the JDK (e.g. com.sun.tools.xjc.XJC2Task), those plugins can be used.
|===
===== Method
[cols="17%,17%,66%", width="90%, options="header"]
|===
|Method | Parameter | Description
|arg | String
| Add an additional command line argument passed to the XJC
|args | List<String>
| Add additional command line arguments passed to the XJC
|===
==== [[schemaGen]]Object 'schemaGen' (JavaToSchema)
[cols="17%,17%,15%,51%", width="90%, options="header"] |=== |Property | Type | Default value | Description
|outputDir | File
| <project.buildDir>/generated/jaxb/schema/<config name>
| Base directory to place the generated schema files
|InputDir | File
| null
| Base directory of input files
|excludes | List<String> | [] | List of exclude filters of this configuration.
|includes | List<String> | ['//*.java'] | List of includes filters of this configuration.
|namespaceconfigs | Map<String,String>
| null
| Control the file name of the generated schema. The entry key is the namespace attribute and the value is the file name. When this element is present, the schema document generated for the specified namespace will be placed in the specified file name.
|episode | String
| null
| If specified, generate an episode file with the specified name.
|===
===== Method
[cols="17%,17%,66%", width="90%, options="header"]
|===
|Method | Parameter | Description
|exclude | String
| Add exclude filter to excludes list
|include | String
| Add include filter to excludes list
|===
=== Example Configurations ==== Simple configuration for java code generation [source,groovy,subs="attributes"]
plugins { id 'java' id 'com.intershop.gradle.jaxb' version '{latestRevision}' }
jaxb { javaGen { posConfig { packageName = '' schema = file('pos.xsd') } } }
==== Configuration with binding file for java code generation
[source,groovy,subs="attributes"]
plugins { id 'java' id 'com.intershop.gradle.jaxb' version '{latestRevision}' }
jaxb { javaGen { posConfig { binding = file('binding.xjb') schema = file('pos.xsd') } } }
==== Configuration for schema generation
[source,groovy,subs="attributes"]
plugins { id 'java' id 'com.intershop.gradle.jaxb' version '{latestRevision}' }
jaxb { schemaGen { orderstatusimport { javaFiles = fileTree(dir: 'javasource', include: 'com/corporate/annotated//binding//*.java') namespaceconfigs = ['http://com.corporate.com/xml/ns/corporate/feature/status/1.0' : 'feature_xml.xsd' ] } } }
== Contribute
See link:https://github.com/IntershopCommunicationsAG/.github/blob/main/CONTRIBUTE.asciidoc[here] for details.
== License
Copyright 2014-2021 Intershop Communications.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.