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 XML Binding TCK and JavaTest harness software. 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 XML Binding TCK.

### 4.1 Configuring the XML Binding TCK

#### 4.1.1 TCK Configuration Concepts

XML Binding 4.0 comprises of a schema compiler and a schema generator. Both are types of compilers; the former maps from a schema to Java, and the latter maps from Java to schema. For the purposes of brevity in these instructions, the term compiler refers to both the schema compiler and the schema generator.

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

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

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

   2. `TS_HOME` to the directory in which the XML Binding TCK software is installed

   3. `JAXB_HOME` to the directory in which the XML Binding software is installed

   4. `PATH` to include the following directories: `$JAVA_HOME/bin` and `$ANT_HOME/bin`

2. Edit `$TS_HOME/testsuite.jtt` and modify `finder` settings to contain proper XML Binding TCK software installation directory path prefix

3. Choose XML Binding TCK software configuration file template to use:

   1. `$TS_HOME/lib/javasoft-multiJVM.jti` to run tests in multi JVM mode (this is the default configuration template)

   2. or `$TS_HOME/lib/javasoft-singleJVM.jti` to run tests in single JVM mode

4. Edit chosen file, for example `${TS_HOME}/lib/javasoft-multiJVM.jti`, and set environment variables and configuration properties.

   1. Set `TESTSUITE` environment variable to contain XML Binding TCK software installation directory.

   2. Set `WORKDIR` environment variable to contain XML Binding TCK software working directory. This directory will contain raw testing data and results.

   3. Set `jck.env.jaxb.classes.jaxbClasses` property to contain The Checker Framework library and all XML Binding libraries:

      - checker.jar

      - `JAXB_HOME`/mod/jakarta.activation-api.jar

      - `JAXB_HOME`/mod/jakarta.xml.bind-api.jar

      - `JAXB_HOME`/mod/jaxb-core.jar

      - `JAXB_HOME`/mod/jaxb-impl.jar

      - `JAXB_HOME`/mod/jaxb-jxc.jar

   4. Set `jck.env.jaxb.testExecute.cmdAsFile` property to contain Java SE 8 installation Directory.

   5. Set `jck.env.jaxb.testExecute.otherEnvVars` property to contain

      - `JAVA_HOME` variable with Java SE 8 installation directory,

      - `JAXB_HOME` variable with XML Binding installation directory,

   6. Set `jck.env.jaxb.schemagen.run.jxcCmd` property to contain proper schema generator script for your platform.

   7. Set `jck.env.jaxb.xsd_compiler.testCompile.xjcCmd` property to contain proper schema compiler script for your platform. This property can also affect which CI is used in tests.

   8. Set `jck.env.jaxb.xsd_compiler.skipValidationOptional` property to contain value `Yes`. XML validation is implemented from JAXP in XML Binding 4.0 Compatible Implementation. See Section, "Configuration Properties" for details.

Note: More info about JAXBContext loading in Discovery of JAXB implementation.

An example of modified `${TS_HOME}/lib/javasoft-multiJVM.jti` file:

    TESTSUITE=/workspace/XMLB-TCK-4.0
    WORKDIR=/workspace/XMLB-TCK-4.0/batch-multiJVM/work
    jck.concurrency.concurrency=1
    jck.env.description=multi jvm
    jck.env.envName=multi_jvm
    jck.env.jaxb.classes.jaxbClasses=/data/tck/tmp/checker.jar
      /data/tck/tmp/jaxb-ri/mod/jakarta.activation-api.jar
      /data/tck/tmp/jaxb-ri/mod/jakarta.xml.bind-api.jar
      /data/tck/tmp/jaxb-ri/mod/jaxb-core.jar
      /data/tck/tmp/jaxb-ri/mod/jaxb-impl.jar
      /data/tck/tmp/jaxb-ri/mod/jaxb-jxc.jar
    jck.env.jaxb.schemagen.run.jxcCmd=/bin/sh
      /workspace/XMLB-TCK-4.0/linux/bin/schemagen.sh
    jck.env.jaxb.schemagen.skipJ2XOptional=Yes
    jck.env.jaxb.testExecute.cmdAsFile=/opt/jdk11/bin/java
    jck.env.jaxb.testExecute.otherEnvVars=JAVA_HOME\=/opt/jdk11
      JAXB_HOME\=/workspace/jaxb-ri
    jck.env.jaxb.testExecute.otherOpts=
    jck.env.jaxb.xsd_compiler.defaultOperationMode=Yes
    jck.env.jaxb.xsd_compiler.skipValidationOptional=Yes
    jck.env.jaxb.xsd_compiler.testCompile.xjcCmd=/bin/sh
      /workspace/XMLB-TCK-4.0/linux/bin/xjc.sh
    jck.env.testPlatform.local=Yes
    jck.env.testPlatform.multiJVM=Yes
    jck.excludeList.latestAutoCheck=No
    jck.excludeList.latestAutoCheckInterval=7
    jck.excludeList.latestAutoCheckMode=everyXDays
    jck.excludeList.needExcludeList=No
    jck.keywords.keywords.mode=expr
    jck.keywords.needKeywords=No
    jck.priorStatus.needStatus=No
    jck.priorStatus.status=
    jck.tests.needTests=No
    jck.tests.tests=
    jck.tests.treeOrFile=tree
    jck.timeout.timeout=1

