JAXB Gradle Plugin

Table of Contents

• Summary
• Usage
• Tasks
• Project Extension 'jaxb'
  • Methods
  • Example Configurations
• Contribute
• License

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 com.sun.tools.xjc.XJCTask) or schema files from existing Java code (see com.sun.tools.jxc.SchemaGenTask).

Usage

To apply the JAXB Gradle Plugin to your projects, add the following in your build script:

Groovy

build.gradle

plugins {
    id 'com.intershop.gradle.jaxb' version '6.0.0'
}

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

build.gradle.kts

plugins {
    id("com.intershop.gradle.jaxb") version "6.0.0"
}

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:4.0.5     com.sun.xml.bind:jaxb-jxc:4.0.5     com.sun.xml.bind:jaxb-impl:4.0.5     com.sun.xml.bind:jaxb-core:4.0.5     org.glassfish.jaxb:jaxb-runtime:4.0.5     jakarta.xml.bind:jakarta.xml.bind-api:4.0.2     jakarta.activation:jakarta.activation-api:2.1.3

These dependencies are pre-defined by the plugin in the configuration jaxb, which will be passed to the argument -classpath of JAXB tools (xjc for javaGen and schemagen for schemaGen). If you want to use another version of JAXB in the code/schema generation process, you can overwrite configuration jaxb in your project.dependencies. Moreover, you can add additional dependencies to -classpath of JAXB tools with the configuration jaxbext, e.g., in order to use JAXB -extension like -Xequals, -Xcopyable, etc.

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.

Task name	Type	Description
jaxb	Task	Overall jaxb code generation task of a project. This task depends on all jaxbJavaGen and jaxbSchemaGen tasks.
jaxbJavaGen<configuration name>	com.intershop.build.jaxb.task.SchemaToJavaTask	This task generates Java code for the specified schema and binding configuration.
jaxbSchemaGen<configuration name>	com.intershop.build.jaxb.task.JavaToSchemaTask	This task creates schema files for the specified java code.

Project Extension 'jaxb'

This plugin adds an extension jaxb to the project.

Methods

Method	Values	Description
javaGen	SchemaToJava	This contains all Java code generation configurations.
schemaGen	JavaToSchema	This contains all schema code generation configurations.

Object 'javaGen' (SchemaToJava)

Properties

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

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

Object 'schemaGen' (JavaToSchema)

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

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

plugins {
    id 'java'
    id 'com.intershop.gradle.jaxb' version '6.0.0'
}

jaxb {
    javaGen {
        posConfig {
            packageName = ''
            schema = file('pos.xsd')
        }
    }
}

Configuration with binding file for java code generation

plugins {
    id 'java'
    id 'com.intershop.gradle.jaxb' version '6.0.0'
}

jaxb {
    javaGen {
        posConfig {
            binding = file('binding.xjb')
            schema = file('pos.xsd')
        }
    }
}

Configuration for schema generation

plugins {
    id 'java'
    id 'com.intershop.gradle.jaxb' version '6.0.0'
}

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 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.