Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[#314] Merge jaxb-annotate to jaxb-tools #315

Merged
merged 1 commit into from
Aug 18, 2023
Merged

[#314] Merge jaxb-annotate to jaxb-tools #315

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .travis.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
language: java
jdk:
- oraclejdk8
4 changes: 4 additions & 0 deletions LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,3 +23,7 @@ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those
of the authors and should not be interpreted as representing official policies,
either expressed or implied, of the FreeBSD Project.
273 changes: 273 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
<<<<<<< HEAD
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove <<< merges flags please

# JAXB Maven Plugin #

Welcome to the `org.jvnet.jaxb:jaxb-maven-plugin`, the most advanced and feature-full Maven plugin for XML Schema compilation.
Expand Down Expand Up @@ -137,3 +138,275 @@ Parse Java annotations from text or XML resources.
assertEquals(String.class, xannotation.getFieldsMap().get("name").getType());
assertEquals("##default", xannotation.getFieldsMap().get("namespace").getResult());
```
=======
[![Maven Central](https://img.shields.io/maven-central/v/org.jvnet.jaxb2_commons/jaxb2-basics-annotate.svg)](https://github.com/highsource/jaxb2-annotate-plugin)

jaxb2-annotate-plugin
=====================

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

Usage overview
--------------

* Annotate your schema using binding files or directly in schema
* Add the plugin to the XJC classpath.
* Add your annotation classes to the XJC classpath.
* Activate the plugin using `-Xannotate`-switch.

Providing annotations
---------------------

You can annotate your schema-derived elements using normal Java annotation syntax.
([Old XML syntax](http://confluence.highsource.org/display/J2B/Annotate+Plugin) is still supported but no longer recommended.)

**Current limitations:**
* Annotation classes must be known in compile time. I.e. annotation classes must be made available in the XJC classpath.
If you want to use your own annotations, you have to pre-compile them and add your annotation classes to the XJC classpath.
* As a consequence, currently you can't use schema-derived enums in your annotations. Since you have to compile annotations
before compiling the schema - and as your enums are first generated from the schema, this is a chicken-and-egg-problem.
* All class names (classes of annotations or classes you use as values in annotations) must be fully qualified.
Inner classes should use the dot (`.`) as delimiter (not `$`).

You can put your annotations directly in schema:

````xml
<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>

</xsd:schema>
````

Or in binding files:

````xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<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>

</jaxb:bindings>
````

You can use the following customization elements in the `http://annox.dev.java.net` namespace:
* `annotate` with the optional `target` attribute
* `package`
* `class`
* `getter`
* `setter`
* `setter-parameter`
* `field`
* `enum-value-method`
* `enum-fromValue-method`
* `annotateProperty`
* `annotatePackage`
* `annotateClass`
* `annotateElement`
* `annotateEnum`
* `annotateEnumConstant`
* `annotateEnumValueMethod` - annotate the `value()` method of the enum
* `annotateEnumFromValueMethod` - annotate the `fromValue(String)` method of the enum

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

* Customize your schema using binding files or directly in schema
* Add the plugin to the XJC classpath.
* Activate the plugin using `-XremoveAnnotation`-switch.

You can remove annotations using customizations directly in schema:

````xml
<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>

</xsd:schema>
````

Or in binding files:

````xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<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>

</jaxb:bindings>
````

You can use the following customization elements in the `http://annox.dev.java.net` namespace:
* `removeAnnotation` with the optional `target` attribute:
* `package`
* `class`
* `getter`
* `setter`
* `setter-parameter`
* `field`
* `enum-value-method`
* `enum-fromValue-method`
* `removeAnnotationFromProperty`
* `removeAnnotationFromPackage`
* `removeAnnotationFromClass`
* `removeAnnotationFromElement`
* `removeAnnotationFromeEnum`
* `removeAnnotationFromEnumConstant`
* `removeAnnotationFromEnumValueMethod` - removes annotation from the `value()` method of the enum
* `removeAnnotationFromEnumFromValueMethod` - removes annotation from the `fromValue(String)` method of the enum

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

* Add `org.jvnet.jaxb2_commons:jaxb2-basics-annotate` as XJC plugin
* Turn on the plugin using `-Xannotate` or `-XremoveAnnotation`switch
* Add artifact with your annotations as another XJC plugin

Example:

````xml
<plugin>
<groupId>org.jvnet.jaxb2.maven2</groupId>
<artifactId>maven-jaxb2-plugin</artifactId>
<configuration>
<extension>true</extension>
<args>
<arg>-Xannotate</arg>
<arg>-XremoveAnnotation</arg>
</args>
<plugins>
<plugin>
<groupId>org.jvnet.jaxb2_commons</groupId>
<artifactId>jaxb2-basics-annotate</artifactId>
</plugin>
<!-- Artifact with custom annotations -->
<plugin>
<groupId>com.acme.foo</groupId>
<artifactId>my-custom-annotations</artifactId>
</plugin>
</plugins>
</configuration>
</plugin>
````
See [this example](https://github.com/highsource/jaxb2-annotate-plugin/tree/master/tests/annox).

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

Using JAXB2 Annotate Plugin with Ant
------------------------------------
See [this example](https://github.com/highsource/jaxb2-annotate-plugin/blob/master/samples/annotate/project-build.xml).
>>>>>>> jaxb2-annotate-plugin/master
5 changes: 0 additions & 5 deletions full-build-9.bat
View file
Open in desktop

This file was deleted.

4 changes: 4 additions & 0 deletions jaxb-annotate-parent/plugin/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/target
.classpath
.project
.settings
72 changes: 72 additions & 0 deletions jaxb-annotate-parent/plugin/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
<!--

Copyright © 2005-2015, Alexey Valikov
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those
of the authors and should not be interpreted as representing official policies,
either expressed or implied, of the FreeBSD Project.

-->
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.jvnet.jaxb</groupId>
<artifactId>jaxb-annotate-plugin-parent</artifactId>
<version>2.0.5-SNAPSHOT</version>
<relativePath>../pom.xml</relativePath>
</parent>
<artifactId>jaxb-basics-annotate</artifactId>
<packaging>jar</packaging>
<name>JAXB Tools :: Annotate :: Plugin</name>
<dependencies>
<dependency>
<groupId>org.jvnet.jaxb</groupId>
<artifactId>jaxb2-basics-tools</artifactId>
<version>${project.version}</version>
<exclusions>
<exclusion>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
</exclusion>
<exclusion>
<groupId>org.jvnet.jaxb</groupId>
<artifactId>jaxb2-basics-runtime</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.glassfish.jaxb</groupId>
<artifactId>jaxb-xjc</artifactId>
<scope>provided</scope>
</dependency>
<!-- Annox -->
<dependency>
<groupId>org.jvnet.jaxb</groupId>
<artifactId>jaxb-annox</artifactId>
<version>${project.version}</version>
</dependency>
</dependencies>
</project>
Loading