Merge pull request #523 from KyleAure/510-signature-test-plugin-update

Update signature test plugin to jakarta.tck varient

tck-dist/src/main/asciidoc/concurrency-tck-reference-guide.adoc

@@ -14,8 +14,8 @@
 :APIGitSite: https://github.com/jakartaee/concurrency
 
 :TCKTestPlatform: Junit5
-:SigPluginVersion: 1.6
-:SigPluginGAV: org.netbeans.tools:sigtest-maven-plugin:{SigPluginVersion}
+:SigPluginVersion: 2.3
+:SigPluginGAV: jakarta.tck:sigtest-maven-plugin:{SigPluginVersion}
 
 :JavaVersion1: 17
 :JavaVersion2: 21
@@ -268,7 +268,7 @@ The TCK uses external libraries that also need to be available on the Applicatio
 
 - org.apache.derby:derby - For database testing
 - org.junit.jupiter:junit-jupiter - For test assertions
-- org.netbeans.tools:sigtest-maven-plugin - For signature testing
+- jakarta.tck:sigtest-maven-plugin - For signature testing
 
 See <<Test Server Dependencies>>
 
@@ -330,6 +330,21 @@ Example META-INF/services/org.jboss.arquillian.core.spi.LoadableExtension:
 my.custom.test.package.MyLoadableExtension
 ----
 
+=== Test property reference
+
+In the previous sections, there were sample configurations that contained information about
+the different system properties that can be set under the `<systemPropertyVariables>` of the Surefire plugin. 
+
+This section contains a complete list of the system properties that will be looked up by the TCK
+and a short description of what data each represents. 
+
+Use this reference as a quick guide for customizing how this TCK is run for your implementation.
+
+include::generated/test-properties.adoc[]
+
+Note: All non-java properties set on the test client will be exported to the test server, so there is no
+need to set the same properties on both.
+
 == Running the TCK
 
 Once the TCK Runner project is created and configured the {APIShortName} TCK is run as part of the maven test lifecycle. 