#### 4.1.2 XML Binding-Specific Configuration Settings

A number of properties in the JavaTest harness configuration file are generic and apply to most Java product TCK suites. This section describes configuration settings that are specific to the XML Binding TCK.

The XML Binding TCK 4.0 includes a special configuration properties used by the JavaTest harness to collect information from you about your test environment and to create the configuration used to run tests. The TCK configuration properties consists of the following types:

- Test Environment: the first type of the properties collects information about the test environment used to run the XML Binding TCK 4.0 (such as the type of environment and the type of agent used).

- Schema Compiler Questions: the second type of the properties collects information about how to compile the source schema on your platform.

  - XML Validation Tests: optional tests that must be run if schema validation is performed using a mechanism other than JAXP.

- Schema Generator Questions: the type section of the properties collects information about how to generate XML schema from Java sources on your platform.

- How Tests are Run: the last section of the properties collects information on how the tests are run (such as Keywords and the Exclude List).

#### 4.1.3 Configuration Properties

Following list describes the configuration properties and gives examples of relevant values to correctly configure the JavaTest harness to run the test suite.

#### Configuration Name

Property: jck.env.envName

Provide a short identifier that names the configuration you are creating.

This is a short string that identifies this particular configuration. Select a name that describes the configuration.

Example: `jaxb_win32`

The name must begin with a letter, followed by letters, digits, or an underscore, and must not contain a white space or punctuation characters.

#### Description

Property: jck.env.description

Provide a short description that identifies the configuration you are creating.

JavaTest uses this short description to provide more detail about the configuration, for example, in reports. This information might be useful to an auditor looking at the test run reports, and could include the version number of the product and the name of the tester.

Example: `John Smith x86 Eclipse Implementation of JAXB 4.0.0`

#### Execution Mode

Property: jck.env.testPlatform.multiJVM

Specify whether you want to run the tests in SingleJVM or MultiJVM mode. Depending on the selected mode, you can configure to run the compiler either from the command line, or via the Java Compiler API, or via a custom class accessed by the core reflection API.

Answer `MultiJVM Mode` if the JavaTest harness can directly start your product, for example, from a command line in an MSDOS window or UNIX shell; this is the required mode for the XML Binding TCK.

Typically, applications that do not support such actions run in point-and-click environments or in browsers. For example, the JavaTest harness cannot start a new instance of a Java virtual machine inside a browser.

If you answer MultiJVM Mode , then you need to answer additional interview questions to specify whether you plan to run the tests locally. In addition, you need to specify the details about the Java Virtual Machine in which the tests will run (the questions in the Runtime Other JVM section of this interview) and the details about the Java launcher.

#### Execute Locally

Property: jck.env.testPlatform.local

Will you run the TCK tests on the system that hosts the JavaTest harness?

If you plan to run the tests on the system on which you are running this interview, then the editor gathers configuration information directly from the system. For example, you will be able to browse the local file system to point to the required files.

#### Agent Type

Property: jck.env.jaxb.agent.agentType

The JavaTest Agent can be run in two modes: active and passive. Which mode do you wish to use?

Select the agent type you wish to use. If you want to use the passive agent, then additional properties must be provided to specify the passive agent host and default agent port.

#### Passive Host

Property: jck.env.jaxb.agent.agentPassiveHost

What is the of the host on which you run the tests?

