Newbie help needed getting setup to build SigTest + discussion about adding a exclude class by name option ...

Tue Jan 5 20:35:18 UTC 2021

Hi Victor,

Thank you for the response!

On 12/5/20 3:18 AM, victor.rudometov at oracle.com wrote:
> Hi Scott,
>
> Thank you for your interest in SigTest. Please find my answers below.
>
> On 12/3/20 08:03, Scott Marlow wrote:
>> Hi,
>>
>> I'm following the [1] guide to build locally but still have a few 
>> questions.  Is there a particular version of Apache Ant needed to 
>> build?  I downloaded 1.9.15 as that should work with Java 7 but am 
>> getting a build failure [2]:
>> `
>> src/com/sun/tdk/signaturetest/ant/ATest.java:165: error: cannot find 
>> symbol
>>     [javac]         if (classpath == null || classpath.isEmpty()) {
>
> [1] is outdated and needs to be refreshed.
>
> I'm using ant 1.10.8 (older ones should work as well) with the 
> following minimal parameters:
>
> ant -f build/build.xml -Djdk7.home=/ws/java/java8 
> -Djdk8.home=/ws/java/java8 -Djdk9.home=/ws/java/java11
>
> Please use Java 8 for jdk7.home. There's probably a way to still use 
> 7, I have not checked it.
>
> You can use Java 9 or higher for jdk9.home, but I would recommend Java 
> 11 or higher, since 11 is LTS.
>
> You can use 15 or 16 too as jdk8.home and jdk9.home if features like 
> records or sealed types are present in your implementation. Sigtest 
> supports them.
>

Thanks, this helped me to build correctly! :)

>
>> I would like to explore a few ideas with SigTest related to [3] for 
>> the Jakarta EE Platform TCK which heavily depends on SigTest for SPEC 
>> API signature testing. Basically, we have users that would like to 
>> run our TCK against newer versions of Java SE than we have tested 
>> against. These users like the idea of being able to run the TCKs 
>> against the very latest Java SE versions.  Since our (Jakarta EE 
>> Platform TCK) is basically a Java application, it would be very 
>> useful to be able to run our Jakarta EE Platform EE TCKs against any 
>> Java SE version that is greater than our base requirement (currently 
>> we only support Java SE 8 but are working on Java SE 11 now).
>>
>> One idea is to create a SigTest pull request for adding an exclude 
>> class option so that the java.lang.Object public methods/fields will 
>> be excluded from signature generation/testing.
>
> I guess the functionality that you need is already there. You can 
> specify what should be tested by using -Package and 
> -PackageWithoutSubpackages options.
>
> You can also filter out packages (with subpackages) or individual 
> classes using -Exclude option.

I tried excluding the `java` package during Setup which seemed to 
exclude most of the Java SE classes that I wanted to exclude from the 
generated signature, however then the `java` package classes are missing 
during the Test command.

Using Java 8, I did the following with a recent local SigTest build:

1.  cd /tmp
2.  wget 
https://repo1.maven.org/maven2/jakarta/persistence/jakarta.persistence-api/3.0.0/jakarta.persistence-api-3.0.0.jar
3.  export SIGTEST=~/SIGTEST_BUILD/release/lib/
4.  java -Xmx2g -jar $SIGTEST/sigtestdev.jar Setup -classpath 
jakarta.persistence-api-3.0.0.jar:$JAVA_HOME/jre/lib/rt.jar:$JAVA_HOME/jre/lib/jce.jar 
-filename /tmp/jakarta.persistence-api-3.0.0.sig -package jakarta 
-exclude java

"
Warning: the created signature file is not transitively-closed
The signature file contains the following subclasses or subinterfaces of 
excluded java.io.Serializable:
java.lang.Class, java.lang.String, java.lang.StackTraceElement, 
java.util.Calendar, java.util.Date, java.lang.Boolean, 
java.lang.Character, java.lang.Number, java.net.URL
...
"

On the Test command, I get then get failures :

5.  java -Xmx2g -jar $SIGTEST/sigtest.jar Test -Static -classpath 
jakarta.persistence-api-3.0.0.jar:$JAVA_HOME/jre/lib/rt.jar:$JAVA_HOME/jre/lib/jce.jar 
-filename /tmp/jakarta.persistence-api-3.0.0.sig -package jakarta

"
The following classes are required, but missing in the signature 
files:java.lang.Enum, java.lang.annotation.Repeatable, 
java.lang.annotation.Annotation, java.lang.annotation.Target, 
java.lang.annotation.Documented, java.lang.Object, 
java.lang.RuntimeException, java.lang.annotation.Retention
STATUS:Error.Required classes not found!
"

>
> If that is not flexible enough there is a possibility to create an 
> exclude plugin and set it via system property "exclude.plugin". Take a 
> look at com.sun.tdk.exclude.ExcludeList and -ExcludeSig option 
> allowing signature exclusions using regexps.

Thanks, I will try using the Exclude extension next via 
com.sun.tdk.exclude.ExcludeList.  That does seem to be different than 
excluding the Java SE runtime classes from the generated signature files.

I'm not really sure if the Exclude extension prevents the verification of:

1.  Jakarta EE SPEC API verification of super class (e.g. java.util.Map 
or java.lang.Object or some other Java SE runtime class that Jakarta EE 
SPEC API class "is a descendant of").

2.  Jakarta EE SPEC API class must have a Java SE runtime class 
reference (as part of a public field/method).

For example, if we are verifying that the super class of 
jakarta.persistence.Persistence 
(https://jakarta.ee/specifications/persistence/3.0/apidocs/jakarta.persistence/jakarta/persistence/persistence) 
class is java.lang.Object but find that the super class is some 
unexpected class like java.util.Map, the signature test must still fail.

Scott

>
>> Imo, this should be a general option that allows a set of classes to 
>> be excluded (perhaps with some regular expression matching) and also 
>> allowing the command line exclude option to be specified multiple 
>> times (for excluding multiple classes by name).
>>
>> At least that is one idea.  My preference is to do this work upstream 
>> first [4].  If there is no interest in the pull request being merged, 
>> the next option could be forking the SigTest code into the 
>> jakartaee-tck-tools [5] and making the change there. Either option 
>> would be easy figure out once we have appropriate changes.
>
> Contributions are very much welcome.
>
> This mailing list is the best place to discuss new needed things in 
> SigTest.
>
>
> Thanks.
>
> Victor.
>
>
>> One other possible issue or question is whether this exclude class 
>> option would be a safe option to add to the OpenJDK SigTest tool? 
>> More specifically, could OpenJDK implementors use such an exclude 
>> option to cheat the JDK signature tests?  I'm not sure how that would 
>> happen but if that is a concern, please do speak up about that, so we 
>> can just proceed to do fork of SigTest.
>>
>> From a timing perspective, this `exclude class` change is not 
>> required at this point in our planning but it would be very very nice 
>> to have!
>>
>> Scott
>>
>> [1] https://wiki.openjdk.java.net/display/CodeTools/How+to+build
>> [2] https://gist.github.com/scottmarlow/b48890c8c5365264a4e7ea5c44c0778c
>> [3] https://github.com/eclipse-ee4j/jakartaee-tck/issues/156
>> [4] http://hg.openjdk.java.net/code-tools/sigtest
>> [5] https://github.com/eclipse-ee4j/jakartaee-tck-tools
>>
>