Setup and Configuration

## 4 Setup and Configuration

Note | The Jakarta EE Specification process provides for any number of compatible implementations. As additional implementations become available, refer to project or product documentation from those vendors for specific TCK setup and operational guidance.

This chapter describes how to set up the Security TCK. Before proceeding with the instructions in this chapter, be sure to install all required software, as described in Chapter 3, "Installation."

After completing the instructions in this chapter, proceed to Chapter 5, "Executing Tests," for instructions on running the Security TCK.

### 4.1 Configuring Your Environment to Run the TCK Against the Compatible Implementation

After configuring your environment as described in this section, continue with the instructions in Section 4.6, "Using the JavaTest Harness Software."

Note | In these instructions, variables in angle brackets need to be expanded for each platform. For example, `<TS_HOME>` becomes `$TS_HOME` on Solaris/Linux and `%TS_HOME%` on Windows. In addition, the forward slashes (`/`) used in all of the examples need to be replaced with backslashes (`\`) for Windows. Finally, be sure to use the appropriate separator for your operating system when specifying multiple path entries (`;` on Windows, `:` on UNIX/Linux). On Windows, you must escape any backslashes with an extra backslash in path separators used in any of the following properties, or use forward slashes as a path separator instead.

1. Set the following environment variables in your shell environment:

   1. `JAVA_HOME` to the directory in which Java SE 17 is installed

   2. `TS_HOME` to the directory in which the Security TCK 4.0 software is installed

   3. `PATH` to include the following directories: `JAVA_HOME/bin`, `SOTERIA_HOME/bin`, `ANT_HOME/bin` and `M2_HOME/bin`

2. Copy <TS_HOME>/bin/ts.jte.standalone as <TS_HOME>/bin/ts.jte if TCK is run in standalone mode. Edit your `<TS_HOME>/bin/ts.jte` file and set the following environment variables:

   1. Set `securityapi.classes` to include all necessary JAR files that pertain to your implementation.

   2. Set `web.home` to the location where the securityapi is implemented. For example, If you are using Eclipse GlassFish 7.0 as your CI, set `web.home=<GLASSFISH_HOME_FOLDER`>.

   3. Set `jdbc.lib.class.path` to the location where the JDBC drivers are installed.

   4. Set `jdbc.db` to the name of the database under test. Valid values include:

          derby
          mysql
          oracle

   5. Set `sigTestClasspath` to include any additional classes not specified with the `securityapi.classes` property.

   6. Set `work.dir` to the default directory in which JavaTest writes temporary files that are created during test execution. The default location is <TS_HOME>/tmp/JTwork.
      This property is required for the TCK Ant targets.

   7. Set `report.dir` to the default directory in which JavaTest creates a test report for the most recent test run. The default location is <TS_HOME>/tmp/JTreport.
      This property is a required property for the TCK Ant targets; it must be set. To disable reporting, set the `report.dir` property to `"none"`.

   8. If you are testing against the default UnboundID LDAP server that is bundled with the TCK (recommended), make sure the following properties are set:
      `ldap.server=unboundid`
      `ldap.install.server=true`
      `ldap.ldif.file=${ts.home}/bin/ldap.ldif`
      If you are testing against a different LDAP server, then set the following property:
      `ldap.install.server=false`
      For a non-default LDAP, you must manually install the server on the local machine, and configure it to listen on port 11389. You will also need to load the test data by importing the file `<TS_HOME>/bin/ldap.ldif`.

3. Start the database under test.

4. Ensure that no process is using port 11389. If you are not using the default LDAP server, start the LDAP server under test.

5. Initialize the Vendor Implementation (server, database, and LDAP).
   Change to the `<TS_HOME>/bin` directory and execute the following command.

       ant config.vi
       ant init.ldap

6. Deploy all the server packages for testing. To do so, execute the following command:

       ant deploy.all

### 4.2 Configuring Your Environment to Repackage and Run the TCK Against the Vendor Implementation

After configuring your environment as described in this section, continue with the instructions in Section 4.4, "Using the JavaTest Harness Software."

Note | In these instructions, variables in angle brackets need to be expanded for each platform. For example, `<JAVA_HOME>` becomes `$JAVA_HOME` on Solaris/Linux and `%JAVA_HOME%` on Windows. In addition, the forward slashes (`/`) used in all of the examples need to be replaced with backslashes (`\`) for Windows. Finally, be sure to use the appropriate separator for your operating system when specifying multiple path entries (`;` on Windows, `:` on UNIX/Linux). On Windows, you must escape any backslashes with an extra backslash in path separators used in any of the following properties, or use forward slashes as a path separator instead.

#### Before You Begin

Decide against which Security implementation the tests will be run and determine to which Servlet–compliant Web server the Security TCK applications will be published.

Adapt the above instructions for the vendor implementation.

### 4.4 Custom Configuration Handlers

Configuration handlers are used to configure and unconfigure a Security 4.0 implementation during the certification process. These are similar to deployment handlers but used for configuration. A configuration handler is an Ant build file that contains at least the required targets listed below:

- `config.vi` - to configure the vendor implementation

- `clean.vi` - to unconfigure the vendor implementation

These targets are called from the `<TS_HOME>/bin/build.xml` file and call down into the implementation-specific configuration handlers.

To provide your own configuration handler, create a config.vi.xml file with the necessary configuration steps for your implementation and place the file under the `<TS_HOME>/bin/xml/impl/<your_impl>` directory.

For more information, you may wish to view `<TS_HOME>/bin/xml/impl/glassfish/config.vi.xml`, the configuration file for Jakarta EE 11.0 Compatible Implementation, Eclipse GlassFish.

### 4.5 Custom Deployment Handlers

Deployment handlers are used to deploy and undeploy the WAR files that contain the tests to be run during the certification process. A deployment handler is an Ant build file that contains at least the required targets listed in the table below.

The Security TCK provides these deployment handlers:

- `<TS_HOME>/bin/xml/impl/none/deploy.xml`

- `<TS_HOME>/bin/xml/impl/glassfish/deploy.xml`

- `<TS_HOME>/bin/xml/impl/tomcat/deploy.xml`

The `deploy.xml` files in each of these directories are used to control deployment to a specific container (no deployment, deployment to the Eclipse GlassFish Web container, deployment to the Tomcat Web container) denoted by the name of the directory in which each `deploy.xml` file resides. The primary `build.xml` file in the `<TS_HOME>/bin` directory has a target to invoke any of the required targets (`-deploy`, `-undeploy`, `-deploy.all`, `-undeploy.all`).

#### 4.5.1 To Create a Custom Deployment Handler

To deploy tests to another Security implementation, you must create a custom handler.

1. Create a new directory in the `<TS_HOME>/bin/xml/impl` directory tree. For example, create the `<TS_HOME>/bin/xml/impl/my_deployment_handler` directory. Replace my_deployment_handler with the value of the impl.vi property that you set in Step 5 of the configuration procedure described in Section 4.2, "Configuring Your Environment to Repackage and Run the TCK Against the Vendor Implementation".

2. Copy the deploy.xml file from the `<TS_HOME>/bin/xml/impl/none` directory to the directory that you created.

3. Modify the required targets in the `deploy.xml` file. This is what the `deploy.xml` file for the "none" deployment handler looks like.

       <project name="No-op Deployment" default="deploy">
           <!-- No-op deployment target -->
           <target name="-deploy">
               <echo message="No deploy target implemented for this deliverable"/>
           </target>
           <target name="-undeploy">
               <echo message="No undeploy target implemented for this deliverable"/>
           </target>
           <target name="-deploy.all">
               <echo message="No deploy target implemented for this deliverable"/>
           </target>
           <target name="-undeploy.all">
               <echo message="No undeploy target implemented for this deliverable"/>
           </target>
       </project>

   Although this example just echoes messages, it does include the four required Ant targets (`-deploy`, `-undeploy`, `-deploy.all`, `-undeploy.all`) that your custom `deploy.xml` file must contain. With this as your starting point, look at the required targets in the `deploy.xml` files in the Tomcat and Eclipse Glassfish directories for guidance as you create the same targets for the Web container in which you will run your implementation of Security.

The following Ant targets can be called from anywhere under the `<TS_HOME>/src` directory:

- `deploy`

- `undeploy`

- `deploy.all`

- `undeploy.all`

The `deploy.all` and `undeploy.all` targets can also be called from the `<TS_HOME>/bin` directory.

Note | The targets in the `deploy.xml` file are never called directly. They are called indirectly by the targets listed above.

### 4.6 Using the JavaTest Harness Software

It is recommended to run the Security TCK test suite using the JavaTest harness software in JavaTest batch mode, from the command line in your shell environment; if using this method, please proceed directly to Chapter 5, "Executing Tests."

Copyright © 2017, 2022 Oracle and/or its affiliates. All rights reserved.