Userguide updates (#321)

* User guide updates * JSONP API version bump Signed-off-by: David Kral <david.k.kral@oracle.com>
jakartaee · Feb 24, 2022 · ad73dd3 · ad73dd3
1 parent c1d3b77
commit ad73dd3
Show file tree

Hide file tree

Showing 13 changed files with 225 additions and 1,797 deletions.
diff --git a/.github/workflows/maven.yml b/.github/workflows/maven.yml
@@ -42,10 +42,10 @@ jobs:
             ~/.m2
           key: build-${{ env.cache-name }}
       - name: API compilation
-        run: cd api && mvn clean install
+        run: cd api && mvn clean install -Pstaging
       - name: TCK test compilation
-        run: cd tck && mvn clean install
+        run: cd tck && mvn clean install -Pstaging
       - name: Javadoc compilation
-        run: cd docs && mvn clean install
+        run: cd docs && mvn clean install -Pstaging
       - name: Generating specification
-        run: cd spec && mvn clean install
+        run: cd spec && mvn clean install -Pstaging
diff --git a/api/pom.xml b/api/pom.xml
@@ -90,7 +90,7 @@
         <non.final>false</non.final>
         <skip.release.tests>false</skip.release.tests>
         <spec.version>3.0</spec.version>
-        <jakarta.json.version>2.0.1</jakarta.json.version>
+        <jakarta.json.version>2.1.0</jakarta.json.version>
         <!-- The version of JSON-B API to compare against to verify we follow semantic versioning rules -->
         <baseline.compare.version>2.0.0</baseline.compare.version>
         <api_package>jakarta.json.bind</api_package>

diff --git a/tck-docs/JSONB3.0-ReleaseNotes.html b/tck-docs/JSONB3.0-ReleaseNotes.html
@@ -17,7 +17,7 @@
 
 -->
 
-<html><head><title>Jakarta JSON Binding TCK, Version 3.0 Release Notes, December 2021</title>
+<html><head><title>Jakarta JSON Binding TCK, Version 3.0 Release Notes, March 2022</title>
 
 <style type="text/css">
 <!--

diff --git a/tck-docs/assertions/JSONB10JavadocAssertions.html b/tck-docs/assertions/JSONB10JavadocAssertions.html
diff --git a/tck-docs/assertions/JSONB10SpecAssertions.html b/tck-docs/assertions/JSONB10SpecAssertions.html
diff --git a/tck-docs/index.html b/tck-docs/index.html
@@ -48,8 +48,8 @@ <h2>Guide to JSON-B TCK 3.0 Documentation</h2>
   <ul>
    <li><p>The <cite><a href="JSONB3.0-ReleaseNotes.html">JSON-B Release Notes</a></cite> provide the information that you need to install, set up, and run the JSON-B TCK, Version 3.0. The Release Notes are located in the TCK product bundle.</p></li>
 	<li><p>The <cite>JSON-B 3.0 Technology Compatibility Kit User's Guide</cite>  provides the information that you need to install, set up, and run the JSON-B TCK as well as the rules you must comply with for certification.</p></li>
-   <li><p>The <a href="assertions/JSONB10JavadocAssertions.html">Javadoc Assertion List</a> lists all the javadoc assertions that are tested by the JSON-B TCK.</p></li>
-   <li><p>The <a href="assertions/JSONB10SpecAssertions.html">Specification Assertion List</a> lists all the specification assertions that are tested by the JSON-B TCK.</p></li>
+   <li><p>The <a href="assertions/JSONBJavadocAssertions.html">Javadoc Assertion List</a> lists all the javadoc assertions that are tested by the JSON-B TCK.</p></li>
+   <li><p>The <a href="assertions/JSONBSpecAssertions.html">Specification Assertion List</a> lists all the specification assertions that are tested by the JSON-B TCK.</p></li>
  </ul>
 <hr>
 <p><cite><small><address>Copyright (c) 2017, 2022 Oracle and/or its affiliates. All rights reserved.</address></small><cite></p>

diff --git a/tck-docs/userguide/pom.xml b/tck-docs/userguide/pom.xml
@@ -22,7 +22,7 @@
     <parent>
         <groupId>org.eclipse.ee4j</groupId>
         <artifactId>project</artifactId>
-        <version>1.0.5</version>
+        <version>1.0.7</version>
     </parent>
     <groupId>jakarta.json.bind</groupId>
     <artifactId>jakarta.json.bind-tck-ug</artifactId>
@@ -101,7 +101,7 @@
                         </goals>
                         <configuration>
                             <chapterPatterns>
-                                [0-9]+\s.*,Preface.*,Part\s.*
+                                [A-C0-9]+\s.*,Preface.*,Part\s.*
                             </chapterPatterns>
                         </configuration>
                     </execution>

diff --git a/tck-docs/userguide/src/main/jbake/content/attributes.conf b/tck-docs/userguide/src/main/jbake/content/attributes.conf
@@ -24,12 +24,15 @@
 // Java SE version required.
 :SEversion: 11+
 :MavenVersion: 3.6.3+
+:JunitVersion: 5.7.2+
 :JakartaEEVersion: 10
 :excludeListFileName: TCK-Exclude-List.txt
 :TCKPackageName: jakarta-jsonb-tck-3.0.0.zip
 // Directory names used in examples in using.adoc.
-:sigTestDirectoryExample: jakarta.json.bind.tck.signaturetest.jsonb
-:singleTestDirectoryExample: jakarta.json.bind.tck.api.annotation
-:subsetTestDirectoryExample: jakarta.json.bind.tck.api
+:sigTestDirectoryExample: ee.jakarta.tck.json.bind.signaturetest.jsonb
+:singleTestDirectoryExample: ee.jakarta.tck.json.bind.api.annotation
+:subsetTestDirectoryExample: ee.jakarta.tck.json.bind.api
+:singleTestExample: ee.jakarta.tck.json.bind.api.jsonb.JsonbTest
+:sigTestExample: ee.jakarta.tck.json.bind.signaturetest.jsonb.JSONBSigTest
 // Define this attribute (uncomment it) if the TCK needs the rebuild appendix.
 // :rebuild:
diff --git a/tck-docs/userguide/src/main/jbake/content/config.inc b/tck-docs/userguide/src/main/jbake/content/config.inc
@@ -44,9 +44,81 @@ slashes as a path separator instead.
   d.  `PATH` to include the following directories: `JAVA_HOME/bin`,
   and `M2_HOME/bin`
 
-[[GCLHU]][[configuring-your-environment-to-repackage-and-run-the-tck-against-the-vendor-implementation]]
-
-4.2 Configuring Your Environment to Repackage and Run the TCK Against the Vendor Implementation
+2.  Set below Maven/System properties
+  a. `jimage.dir` This property specifies the directory where Java 11+ modules will be expanded by the
+  jimage tool for use in sigTestClasspath
+  b. `sigTestClasspath` This property must be set when running signature tests.
+  This property should be set to a list of jar files and/or directories which contain your
+  Jakarta EE and Java SE classes. Paths must be separated by the appropriate path separator (';' windows, ':' Unixes).
+
+3.  Set the below jars to the classpath
+  a. JAR file for the {TechnologyShortName} {TechnologyVersion} CI. +
+  `jakarta.json.bind-api.jar`.
+  b. JUnit 5 jars ({JunitVersion})
+  c. sigtest-maven-plugin (1.4) to run the signature tests.
+  d. {TechnologyShortName} TCK tests (`jakarta.json.bind:jakarta.json.bind-tck`)
+
++
+.Example: Maven configuration
+[source,oac_no_warn,xml]
+----
+    <dependencies>
+        <dependency>
+          <groupId>CI.group.id</groupId>
+          <artifactId>CI.artifact.id</artifactId>
+          <version>CI.version</version>
+          <scope>test</scope>
+        </dependency>
+        <dependency>
+          <groupId>jakarta.json.bind</groupId>
+          <artifactId>jakarta.json.bind-api</artifactId>
+          <version>3.0.0</version>
+          <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.json</groupId>
+            <artifactId>jakarta.json-api</artifactId>
+            <version>2.1.0</version>
+            <scope>provided</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.jboss.weld.se</groupId>
+            <artifactId>weld-se-core</artifactId>
+            <version>4.0.2.Final</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.json.bind</groupId>
+            <artifactId>jakarta.json.bind-tck</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+    ----
+    <plugins>
+        <plugin>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <version>3.0.0-M5</version>
+            <configuration>
+                <trimStackTrace>false</trimStackTrace>
+                <failIfNoTests>true</failIfNoTests>
+                <dependenciesToScan>jakarta.json.bind:jakarta.json.bind-tck</dependenciesToScan>
+                <systemPropertyVariables>
+                    <!-- Needed for signature tests to pass -->
+                    <jimage.dir>${project.build.directory}/jdk-bundles</jimage.dir>
+                    <signature.sigTestClasspath>
+                        ${project.build.directory}/signaturedirectory/jakarta.json.bind-api.jar:
+                        ${jimage.dir}/java.base:${jimage.dir}/java.rmi:${jimage.dir}/java.sql:${jimage.dir}/java.naming
+                    </signature.sigTestClasspath>
+                </systemPropertyVariables>
+            </configuration>
+        </plugin>
+    </plugins>
+----
++
+
+[[GCLHU]][[configuring-your-environment-run-the-tck-against-the-vendor-implementation]]
+
+4.2 Configuring Your Environment to Run the TCK Against the Vendor Implementation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 After configuring your environment as described in this section,
@@ -72,13 +144,85 @@ slashes as a path separator instead.
 
 
 1.  Set the following environment variables in your shell environment:
-  a.  `JAVA_HOME` to the directory in which Java SE 8 or Java SE 11 is installed
+  a.  `JAVA_HOME` to the directory in which Java SE {SEversion} is installed
   b.  `M2_HOME` to the directory in which the Apache Maven build tool is installed.
   c.  +{TechnologyHomeEnv}+ to the directory in which the {TechnologyShortName}
   {TechnologyVersion} CI has been installed
   d.  `PATH` to include the following directories: `JAVA_HOME/bin`,
   and `M2_HOME/bin`
 
+2.  Set below Maven/System properties
+  a. `jimage.dir` This property specifies the directory where Java 11+ modules will be expanded by the
+  jimage tool for use in sigTestClasspath
+  b. `sigTestClasspath` This property must be set when running signature tests.
+  This property should be set to a list of jar files and/or directories which contain your
+  Java EE and Java SE classes. Paths must be separated by the appropriate path separator (';' windows, ':' Unixes).
+
+3.  Set the below jars to the classpath
+  a. JAR file for the {TechnologyShortName} {TechnologyVersion} VI. +
+  `yasson.jar`.
+  b. JUnit 5 jars ({JunitVersion})
+  c. sigtest-maven-plugin (1.4) to run the signature tests.
+  d. {TechnologyShortName} TCK tests (`jakarta.json.bind:jakarta.json.bind-tck`)
+
++
+.Example: Maven configuration
+[source,oac_no_warn,xml]
+----
+    <dependencies>
+        <dependency>
+          <groupId>VI.grou.id</groupId>
+          <artifactId>VI.artefact.id</artifactId>
+          <version>VI.version</version>
+          <scope>test</scope>
+        </dependency>
+        <dependency>
+          <groupId>org.eclipse</groupId>
+          <artifactId>yasson</artifactId>
+          <version>3.0.0-R1</version>
+          <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.json</groupId>
+            <artifactId>jakarta.json-api</artifactId>
+            <version>2.1.0</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>org.jboss.weld.se</groupId>
+            <artifactId>weld-se-core</artifactId>
+            <version>4.0.2.Final</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>jakarta.json.bind</groupId>
+            <artifactId>jakarta.json.bind-tck</artifactId>
+            <scope>test</scope>
+        </dependency>
+    </dependencies>
+    ----
+    <plugins>
+        <plugin>
+            <artifactId>maven-surefire-plugin</artifactId>
+            <version>3.0.0-M5</version>
+            <configuration>
+                <trimStackTrace>false</trimStackTrace>
+                <failIfNoTests>true</failIfNoTests>
+                <dependenciesToScan>jakarta.json.bind:jakarta.json.bind-tck</dependenciesToScan>
+                <systemPropertyVariables>
+                    <!-- Needed for signature tests to pass -->
+                    <jimage.dir>${project.build.directory}/jdk-bundles</jimage.dir>
+                    <signature.sigTestClasspath>
+                        ${project.build.directory}/signaturedirectory/jakarta.json.bind-api.jar:
+                        ${jimage.dir}/java.base:${jimage.dir}/java.rmi:${jimage.dir}/java.sql:${jimage.dir}/java.naming
+                    </signature.sigTestClasspath>
+                </systemPropertyVariables>
+            </configuration>
+        </plugin>
+    </plugins>
+
+----
++
 
 [[GHGDG]][[publishing-the-test-applications]]
 

diff --git a/tck-docs/userguide/src/main/jbake/content/intro.adoc b/tck-docs/userguide/src/main/jbake/content/intro.adoc
@@ -290,13 +290,17 @@ steps are explained in more detail in subsequent chapters of this
 guide.
 
 1.  Make sure that the following software has been correctly installed
-on the system hosting the JavaTest harness:
+on the system:
++
+--
 include::req-software.inc[]
 * Java SE {SEversion}
 * A CI for {TechnologyShortName} {TechnologyVersion}. One example is {TechnologyRI}.
 * {TechnologyShortName} TCK version {TechnologyVersion}, which includes:
 include::tck-packages.inc[]
 * The {TechnologyShortName} {TechnologyVersion} Vendor Implementation (VI) +
+* Any Jupiter API compatible test runner
+--
 See the documentation for each of these software applications for
 installation instructions. See link:install.html#GBFTP[Chapter 3,
 "Installation,"] for instructions on installing the {TechnologyShortName} TCK.

