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

highsource · Aug 18, 2023 · cee35cc · cee35cc
1 parent e796ab7
commit cee35cc
Show file tree

Hide file tree

Showing 102 changed files with 7,650 additions and 5 deletions.
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,3 @@
+language: java
+jdk:
+- oraclejdk8
diff --git a/LICENSE b/LICENSE
@@ -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.
diff --git a/README.md b/README.md
@@ -1,3 +1,4 @@
+<<<<<<< HEAD
 # JAXB Maven Plugin #
 
 Welcome to the `org.jvnet.jaxb:jaxb-maven-plugin`, the most advanced and feature-full Maven plugin for XML Schema compilation.
@@ -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
diff --git a/full-build-9.bat b/full-build-9.bat
diff --git a/jaxb-annotate-parent/plugin/.gitignore b/jaxb-annotate-parent/plugin/.gitignore
@@ -0,0 +1,4 @@
+/target
+.classpath
+.project
+.settings
diff --git a/jaxb-annotate-parent/plugin/pom.xml b/jaxb-annotate-parent/plugin/pom.xml
@@ -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>