////

    Copyright © 2019 Christian Kaltepoth
    Copyright © 2020 Copyright (c) 2020 Contributors to the Eclipse Foundation

    This program and the accompanying materials are made available under the
    terms of the Eclipse Public License v. 2.0, which is available at
    http://www.eclipse.org/legal/epl-2.0.

    This Source Code may also be made available under the following Secondary
    Licenses when the conditions for such availability set forth in the
    Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
    version 2 with the GNU Classpath Exception, which is available at
    https://www.gnu.org/software/classpath/license.html.

    SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0

////
[[running_sig_tests]]
== Running the signature tests

One of the requirements of an implementation passing the TCK is for it to pass the Jakarta MVC {mvc-spec-version} signature test.
This section describes how to run it against your implementation.

=== Obtaining the sigtest tool

To run the signature tests against an implementation, you will need the Sigtest tool.
You can download the latest version here:

https://download.java.net/sigtest/download.html

The process has been tested against `sigtest-3_0-dev-bin-b09-24_apr_2013.zip`.

Download the corresponding ZIP file and unpack it to some location:

[source,sh]
----
mkdir ${HOME}/sigtest && cd $_
wget http://download.java.net/sigtest/3.0/PreRel/sigtest-3_0-dev-bin-b09-24_apr_2013.zip
unzip sigtest-3_0-dev-bin-b09-24_apr_2013.zip
----

Now set the following environment variables:

`SIGTEST_HOME`::
  Directory of the just downloaded Sigtest tool.

`JAVA_HOME`::
  Location of the JDK you want to use for the test.

If you use the installation directory from the example above:

[source,sh]
----
export SIGTEST_HOME=${HOME}/sigtest/sigtest-3.0
export JAVA_HOME=/lib/jvm/java-1.8.0
----

NOTE: It is strongly recommended to use Java 8 for running the signature tests, because the Sigtest tool
doesn't work well with newer Java versions.

=== Preparing the environment

To run the signature tests, you will need obtain three files. To simplify the invocation of the Sigtest tool,
it is recommended to place all files in the same directory and to run the Sigtest from this directory:

[source,sh]
----
mkdir ${HOME}/sigtest/mvc/ && cd $_
----

First you will need to get the Java EE 8 API JAR. You can download this directly from Maven Central:

[source,sh]
----
wget https://repo1.maven.org/maven2/jakarta/platform/jakarta.jakartaee-api/9.0.0/jakarta.jakartaee-api-9.0.0.jar
----

Next, you will need the implementation JAR of the Jakarta MVC {mvc-spec-version} API.
In this example we will simply use the official API JAR.

[source,sh,subs="attributes"]
----
wget https://repo1.maven.org/maven2/jakarta/mvc/jakarta.mvc-api/{mvc-api-version}/jakarta.mvc-api-{mvc-api-version}.jar
----

Finally you will need the `.sigtest` definition file, which you can also get from Maven Central:

[source,sh,subs="attributes"]
----
wget https://repo1.maven.org/maven2/jakarta/mvc/tck/mvc-tck-sigtest/{tck-version}/mvc-tck-sigtest-{tck-version}.sigfile
----

Now you are ready to run the signature tests.

=== Running the signature test

[source,sh,subs="attributes"]
----
${JAVA_HOME}/bin/java -jar ${SIGTEST_HOME}/lib/sigtestdev.jar SignatureTest \
  -Classpath "${JAVA_HOME}/jre/lib/rt.jar:./jakarta.jakartaee-api-9.0.0.jar:./jakarta.mvc-api-{mvc-api-version}.jar" \
  -Package jakarta.mvc \
  -FileName ./mvc-tck-sigtest-{tck-version}.sigfile \
  -static
----

If the test is successful, you should see an output like this:

[subs="attributes"]
----
SignatureTest report
Base version: {tck-version}
Tested version:
Check mode: src [throws normalized]
Constant checking: on


STATUS:Passed.
----

=== Forcing a signature test failure

To verify that the signature test works correctly, you can modify the signature file:

[source,plain]
----
CLSS public abstract interface jakarta.mvc.Models
intf java.lang.Iterable<java.lang.String>
meth public abstract <%0 extends java.lang.Object> {%%0} get(java.lang.String,java.lang.Class<{%%0}>)
meth public abstract java.lang.Object get(java.lang.String)
meth public abstract java.util.Map<java.lang.String,java.lang.Object> asMap()
meth public abstract jakarta.mvc.Models put(java.lang.String,java.lang.Object)
----

You can for example delete the line containing the definition of the `get` method.
Now run the signature test again. The check should fail like this:

[subs="attributes"]
----
SignatureTest report
Base version: {tck-version}
Tested version:
Check mode: src [throws normalized]
Constant checking: on


Added Methods
-------------

jakarta.mvc.Models:   method public abstract java.lang.Object jakarta.mvc.Models.get(java.lang.String)


STATUS:Failed.1 errors
----