GitHub - highsource/jaxb-tools at jaxb-tools-2.x (original) (raw)

JAXB Tools

Maven Central GitHub Actions Status CodeQL

Welcome to the most advanced and feature-full sets of JAXB-related tools.

The project is currently containing the following tools :

Please check our Migration Guide for any questions about migrating from previous releases to newers one.

Maven versions

Starting from 2.0.10, this plugin requires maven 3.1.0 as minimal version.

If you still need maven 2.x or maven 3.0.x, you can still use the previous released versions but you should consider upgrading maven to at least 3.1.0.

Java versions

This project supports Java 8 and higher.

The build is tested against JDK8, JDK11 and JDK17.

Documentation

Please refer to the wiki for the full documentation.

Disclaimer

This project is not developed, supported or in any other way affiliated with Apache, Eclipse or Oracle.

It was a completely independent development by its creator, Alexey Valikov.

It is now maintained by a group of people who are interested in keeping jaxb-tools working with future versions of Java and Jakarta.

JAXB Maven Plugin

This Maven plugin generates Java classes during Maven builds from XML Schemas (as well as WSDL, DTDs, RELAX NG formats).

It wraps and enhances the JAXB Schema Compiler (XJC) with its own set of plugins and customization points.

Quick start

<project ...> ... org.jvnet.jaxb jaxb-maven-plugin 2.0.5 generate ...

JAXB Versions

The current version 2.X of this plugin supports only JAXB 2.3.

A version of this plugin that supports JAXB >= 3.x is currently being worked on.

If you need an older JAXB version, you can use one of the following variants, which are no longer supported:

Similar Projects

If you experience issues with the Mojohaus JAXB2 Maven Plugin (org.codehaus.mojo:jaxb2-maven-plugin), please file it on their project page.

JAXB2 Basics

JAXB2 Basics is an open source project which provides useful plugins and tools for JAXB 2.x reference implementation.

Documentation

Please refer to the wiki for documentation.

JAXB2 Basics can only be used with JAXB/XJC 2.3.x. JAXB/XJC versions 2.2.x and earlier are no longer supported.

If you're using jaxb2-basics-runtime dependency with previous generated code, please be sure to use 0.11 as minimal version or consider upgrading to 2.x. The new published artifact org.jvnet.jaxb:jaxb2-basics-runtime is backward compatible with org.jvnet.jaxb2_commons:jaxb2-basics-runtime from version 0.11 and above.

Using JAXB2 Basics

JAXB2 Basics Plugins

Credits

Annox

Parse Java annotations from text or XML resources.

Please refer to the wiki for documentation.

// Parse annotation from the string XAnnotation xannotation = (XAnnotation) XAnnotationParser.INSTANCE.parse ("@javax.xml.bind.annotation.XmlRootElement(name="foo")");

// Create an instance of the annotation XmlRootElement xmlRootElement = xannotation.getResult(); assertEquals("foo", xmlRootElement.name()); assertEquals("##default", xmlRootElement.namespace());

// Analyze the structure of the annotation assertEquals(String.class, xannotation.getFieldsMap().get("name").getType()); assertEquals("##default", xannotation.getFieldsMap().get("namespace").getResult());

JAXB Annotate Plugin

JAXB Annotate Plugin is capable of adding or removing arbitrary annotations to/from the generated sources.

Please refer to the wiki for documentation.

Usage overview

Providing annotations

You can annotate your schema-derived elements using normal Java annotation syntax. (Old XML syntax is still supported but no longer recommended.)

Current limitations:

You can put your annotations directly in schema:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" jaxb:version="2.1" xmlns:annox="http://annox.dev.java.net" jaxb:extensionBindingPrefixes="annox">

<xsd:complexType name="FooType">
    <xsd:annotation>
        <xsd:appinfo>
            <annox:annotate>@java.lang.SuppressWarnings({"unchecked","rawtypes"})</annox:annotate>
            <annox:annotate target="package">@javax.annotation.Generated({"XJC","JAXB2 Annotate Plugin"})</annox:annotate>
        </xsd:appinfo>
    </xsd:annotation>
    <xsd:sequence>
        <xsd:element name="bar" type="xsd:string"/>
        <xsd:element name="foobar" type="xsd:string">
            <xsd:annotation>
                <xsd:appinfo>
                    <annox:annotate>@java.lang.SuppressWarnings({"unchecked","rawtypes"})</annox:annotate>
                    <annox:annotate target="setter">@java.lang.Deprecated</annox:annotate>
                    <annox:annotate target="setter-parameter">@java.lang.Deprecated</annox:annotate>
                    <annox:annotate target="getter">@java.lang.Deprecated</annox:annotate>
                    <annox:annotate target="field">@java.lang.Deprecated</annox:annotate>
                    <annox:annotate target="class">@java.lang.Deprecated</annox:annotate>
                </xsd:appinfo>
            </xsd:annotation>
        </xsd:element>
    </xsd:sequence>