This is the name of the system on which the passive agent runs and executes tests. The name of the system must be accessible from the system on which JavaTest runs. Since the JavaTest agent is passive, you can only change the machine you specify here by running this interview again and changing the name of the passive host.

#### Default Agent Port

Property: jck.env.jaxb.agent.useAgentPortDefault

Do you wish to use the default port for the JavaTest harness to contact the JavaTest Agent?

By default, the JavaTest harness communicates with a passive agent using port 1908. You must change only the default if you are running more than one passive agent on a system; this might be the case if you have set up batch runs.

If you answer `No`, then you will need to specify the default port number in the next interview question.

#### Passive Port

Property: jck.env.jaxb.agent.agentPassivePort

Which port does the JavaTest harness use to contact the JavaTest Agent?

Specify the port you want to use to communicate with the JavaTest agent.

#### Test Platform File Separator

Property: jck.env.jaxb.agent.fileSeparator

Which file separator character is used on the test platform?

Specify the appropriate file separator for your operating system.

For example, for Windows, use the back slash `\` character. For Solaris OS or Linux operation system, use the forward slash `/` character.

#### Test Platform Path Separator

Property: jck.env.jaxb.agent.pathSeparator

Which path separator character is used on the test platform?.

Specify the appropriate path separator for your operating system.

For example, on Windows systems, specify the `;` character, on Unix systems specify the `:` character. Other platforms may differ.

#### Agent Map File

Property: jck.env.jaxb.agent.mapArgs

Because JavaTest and the JavaTest agent run on different systems, values such as path names and variable names may differ on each system. For example, if a file is accessed over a network, it might be mounted as `H:\tests\lib` on the JavaTest system and as `F:\tests\lib` on the system running the JavaTest agent. The map file is used to associate values used on the JavaTest agent with those used by JavaTest. The map file is specified on the JavaTest agent, but the use of the map must be enabled here. For more information about map files, refer to the JavaTest User’s Guide or to the JavaTest online help.

#### Java Launcher

Property: jck.env.jaxb.testExecute.cmdAsFile

Enter the full path name of the Java launcher that runs the tests through the Java Compiler API interface.

This property is required only if `jck.env.testPlatform.multiJVM` property value has been set to `Yes`.

This is the command used on the reference system to invoke the `java` command.

Note | Use the `java` command in JDK (not JRE).

- On Solaris or Linux platforms, use expanded value of: `$JAVA_HOME/bin/java`

  - For example: `/usr/java/bin/java`

- On Win32 systems, use expanded value of: `%JAVA_HOME%\bin\java.exe`

  - For example: `C:\Java\jdk–9\bin\java.exe`

Ensure that you supply the full file name, including the file extension.

#### Other Options

Property: jck.env.jaxb.testExecute.otherOpts

Specify any additional commandline options that must be set.

Specify any command-line options that JavaTest should set for your compiler when it runs the tests on your system. Specify the options using `name=value` pairs. For example you may want to specify: `-Xmx256m -Xms128m` to change the default maximum and initial Java heap size.

#### Other Environment Variables

Property: jck.env.jaxb.testExecute.otherEnvVars

Except for CLASSPATH, if there are any other environment variables that must be set for the reference Java launcher, enter them here.

Specify any environment variables that the JavaTest harness should use in the environment created to run the tests on your system. Specify the variables using the `name=value` pairs.

You must specify at least `JAVA_HOME` and `JAXB_HOME`.

The JavaTest cannot inherit environment variables from your operating system environment. If you find that your tests run correctly outside of the JavaTest harness, but do not run correctly using the JavaTest harness, then the reason might be that a value set in your operating system environment is not available to the test. If you check your operating system environment and determine that this is the case, then set the missing values here.

#### Need Extra XML Binding Classes

Property: jck.env.jaxb.classes.needJaxbClasses

Do you need to specify extra XML Binding classes for the Java launcher to execute tests?

The XML Binding classes must be available (that is, can be found and loaded) during test execution. This means that XML Binding JAR archives which contain the XML Binding classes must be on the class path of the the Java VM executing the test.

Answer `No` if the XML Binding JAR archives are in the Java default class path, for example, all jar files are stored in the jdk_install_dir/jre/lib/ext directory.

Answer `Yes` if some directories or archives are not located on the Java VM default class path.

If you answer `Yes`, then must specify necessary XML Binding archives.

#### Extra XML Binding Classes

Property: jck.env.jaxb.classes.jaxbClasses

Extra XML Binding classes to be put on class path of the the Java VM executing the test.

Specify all necessary XML Binding archives required for tests execution. Archive files must be specified with full path and separated by space.

#### Schema Compiler Operation Mode

Property: jck.env.jaxb.xsd_compiler.defaultOperationMode

Would you like to run your schema compiler in default operation mode?

A XML Binding compatible implementation must support a default operating mode in which all the required XML Schema to Java bindings that are described in the XML Binding specification must be implemented. Errors must be reported when alternative or extension non-required features are encountered.

A XML Binding compatible implementation may support non-default operating modes. These modes must support all the XML Schema to Java bindings that are described in XML Binding specification, but may also generate alternative or extension bindings for XML Schema constructs, which are not required by this specification.

If you select `Yes`, then the schema compiler is supposed to run in default operation mode and the tests for non-required features must be passed (as negative tests with expected error messages).

If you select `No`, then the schema compiler is supposed to run in non-default operation mode and the tests for non-required features will not be run. For more information on default operation mode requirements, see the Compatibility section of the XML Binding specification.

#### Optional XML Validation Tests

Property: jck.env.jaxb.xsd_compiler.skipValidationOptional

Is Schema Validation implemented via mechanism different from JAXP?

XML validation can be implemented from JAXP or from some other mechanism. If the validation is implemented from JAXP, then validation checking tests can be skipped by deselecting them in the test interview. If you use some other tools for schema validation, then XML validation tests are mandatory.

#### Schema Compiler Run Command

Property: jck.env.jaxb.xsd_compiler.testCompile. xjcCmd

Enter the command to run the a schema compiler.

This is the command used to invoke your schema compiler. For example, for the Eclipse XML Binding implementation on Linux we provide a script `$TS_HOME/linux/bin/xjc.sh`, which compiles schemas into class files. The command is as follows:

`/bin/sh /workspace/XMLB-TCK-4.0/linux/bin/xjc.sh`

For the Eclipse XML Binding implementation on Windows, we provide a script `%TS_HOME%\win32\bin\xjc.bat`, which compiles schemas into class files. The command is as follows:

`c:\workspace\XMLB-TCK-4.0\win32\bin\xjc.bat`

The xjc script supports the following mandatory command-line options: `xjc -p <pkg> -d <dir> <schema files>` where:

- `-p <pkg>` specifies the target package

- `-d <dir>` specifies the directory to store generated files.

#### Schema Compiler Class

Property: jaxb.xsd_compiler.run.compilerWrapperClass

You must provide a custom class to invoke your compiler. This class should implement the `com.sun.jaxb_tck.lib.SchemaCompilerTool` interface.

When you run schema compilation through the JavaTest agent, your schema compiler will be executed in the agent’s JVM. Your implementation must provide a custom class to invoke your schema compilation tool. This class should implement the `SchemaCompilerTool` interface:

    package com.sun.jaxb_tck.lib;

    public interface SchemaCompilerTool {

      /**
      * @param xsdFiles – array of strings containing schema files
      * @param packageName – the target package
      * @param outDir – output directory where java file(s) will be generated
      * @param out - output stream for logging
      * @param err - error stream for logging
      * @return 0 if java file(s) generated successfully
      */
      int compile(
        String[] xsdFiles,
        String packageName,
        File outDir,
        PrintStream out,
        PrintStream err
      );
    }

Schema compilation should be accomplished during invocation of compile method. The XML Binding TCK includes the following class that is fully compatible with Eclipse’s compatible implementation and that can be used for schema compilation: `com.sun.jaxb_tck.lib.SchemaCompiler.` The realization of the method `compile(String[] xsdFiles, String packageName, File outDir, PrintStream out, PrintStream err)` compiles a schema into `java` sources. If your implementation doesn’t provide such a class, then create it and specify it here.

#### Schema Generator Presence

Property: jck.env.jaxb.schemagen.skipJ2XOptional

Does your implementation provide schema generator which is able to generate schemas from Java sources?

Java Architecture for XML Binding 4.0 specification does not require any implementation, which provides a possibility to generate the schemas from the java sources. If they are provided, then all specification requirements should be met.

#### Schema Generator Run Command

Property: jck.env.jaxb.schemagen.run.jxcCmd

Enter the command to run the schema generator.

This is the command used to invoke your schema generator. For example, for the Eclipse XML Binding implementation on Linux we provide a script `$TS_HOME/linux/bin/schemagen.sh`, which generates the schemas from the java files. The command is as follows:

`/bin/sh /workspace/XMLB-TCK-4.0/linux/bin/schemagen.sh`

For the Eclipse XML Binding implementation on Windows, we provide a script `%TS_HOME%\win32\bin\schemagen.bat`, which compiles the schemas into class files. The command is as follows:

`c:\workspace\XMLB-TCK-4.0\win32\bin\schemagen.bat`

The schemagen script supports the following mandatory command-line options: `schemagen -d <dir> <java files>`, where `-d <dir>` specifies the directory to store the generated files.

#### Schema Generator Class

Property: jck.env.jaxb.schemagen.run.schemagenWrapperClass

You must provide a custom class to invoke your schema generator. This class should implement the com.sun.jaxb_tck.lib.SchemaGenTool interface.

When you run schema generation through JavaTest agent, your schema generator will be executed in the agent’s JVM. Your implementation must provide a custom class to invoke your schema generation tool. This class should implement the SchemaGenTool interface:

    package com.sun.jaxb_tck.lib;

    public interface SchemaGenTool {
      /**
      * @param javaFiles - array of strings containing java files
      * @param outDir - output directory where schema file(s) will be generated
      * @param out – output stream for logging
      * @param err – error stream for logging
      * @return 0 if schema file(s) generated successfully
      */
      int generate(
        String[] javaFiles,
        File outDir,
        PrintStream out,
        PrintStream err
      );
    }

Schema generations should be complete during the invocation of the generate method. The XML Binding TCK includes the following class that is fully compatible with Eclipse’s compatible implementation and that can be used for schema generation: `com.sun.jaxb_tck.lib.SchemaGen`. The realization of the method `generate(String[] javaFiles, File outDir, PrintStream out, PrintStream err)` generates the XML schemas from the `java` files. If your implementation doesn’t provide such a class, then create it and specify it here.

#### Specify an Exclude List?

Property: jck.excludeList.needExcludeList

Do you wish to specify an exclude list?

Answer `Yes` if you want to specify an exclude list for the test run. If you select Yes, then select the location of the exclude list to use.

Answer `No` if you want to run all tests that are not filtered out by other run filters.

#### Which Exclude List?

Property: jck.excludeList.excludeListType

Which exclude list do you wish to use?

This question appears only if you answered Yes to the previous configuration interview question.

Select either the Initial option to use the exclude list provided with the test suite or the Specify option to specify the exclude list you wish to use.

#### Specify Exclude List Files

Property: jck.excludeList.customFiles

Specify the files that make up the exclude list you wish to use.

Click Add to activate a file chooser with which you select an exclude list file. Exclude list files conventionally use the extension `.jtx`.

#### Specify Keywords?

Property: jck.keywords.needKeywords

Do you wish to specify a keyword expression to select/reject tests based on keywords contained in each test description?

Keywords are tokens associated with specific tests.

Answer `Yes` to run tests based on the keyword and the other run filter settings. If you select Yes, then you are asked to specify the keyword to use.

Answer `No` to run all tests that are not filtered out by other run filters.

#### Specify Status?

Property: jck.priorStatus.needStatus

Do you wish to select tests to run based on their result in a previous run?

Answer Yes to run tests based on the status from the previous test run and the other run filter settings. If you select Yes, then you are asked for the status or statuses.

Answer No to run all tests that are not filtered out by other run filters.

#### Concurrency

Property: jck.concurrency.concurrency

The JavaTest harness can run tests concurrently. Specify the maximum number of tests that should be run concurrently.

The JavaTest harness can run tests concurrently. If you are running the tests on a multiprocessor computer, then the concurrency can accelerate your test runs. The default range of values that the JavaTest harness uses is from 1 to 50. For the first test run, keep this value set to 1.

#### Time Factor

Property: jck.timeout.timeout

Specify a time factor that is applied to each test’s default timeout. For example, specifying 2 doubles the time for each test (the default is 1).

The default 1.0 corresponds to 10 minutes. Use the floating point format specific to your locale.

Note | Setting a proper time factor value requires consideration of such technical factors as the network connector speed.

### 4.2 Using the JavaTest Harness Software

To run the XML Binding TCK test suite using the JavaTest harness software in JavaTest batch mode, from the command line in your shell environment, please proceed directly to Chapter 5, "Executing Tests."

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