From 57d6f9bf13fb2cea0f10e0489cfec0e3585813c0 Mon Sep 17 00:00:00 2001 From: Rob Rudin Date: Wed, 30 Nov 2022 10:21:07 -0500 Subject: [PATCH] Updated README to address how to use Java Client on Java 11 and 17 This addresses a gap in the docs where we've never explained how to include JAXB if a user is using Java 11 or 17 and wishes to use the JAXB support in the Java Client. Can also now build and run all the tests using Java 11 or 17 (we've only used Java 8 before). That simply required the following: - Don't fail the build on javadoc errors; Java 11 is much more particular about these, and we ought to do a cleanup of these errors soon, but we can ignore them for now - Bumped up Gradle wrapper version to the latest 7.x; to build and run on Java 17, need at least Gradle 7.3 - Bumped up Mockito from the very, very old mockito-all dependency (last updated in 2015) to the latest ones; this fixed a simple problem with Mockito that popped up when testing with Java 11 and Java 17 - Added a duplicatesStrategy for ml-development-tools to address an issue where the plugin properties file was getting copied over twice; this occurred as a result of upgrading from Gradle 6 to 7. There is likely a better way to handle this, but this approach (which the error message recommends using) works for now. --- README.md | 46 +++++++++++++++++++++--- build.gradle | 17 +++++++-- gradle/wrapper/gradle-wrapper.properties | 2 +- marklogic-client-api/build.gradle | 5 ++- ml-development-tools/build.gradle | 6 ++++ 5 files changed, 68 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index dc4568d87..c1f05fb7e 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ 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: com.marklogic @@ -40,13 +40,51 @@ To use the API in your maven project, include the following in your pom.xml: 6.0.0 -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: + + + javax.xml.bind + jaxb-api + 2.3.1 + + + org.glassfish.jaxb + jaxb-runtime + 2.3.2 + + + org.glassfish.jaxb + jaxb-core + 2.3.0.1 + + +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 diff --git a/build.gradle b/build.gradle index 85391e7fc..4e23615f0 100644 --- a/build.gradle +++ b/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') } diff --git a/gradle/wrapper/gradle-wrapper.properties b/gradle/wrapper/gradle-wrapper.properties index ec991f9aa..ae04661ee 100644 --- a/gradle/wrapper/gradle-wrapper.properties +++ b/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 diff --git a/marklogic-client-api/build.gradle b/marklogic-client-api/build.gradle index fe0dec710..e35176f7f 100644 --- a/marklogic-client-api/build.gradle +++ b/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' diff --git a/ml-development-tools/build.gradle b/ml-development-tools/build.gradle index 034da3d43..951480a92 100644 --- a/ml-development-tools/build.gradle +++ b/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' }