Initial implementation for #130

FasterXML · Apr 25, 2021 · 62475cf · 62475cf
1 parent cb6bc48
commit 62475cf
Show file tree

Hide file tree

Showing 54 changed files with 6,295 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -11,7 +11,9 @@ Currently included are:
 * [Afterburner](afterburner/)
 * [Blackbird](blackbird/) (NEW in 2.12!)
 * [Guice](guice/)
-* [JAXB Annotations](jaxb/)
+* Java XML Binding Annotation compatibility
+    * "Old" (`java.xml.bind`) annotations: [JAXB Annotations](jaxb/)
+    * New "Jakarta" (`jakarta.xml.bind`): [Jakarta XML Bind Annotations(jakarta-xmlbind/) (added in 2.13)
 * [Mr Bean](mrbean/)
 * [OSGi](osgi/)
 * [Paranamer](paranamer/)
@@ -31,11 +33,24 @@ licensed as per:
 
 whereas 3.0 will use [ByteBuddy](https://github.com/raphw/byte-buddy) (licensed as per https://github.com/raphw/byte-buddy/blob/master/LICENSE)
 
-
 ## Using Jakarta
 
-A note on compatibility of JAXB annotations module, Jakarta 3.0 API libraries for JAXB: with Jackson 2.12,
-Jakarta versions can be referenced for the JAXB module by using the classifier "jakarta" in your dependency
+### Jackson 2.13 and later (once released)
+
+With 2.13, you need to choose either:
+
+* `jackson-module-jaxb-annotations` for "old JAXB" (2.x): supports `javax.xml.bind` annotations
+* `jackson-module-jakarta-xmlbind-annotations` for "new Jakarta JAXB" (3.x): supports `jakarta.xml.bind` annotations
+
+(in theory you can even use both, with databind `AnnotationIntrospectorPair`, but more often you will only want one of these)
+
+Note that Jakarta version was added in Jackson 2.13 and was not available for earlier versions.
+
+### Jackson 2.12 (only)
+
+Alternatively if using Jackson 2.12, there is a specific variant of `jackson-module-jaxb-annotations`
+available, usable with Maven classifier of "jakarta". You can use it instead of "old" JAXB variant
+by specifying classifier like so:
 
 ```
 <dependency>

diff --git a/jakarta-xmlbind/README.md b/jakarta-xmlbind/README.md
@@ -0,0 +1,55 @@
+## Overview
+
+This Jackson extension module provides support for using Jakarta Java XML Binding
+(`jakarta.xml.bind`) annotations as an alternative to native Jackson annotations.
+
+It is most often used to make it easier to reuse existing data beans that used with
+JAXB framework to read and write XML.
+
+NOTE! This module was added in Jackson 2.13 to support NEW version 3.0 API of JAXB,
+after "old" `javax.xml.` package had to be repackaged as "Jakarta" variant.
+For older `java.xml.bind` package, look at "jackson-module-jaxb-annotations".
+
+## Maven dependency
+
+To use this extension on Maven-based projects, use following dependency:
+
+```xml
+<dependency>
+  <groupId>com.fasterxml.jackson.module</groupId>
+  <artifactId>jackson-module-jakarta-jaxb-annotations</artifactId>
+  <version>2.13.0</version>
+</dependency>
+```
+
+(or whatever version is most up-to-date at the moment)
+
+## Usage
+
+To enable use of JAXB annotations, one must add `JakartaJaxbAnnotationIntrospector` provided
+by this module. There are two ways to do this:
+
+* Register `JakartaJaxbAnnotationModule`, OR
+* Directly add `JakartaJaxbAnnotationIntrospector` for use by `ObjectMapper`
+
+Module registration works in standard way:
+
+```java
+JakartaJaxbAnnotationModule module = new JakartaJaxbAnnotationModule();
+// configure as necessary
+objectMapper.registerModule(module);
+```
+
+and the alternative -- explicit configuration is done as:
+
+```java
+AnnotationIntrospector introspector = new JakartaJaxbAnnotationIntrospector();
+// if ONLY using JAXB annotations:
+mapper.setAnnotationIntrospector(introspector);
+// if using BOTH JAXB annotations AND Jackson annotations:
+AnnotationIntrospector secondary = new JacksonAnnotationIntrospector();
+mapper.setAnnotationIntrospector(new AnnotationIntrospector.Pair(introspector, secondary);
+```
+
+Note that by default Module version will use JAXB annotations as the primary,
+and Jackson annotations as secondary source; but you can change this behavior
diff --git a/jakarta-xmlbind/pom.xml b/jakarta-xmlbind/pom.xml
@@ -0,0 +1,89 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<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/xsd/maven-4.0.0.xsd">
+  <!-- This module was also published with a richer model, Gradle metadata,  -->
+  <!-- which should be used instead. Do not delete the following line which  -->
+  <!-- is to indicate to Gradle or any Gradle module metadata file consumer  -->
+  <!-- that they should prefer consuming it instead. -->
+  <!-- do_not_remove: published-with-gradle-metadata -->
+  <modelVersion>4.0.0</modelVersion> 
+  <parent>
+    <groupId>com.fasterxml.jackson.module</groupId>
+    <artifactId>jackson-modules-base</artifactId>
+    <version>2.13.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>jackson-module-jakarta-xmlbind-annotations</artifactId>
+  <name>Jackson module: JAXB Annotations</name>
+  <packaging>bundle</packaging>
+
+  <description>Support for using Jakarta Xml Bind (aka JAXB 3.0) annotations as an alternative
+  to "native" Jackson annotations, for configuring data-binding.
+</description>
+  <url>https://github.com/FasterXML/jackson-modules-base</url>
+
+  <properties>
+   <!-- Generate PackageVersion.java into this directory. -->
+    <packageVersion.dir>com/fasterxml/jackson/module/jakarta/xmlbind</packageVersion.dir>
+    <packageVersion.package>${project.groupId}.jakarta.xmlbind</packageVersion.package>
+    <!-- 22-Mar-2019, tatu: [modules-base#80]: Presence of JAF on the bundle classpath is only necessary
+           when ser/deser'ing javax.a.DataHandlers
+      -->
+    <osgi.import>javax.activation;resolution:=optional,*</osgi.import>
+
+    <version.xmlbind.api>3.0.0</version.xmlbind.api>
+  </properties>
+  <dependencies>
+    <!-- Extends Jackson core and mapper; minor dep on annotations too (JsonInclude) -->
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-annotations</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-core</artifactId>
+    </dependency>
+    <dependency>
+      <groupId>com.fasterxml.jackson.core</groupId>
+      <artifactId>jackson-databind</artifactId>
+    </dependency>
+
+    <!--  and actual Jakarta Xml Bind annotations, types -->
+    <dependency>
+      <groupId>jakarta.xml.bind</groupId>
+      <artifactId>jakarta.xml.bind-api</artifactId>
+      <version>${version.xmlbind.api}</version>
+    </dependency>
+
+    <dependency>
+      <groupId>jakarta.activation</groupId>
+      <artifactId>jakarta.activation-api</artifactId>
+      <version>1.2.1</version>
+    </dependency>
+
+    <!-- may also need JAXB impl for tests -->
+    <dependency>
+      <groupId>org.glassfish.jaxb</groupId>
+      <artifactId>jaxb-runtime</artifactId>
+      <version>${version.xmlbind.api}</version>
+      <scope>test</scope>
+    </dependency>
+
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>com.google.code.maven-replacer-plugin</groupId>
+        <artifactId>replacer</artifactId>
+      </plugin>
+      <plugin>
+        <groupId>org.moditect</groupId>
+        <artifactId>moditect-maven-plugin</artifactId>
+        <inherited>true</inherited>
+        <configuration>
+          <jvmVersion>11</jvmVersion>
+        </configuration>
+      </plugin>
+
+    </plugins>
+  </build>
+</project>
diff --git a/...-xmlbind/src/main/java/com/fasterxml/jackson/module/jakarta/xmlbind/AdapterConverter.java b/...-xmlbind/src/main/java/com/fasterxml/jackson/module/jakarta/xmlbind/AdapterConverter.java
@@ -0,0 +1,52 @@
+package com.fasterxml.jackson.module.jakarta.xmlbind;
+
+import jakarta.xml.bind.annotation.adapters.XmlAdapter;
+
+import com.fasterxml.jackson.databind.JavaType;
+import com.fasterxml.jackson.databind.type.TypeFactory;
+import com.fasterxml.jackson.databind.util.StdConverter;
+
+public class AdapterConverter
+    extends StdConverter<Object,Object>
+{
+    protected final JavaType _inputType, _targetType;
+
+    protected final XmlAdapter<Object,Object> _adapter;
+
+    protected final boolean _forSerialization;
+
+    @SuppressWarnings("unchecked")
+    public AdapterConverter(XmlAdapter<?,?> adapter,
+            JavaType inType, JavaType outType, boolean ser)
+    {
+        _adapter = (XmlAdapter<Object,Object>) adapter;
+        _inputType = inType;
+        _targetType = outType;
+        _forSerialization = ser;
+    }
+
+    @Override
+    public Object convert(Object value)
+    {
+        try {
+            if (_forSerialization) {
+                return _adapter.marshal(value);
+            }
+            return _adapter.unmarshal(value);
+        } catch (RuntimeException e) {
+            throw e;
+        } catch (Exception e) {
+            throw new IllegalArgumentException(e);
+        }
+    }
+
+    @Override
+    public JavaType getInputType(TypeFactory typeFactory) {
+        return _inputType;
+    }
+
+    @Override
+    public JavaType getOutputType(TypeFactory typeFactory) {
+        return _targetType;
+    }
+}