@@ -356,13 +371,10 @@ The signature tests validate the integrity of the `jakarta.enterprise.concurrent
 The {APIShortName} TCK will run signature tests on the application server itself, and not as part of a separate plugin / execution.
 This means that the signature tests will run during the maven `test` phase.
 
-You need to configure your application server with a JVM property `-Djimage.dir=<path-your-server-has-access-to>`.
-This is because, when running the signature tests on JDK 9+ we need to convert the JDK modules back into class files for signature testing.
-
 The signature test plugin we use will also attempt to perform reflective access of classes, methods, and fields.
 Due to the new module system in JDK 9+ special permissions need to be added in order for these tests to run: 
 
-If you are using a Security Manager add the following permissions to the `sigtest-maven-plugin` on your application server:
+If you are using a Security Manager add the following permissions to applications running on your application server:
 
 [source, txt]
 ----
@@ -373,7 +385,7 @@ permission java.lang.RuntimePermission "accessClassInPackage.jdk.internal.vm.ann
 
 By default the java.base module only exposes certain classes for reflective access. 
 Therefore, the {APIShortName} TCK test will need access to the `jdk.internal.vm.annotation` class.
-To give the `sigtest-maven-plugin` access to this class set the following JVM properties: 
+To give the TCK access to this class set the following JVM properties: 
 
 [source, properties]
 ----

tck-dist/src/main/java/ee/jakarta/tck/data/metadata/CollectMetaData.java

@@ -36,6 +36,7 @@
 import org.junit.platform.commons.support.AnnotationSupport;
 import org.junit.platform.commons.support.HierarchyTraversalMode;
 
+import ee.jakarta.tck.concurrent.framework.TestProperty;
 import ee.jakarta.tck.concurrent.framework.junit.anno.Assertion;
 import ee.jakarta.tck.concurrent.framework.junit.anno.Challenge;
 
@@ -111,6 +112,7 @@ public static void main(final String[] args) throws Exception {
         writeSigOutput(new File(adocGeneratedLocation, SIG_OUTPUT_FILE));
         writeOutput(testMetaData, new File(adocGeneratedLocation, EXPECTED_OUTPUT_FILE));
         writeGitIgnore(new File(adocGeneratedLocation, ".gitignore"), RUNTIME_TESTS_FILE, CHALLENGED_TESTS_FILE, SIG_OUTPUT_FILE, EXPECTED_OUTPUT_FILE, TEST_PROPERTIES_FILE);
+        writeTestProperties(new File(adocGeneratedLocation, TEST_PROPERTIES_FILE));
 
         for (TestMetaData data: testMetaData) {
             debug(data.debugString());
@@ -327,6 +329,36 @@ private static Object[] getTestCounts(final List<TestMetaData> testMetaData) {
         return results.toArray();
     }
 
+    /**
+     * Compiles a list of all system properties used by the TCK output to the generated adoc folder.
+     *
+     * @param outputLocation - the output file
+     * @throws IOException   - exception if we cannot write to this location
+     */
+    private static void writeTestProperties(final File outputLocation) throws IOException {
+        String output =
+                """
+                |===
+                |Key  |Required  |Description
+                $properties
+                |===""".replaceAll("\\$properties", getTestProperties());
+        try (BufferedWriter writer = new BufferedWriter(new FileWriter(outputLocation))) {
+            writer.write(output.trim() + System.lineSeparator());
+        }
+    }
+
+    private static String getTestProperties() {
+        String output = "";
+        for (TestProperty property : TestProperty.values()) {
+            output +=
+                    """
+                    
+                    |%s |%s |%s
+                    """.formatted(property.getKey(), property.isRequired(), property.getDescription());
+        }
+        return output;
+    }
+
     /**
      * Inspects each class for methods and annotations and constructs a metadata object.
      * Collects all metadata objects and returns them as a list.

tck-dist/src/main/starter/pom.xml

@@ -112,7 +112,7 @@
         </dependency>
         <!-- Signature Test Plugin -->
         <dependency>
-            <groupId>org.netbeans.tools</groupId>
+            <groupId>jakarta.tck</groupId>
             <artifactId>sigtest-maven-plugin</artifactId>
             <version>${sigtest.version}</version>
         </dependency>
@@ -144,7 +144,7 @@
                             <version>${derby.version}</version>
                         </artifactItem>
                         <artifactItem>
-                            <groupId>org.netbeans.tools</groupId>
+                            <groupId>jakarta.tck</groupId>
                             <artifactId>sigtest-maven-plugin</artifactId>
                             <version>${sigtest.version}</version>
                         </artifactItem>
@@ -171,6 +171,9 @@
                 <version>${maven.surefire.plugin.version}</version>
                 <configuration>
                     <systemPropertyVariables>
+                        <!-- tag::signature[] -->
+                        <jimage.dir>${jimage.dir}</jimage.dir>
+                        <!-- end::signature[] -->
                         <!-- tag::arquillian[] -->
                         <tck_server>[TODO]</tck_server>
                         <tck_port>[TODO]</tck_port>

tck/pom.xml

@@ -48,7 +48,7 @@
 
     <properties>
         <jakarta.concurrent.api.version>${project.version}</jakarta.concurrent.api.version>
-        <sigtest.version>1.6</sigtest.version>
+        <sigtest.version>2.3</sigtest.version>
         <shrinkwrap.resolver.version>3.3.0</shrinkwrap.resolver.version>
     </properties>
 
@@ -92,7 +92,7 @@
         </dependency>
 
         <dependency>
-            <groupId>org.netbeans.tools</groupId>
+            <groupId>jakarta.tck</groupId>
             <artifactId>sigtest-maven-plugin</artifactId>
             <version>${sigtest.version}</version>
         </dependency>
@@ -267,7 +267,7 @@
 
                     <!-- Run signature plugin to generate signature file -->
                     <plugin>
-                        <groupId>org.netbeans.tools</groupId>
+                        <groupId>jakarta.tck</groupId>
                         <artifactId>sigtest-maven-plugin</artifactId>
                         <version>${sigtest.version}</version>
                         <executions>

tck/src/main/java/ee/jakarta/tck/concurrent/common/signature/ApiCheckDriver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022 Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024 Oracle and/or its affiliates. All rights reserved.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0, which is available at
@@ -27,10 +27,12 @@
 import java.lang.reflect.Method;
 import java.util.LinkedList;
 import java.util.List;
+import java.util.logging.Logger;
 
 public final class ApiCheckDriver extends SignatureTestDriver implements Serializable {
-
     private static final long serialVersionUID = 1L;
+
+    private static final Logger log = Logger.getLogger(ApiCheckDriver.class.getCanonicalName());
 
     /* flags for the Diff utility argument list */
     private static final String BASE_FLAG = "-base";
@@ -60,22 +62,14 @@ protected String[] createTestArguments(final String packageListFile, final Strin
             final boolean bStaticMode) throws Exception {
 
         Class<?> pkgListClass = Class.forName("javasoft.sqe.apiCheck.PackageList");
-        Constructor<?> pkgCtor = pkgListClass.getDeclaredConstructor(new Class[] {
-                String.class
-                });
-        Object pkgInstance = pkgCtor.newInstance(new Object[] {
-                packageListFile
-                });
+        Constructor<?> pkgCtor = pkgListClass.getDeclaredConstructor(new Class[] {String.class});
+        Object pkgInstance = pkgCtor.newInstance(new Object[] {packageListFile});
 
-        Method pkgMethod = pkgListClass.getDeclaredMethod("getSubPackagesFormatted", new Class[] {
-                String.class
-                });
+        Method pkgMethod = pkgListClass.getDeclaredMethod("getSubPackagesFormatted", new Class[] {String.class});
 
-        String excludePkgs = (String) pkgMethod.invoke(pkgInstance, new Object[] {
-                packageOrClassUnderTest
-                });
+        String excludePkgs = (String) pkgMethod.invoke(pkgInstance, new Object[] {packageOrClassUnderTest});
 
-        List<String> sigArgsList = new LinkedList<>();
+        List<String> sigArgsList = new LinkedList<String>();
 
         sigArgsList.add(BASE_FLAG);
         sigArgsList.add(getSigFileInfo(packageOrClassUnderTest, mapFile, signatureRepositoryDir).getFile());
@@ -103,12 +97,8 @@ protected String[] createTestArguments(final String packageListFile, final Strin
     protected boolean runSignatureTest(final String packageOrClassName, final String[] testArguments) throws Exception {
 
         Class<?> diffClass = Class.forName("javasoft.sqe.apiCheck.Diff");
-        Method mainMethod = diffClass.getDeclaredMethod("main", new Class[] {
-                String[].class
-                });
-        mainMethod.invoke(null, new Object[] {
-                testArguments
-                });
+        Method mainMethod = diffClass.getDeclaredMethod("main", new Class[] {String[].class});
+        mainMethod.invoke(null, new Object[] {testArguments});
 
         Method diffMethod = diffClass.getDeclaredMethod("diffsFound", new Class[] {});
         return (!((Boolean) diffMethod.invoke(null, new Object[] {})).booleanValue());
@@ -118,7 +108,7 @@ protected boolean runSignatureTest(final String packageOrClassName, final String
     @Override
     protected boolean runPackageSearch(final String packageOrClassName, final String[] testArguments) throws Exception {
         Class<?> sigTestClass = Class.forName("com.sun.tdk.signaturetest.SignatureTest");
-        Object sigTestInstance = sigTestClass.getConstructor().newInstance();
+        Object sigTestInstance = sigTestClass.getDeclaredConstructor().newInstance();
 
         ByteArrayOutputStream output = new ByteArrayOutputStream();
 
@@ -130,33 +120,22 @@ protected boolean runPackageSearch(final String packageOrClassName, final String
         }
 
         // dump args for debugging aid
-        System.out.println("\nCalling:  com.sun.tdk.signaturetest.SignatureTest() with following args:");
+        log.fine("\nCalling:  com.sun.tdk.signaturetest.SignatureTest() with following args:");
         for (int ii = 0; ii < testArguments.length; ii++) {
-            System.out.println("\t  testArguments[" + ii + "] = " + testArguments[ii]);
+            log.fine("\t  testArguments[" + ii + "] = " + testArguments[ii]);
         }
 
         Method runMethod = sigTestClass.getDeclaredMethod("run",
-                new Class[] {
-                        String[].class, PrintWriter.class, PrintWriter.class
-                        });
-        runMethod.invoke(sigTestInstance, new Object[] {
-                testArguments, new PrintWriter(output, true), null
-                });
+                new Class[] {String[].class, PrintWriter.class, PrintWriter.class});
+        runMethod.invoke(sigTestInstance, new Object[] {testArguments, new PrintWriter(output, true), null});
 
         String rawMessages = output.toString();
 
         // currently, there is no way to determine if there are error msgs in
         // the rawmessages, so we will always dump this and call it a status.
-        System.out.println("********** Status Report '" + packageOrClassName + "' **********\n");
-        System.out.println(rawMessages);
+        log.info("********** Status Report '" + packageOrClassName + "' **********\n");
+        log.info(rawMessages);
         return sigTestInstance.toString().substring(7).startsWith("Passed.");
     }
 
-    @Override
-    protected boolean verifyJTAJarForNoXA(final String classpath, final String repositoryDir) throws Exception {
-        // Need to find out whether implementing this method is really required now.
-        // By default, signature test framework will use sigtest
-        return true;
-    }
-
 } // END ApiCheckDriver