Merge pull request #1471 from marklogic/feature/java17-javax-xml

Updated README to address how to use Java Client on Java 11 and 17

Author: rjrudin

README.md

@@ -32,21 +32,59 @@ implemented by an endpoint on the server.
 
 ## QuickStart
 
-To use the API in your maven project, include the following in your pom.xml:
+To use the API in your [Maven](https://maven.apache.org/) project, include the following in your pom.xml file:
 
     <dependency>
         <groupId>com.marklogic</groupId>
         <artifactId>marklogic-client-api</artifactId>
         <version>6.0.0</version>
     </dependency>
 
-For gradle projects, use gradle 4.x+ and include the following:
+To use the API in your [Gradle](https://gradle.org/) project, include the following in your build.gradle file:
 
     dependencies {
-        compile "com.marklogic:marklogic-client-api:6.0.0"
+        implementation "com.marklogic:marklogic-client-api:6.0.0"
     }
 
-Read [The Java API in Five Minutes](http://developer.marklogic.com/try/java/index)
+Next, read [The Java API in Five Minutes](http://developer.marklogic.com/try/java/index) to get started.
+
+### Including JAXB support 
+
+If you are using Java 11 or higher (including Java 17) and you wish to use [JAXB](https://docs.oracle.com/javase/tutorial/jaxb/intro/)
+with the Java Client, you'll need to include JAXB API and implementation dependencies as those are no 
+longer included in Java 11 and higher.
+
+For Maven, include the following in your pom.xml file:
+
+    <dependency>
+        <groupId>javax.xml.bind</groupId>
+        <artifactId>jaxb-api</artifactId>
+        <version>2.3.1</version>
+    </dependency>
+    <dependency>
+        <groupId>org.glassfish.jaxb</groupId>
+        <artifactId>jaxb-runtime</artifactId>
+        <version>2.3.2</version>
+    </dependency>
+    <dependency>
+        <groupId>org.glassfish.jaxb</groupId>
+        <artifactId>jaxb-core</artifactId>
+        <version>2.3.0.1</version>
+    </dependency>
+
+For Gradle, include the following in your build.gradle file (this can be included in the same `dependencies` block 
+as the one that includes the marklogic-client-api dependency):
+
+    dependencies {
+        implementation "javax.xml.bind:jaxb-api:2.3.1"
+        implementation "org.glassfish.jaxb:jaxb-runtime:2.3.2"
+        implementation "org.glassfish.jaxb:jaxb-core:2.3.0.1"
+    }
+
+You are free to use any implementation of JAXB that you wish, but you need to ensure that you're using a JAXB 
+implementation that corresponds to the `javax.xml.bind` interfaces. JAXB 3.0 and 4.0 interfaces are packaged under 
+`jakarta.xml.bind`, and the Java API does not yet depend on those interfaces. You are thus free to include an 
+implementation of JAXB 3.0 or 4.0 in your project for your own use; it will not affect the Java API. 
 
 ### Learning More
 

build.gradle

@@ -21,8 +21,14 @@ subprojects {
  	tasks.withType(JavaCompile) {
     	options.encoding = 'UTF-8'
   	}
-    sourceCompatibility = "1.8"
-    targetCompatibility = "1.8"
+
+    // To ensure that the Java Client continues to support Java 8, both source and target compatibility are set to 1.8.
+    // May adjust this for src/test/java so that tests can take advantage of more expressive functions in Java 9+, such
+    // as Map.of().
+    java {
+        sourceCompatibility = 1.8
+        targetCompatibility = 1.8
+    }
 
     configurations {
         testImplementation.extendsFrom compileOnly
@@ -45,4 +51,11 @@ subprojects {
         systemProperty "javax.xml.stream.XMLOutputFactory", "com.sun.xml.internal.stream.XMLOutputFactoryImpl"
     }
 
+    // Until we do a cleanup of javadoc errors, the build (and specifically the javadoc task) fails on Java 11
+    // and higher. Preventing that until the cleanup can occur.
+    javadoc.failOnError = false
+
+    // Ignores warnings on param tags with no descriptions. Will remove this once javadoc errors are addressed.
+    // Until then, it's just a lot of noise.
+    javadoc.options.addStringOption('Xdoclint:none', '-quiet')
 }

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-6.9.2-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

marklogic-client-api/build.gradle

@@ -25,12 +25,15 @@ dependencies {
     implementation 'com.fasterxml.jackson.core:jackson-annotations:2.13.4'
     implementation 'com.fasterxml.jackson.core:jackson-databind:2.13.4.2'
     implementation 'com.fasterxml.jackson.dataformat:jackson-dataformat-csv:2.13.4'
+
     testImplementation 'com.fasterxml.jackson.dataformat:jackson-dataformat-xml:2.13.4'
-    testImplementation group: 'org.mockito', name: 'mockito-all', version:'1.10.19'
+    testImplementation "org.mockito:mockito-core:4.9.0"
+    testImplementation "org.mockito:mockito-inline:4.9.0"
     testImplementation group: 'ch.qos.logback', name: 'logback-classic', version:'1.2.11'
     testImplementation group: 'org.hsqldb', name: 'hsqldb', version:'2.5.1'
 // schema validation issue with testImplementation group: 'xerces', name: 'xercesImpl', version:'2.12.0'
     testImplementation group: 'org.opengis.cite.xerces', name: 'xercesImpl-xsd11', version:'2.12-beta-r1667115'
+
     compileOnly group: 'org.jdom', name: 'jdom2', version:'2.0.6'
     compileOnly group: 'dom4j', name: 'dom4j', version:'1.6.1'
     compileOnly group: 'com.google.code.gson', name: 'gson', version:'2.8.6'

ml-development-tools/build.gradle

@@ -19,6 +19,12 @@ dependencies {
     testImplementation 'com.squareup.okhttp3:okhttp:4.10.0'
 }
 
+// Added to avoid problem where processResources fails because - somehow - the plugin properties file is getting
+// copied twice. This started occurring with the upgrade of Gradle from 6.x to 7.x.
+tasks.processResources {
+    duplicatesStrategy = "exclude"
+}
+
 task mlDevelopmentToolsJar(type: Jar, dependsOn: classes) {
     archivesBaseName = 'ml-development-tools'
 }