diff --git a/tck-docs/userguide/src/main/jbake/content/toc.adoc b/tck-docs/userguide/src/main/jbake/content/toc.adoc
@@ -68,9 +68,11 @@ link:using.html#GBFWO[5 Executing Tests]
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ** link:using.html#GBFUZ[5.1 Starting the tests]
-*** link:using.html#GBFVW[5.1.1 To Start the tests in Command-Line Mode]
+*** link:using.html#GBFVW[5.1.1 To Run All Tests]
 ** link:using.html#GBFWM[5.2 Running a Subset of the Tests]
-*** link:using.html#GBFWK[5.2.1 To Run a Subset of Tests in Command-Line Mode]
+*** link:using.html#GBFWK[5.2.1 To Run a Single Test]
+*** link:using.html#GCMCA[5.2.2 To Run a Subset of Tests]
+*** link:using.html#GCMCU[5.2.3 To Run Signature Tests]
 ** link:using.html#GCLRR[5.3 Running the TCK Against another CI]
 ** link:using.html#GCLRZ[5.4 Running the TCK Against a Vendor's Implementation]
 ** link:using.html#GBFVK[5.5 Test Reports]
@@ -81,7 +83,11 @@ link:debug.html#GBFUV[6 Debugging Test Problems]
 
 ** link:debug.html#GBFYP[6.1 Overview]
 ** link:debug.html#GBFYF[6.2 Configuration Failures]
-* link:faq.html#GBFYD[A Frequently Asked Questions]
+
+[[a-frequently-asked-questions]]
+link:faq.html#GBFYD[A Frequently Asked Questions]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 ** link:faq.html#GBFYQ[A.1 Where do I start to debug a test failure?]
 ** link:faq.html#GBFYR[A.2 How do I restart a crashed test run?]
 ** link:faq.html#GBFWU[A.3 What would cause tests be added to the exclude list?]