Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/intershopcommunicationsag/jaxb-gradle-plugin

Gradle JAXB code generation plugin
https://github.com/intershopcommunicationsag/jaxb-gradle-plugin

build-automation gradle gradle-plugin

Last synced: about 2 months ago
JSON representation

Gradle JAXB code generation plugin

Awesome Lists containing this project

README 

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



[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   | com.intershop.build.jaxb.task.SchemaToJavaTask | This task generates Java code for the specified schema and binding configuration.

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

[cols="20%,15%,65%", width="95%", options="header"]

|===

|Method | Values | Description

|*javaGen*      |<>  | This contains all Java code generation configurations.

|*schemaGen*    |<>| 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`      | `/generated/jaxb/java/` | Generated code will be written under this directory.

|*args*                | `List` | `[]`        | 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` | 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`      | `/generated/jaxb/schema/` | Base directory to place the generated schema files

|*InputDir*         | `File`      | `null` | Base directory of input files

|*excludes*             | List | [] | List of exclude filters of this configuration.

|*includes*             | List | ['**/**/*.java'] | List of includes filters of this configuration.

|*namespaceconfigs* | `Map` | `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.