</xsd:complexType>

<xs:simpleType name="FooEnum">
    <xs:annotation>
        <xs:appinfo>
            <annox:annotateEnumValueMethod>@java.lang.Deprecated</annox:annotateEnumValueMethod>
        </xs:appinfo>
    </xs:annotation>

    <xs:restriction base="xs:string">
        <xs:enumeration value="BAR"/>
        <xs:enumeration value="BAZ"/>
    </xs:restriction>
</xs:simpleType>

Or in binding files:

<jaxb:bindings xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:annox="http://annox.dev.java.net" xsi:schemaLocation="http://java.sun.com/xml/ns/jaxb http://java.sun.com/xml/ns/jaxb/bindingschema_2_0.xsd" jaxb:extensionBindingPrefixes="xjc annox" version="2.1">

<jaxb:bindings schemaLocation="schema.xsd" node="/xs:schema">
    <jaxb:bindings node="xs:complexType[@name='issueJIIB39CType']">
        <annox:annotateClass>@javax.xml.bind.annotation.XmlRootElement(name="IssueJIIB39CType")</annox:annotateClass>
    </jaxb:bindings>
    <jaxb:bindings node="xs:complexType[@name='issueJIIB39CType']/xs:attribute[@name='test']">
        <annox:annotate target="field">@javax.xml.bind.annotation.XmlAttribute(required=false, name="test")</annox:annotate>
    </jaxb:bindings>
</jaxb:bindings>

You can use the following customization elements in the http://annox.dev.java.net namespace:

The http://annox.dev.java.net namespace must be declared in the jaxb:extensionBindingPrefixes attribute via prefix, ex.:

xmlns:annox="http://annox.dev.java.net"
jaxb:extensionBindingPrefixes="xjc annox"

Note: yes, I know that http://annox.dev.java.net no longer exists. Changing this namespace would break old builds. This is just a namespace, there must not necessarily be content there. Treat it as a logical identifier, nothing else.

Removing annotations

You can remove annotations using customizations directly in schema:

<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" jaxb:version="2.1" xmlns:annox="http://annox.dev.java.net" jaxb:extensionBindingPrefixes="annox">

<xsd:complexType name="FooType">
    <xsd:annotation>
        <xsd:appinfo>
            <annox:removeAnnotation class="javax.xml.bind.annotation.XmlType" />
        </xsd:appinfo>
    </xsd:annotation>
    <xsd:sequence>
        <xsd:element name="bar" type="xsd:string"/>
        <xsd:element name="foobar" type="xsd:string">
            <xsd:annotation>
                <xsd:appinfo>
                    <annox:removeAnnotation class="javax.xml.bind.annotation.XmlElement" target="field" />
                </xsd:appinfo>
            </xsd:annotation>
        </xsd:element>
    </xsd:sequence>
</xsd:complexType>

Or in binding files:

<jaxb:bindings xmlns:jaxb="http://java.sun.com/xml/ns/jaxb" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xjc="http://java.sun.com/xml/ns/jaxb/xjc" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:annox="http://annox.dev.java.net" xsi:schemaLocation="http://java.sun.com/xml/ns/jaxb http://java.sun.com/xml/ns/jaxb/bindingschema_2_0.xsd" jaxb:extensionBindingPrefixes="xjc annox" version="2.1">

<jaxb:bindings schemaLocation="schema.xsd" node="/xs:schema">
    <jaxb:bindings node="xs:complexType[@name='FooType']">
        <annox:removeAnnotation class="javax.xml.bind.annotation.XmlType" />
    </jaxb:bindings>
    <jaxb:bindings node="xs:complexType[@name='FooType']//xs:element[@name='foobar']">
        <annox:removeAnnotation class="javax.xml.bind.annotation.XmlElement" target="field" />
    </jaxb:bindings>
</jaxb:bindings>

You can use the following customization elements in the http://annox.dev.java.net namespace:

The http://annox.dev.java.net namespace must be declared in the jaxb:extensionBindingPrefixes attribute via prefix, ex.:

xmlns:annox="http://annox.dev.java.net"
jaxb:extensionBindingPrefixes="xjc annox"

Note: yes, I know that http://annox.dev.java.net no longer exists. Changing this namespace would break old builds. This is just a namespace, there must not necessarily be content there. Treat it as a logical identifier, nothing else.

Using JAXB2 Annotate Plugin with Maven

Example:

org.jvnet.jaxb jaxb-maven-plugin true -Xannotate -XremoveAnnotation org.jvnet.jaxb jaxb-basics-annotate com.acme.foo my-custom-annotations

See this example.

Note that annotations are first compiled in the annotations module and the added to the classpath of the jaxb-maven-plugin in the schema module:

Using JAXB2 Annotate Plugin with Ant

See this example.

JAXB Hyperjaxb

Hyperjaxb3 provides relational persistence for JAXB objects. This is preview feature (please give feedback if any problems).