# Release Notes

Jakarta XML Binding Technology Compatibility Kit, Version 3.0

Release 3.0

November 2020

## Table of Contents

- Introduction

  - Release Contents

  - New Features and Improvements

- Known Issue

- Usage Notes

## Introduction

The Jakarta XML Binding Technology Compatibility Kit 3.0 is a test suite and a set of tools that is used to certify that a Jakarta XML Binding 3.0 implementation conforms to the specification and to the Jakarta XML Binding 3.0 Compatible Implementation (CI). The test suite exercises assertions described in the Jakarta XML Binding 3.0 specification and implemented in the Jakarta XML Binding TCK 3.0 CI software. The Jakarta XML Binding TCK uses the JavaTest 5.0 test harness and test suite management tools.

### Release Contents

This release contains updates to the following:

- Tests

- Exclude list

- Documentation

- Tools

Refer to the Jakarta XML Binding TCK 3.0 User Guide for a complete list of directories included in the TCK installation.

### New Features and Improvements

This release contains the following features and improvements:

- Jakarta XML Binding Plugability Layer to locate an implementation or service provider with the help of `java.util.ServiceLoader`

- Additional test coverages

## Known Issues

- If necessary, extra options can be passed to the development tools (such as schema compiler, schema generator, and so on) from these interview question values:

      jck.env.devtools.testExecute.otherOpts
      jck.env.devtools.refExecute.otherOpts

## Usage Notes

This section covers the following topics:

- Schema Compiler

  - Running a Schema Compiler in MultiJVM Execution Mode

  - Sample Scripts for Running the Reference Schema Compiler

  - Running a Schema Compiler in SingleJVM Execution Mode

  - Sample Class for Running the Reference Schema Compiler

- Schema Generator

  - Running a Schema Generator in MultiJVM Execution Mode

  - Sample Scripts for Running the Reference Schema Generator

  - Running a Schema Generator in singleJVM Execution Mode

  - Sample Class for Running the Reference Schema Generator

### Schema Compiler

A wrapper for a Schema Compiler under test should compile XML schema files into Java class files.

#### Running a Schema Compiler in `MultiJVM` Execution Mode

In `MultiJVM` execution mode, the schema compiler is invoked as a separate process for each test requiring schema compilation. The TCK invokes the wrapper script for the schema compiler using the `java.lang.Runtime.exec(String[] cmdarray, String[] envp)` method, where `cmdarray` contains the following parameters:

    command [classpath_option valueC] package_option valueP outputdir_option valueD [extra_options] schema_file

Optional parameters are enclosed in square brackets ([]).

- `command` : The path to a Wrapper-to-Schema Compiler; you can specify this parameter in the test harness configuration editor.

- `classpath_option`: The name of optional classpath ; you can specify this parameter in the test harness configuration editor or by using an environment variable.

- `valueC`: The value of the `classpath_option` is constructed by the TCK.

- `package_option`: The package option name; you can specify this parameter in the test harness configuration editor.

- `valueP`: The value of the `package_option` is constructed by the TCK.

- `outputdir_option`: The output directory option name; you can specify this parameter in the test harness configuration editor.

- `valueD`: The value of the `outputdir_option` is constructed by the TCK.

- `extra_options`: Additional options and their values; you can specify these parameters in the test harness configuration editor.

- `schema_file`: The path constructed by the TCK to the schema to be compiled.

Use the test harness configuration editor to specify the following values for the `envp` parameter:

- `CLASSPATH` environment variable; this is an alternative to the `classpath` option. The configuration editor lets you choose between these two alternatives.

- Additional environment variables, as required.

#### Sample Scripts for Running the Reference Schema Compiler

The Jakarta XML Binding TCK provides two sample scripts, which work for the Jakarta XML Binding Compatible Implementation (CI) and can be used to develop scripts for other Jakarta XML Binding implementations:

- `solaris/bin/xjc.sh` (`linux/bin/xjc.sh`, `macos/bin/xjc.sh`): The `ksh` script that is used to run TCK tests with the Jakarta XML Binding CI on Solaris or Linux platforms. The script accepts the following options:

  - `-d <DIR_NAME>`: The path to the output directory

  - `-p <PACKAGE_NAME>`: The package name to which generated Java classes should belong

  - `-javac <PACKAGE_NAME>` : The optional parameter, which is an alternative path to the Java compiler used to compile generated Java sources

  The script also requires the following environment variables to be set:

  - `JAVA_HOME`: The path to the reference Java

  - `JAXB_HOME`: The path to the Jakarta XML Binding CI

  - `CLASSPATH`: The classpath required for TCK tests

- `win32/bin/xjc.bat`: The Windows batch script that is similar to the script described above

#### Running a Schema Compiler in `SingleJVM` Execution Mode

In `singleJVM` execution mode, all invocations of a schema compiler are made from the JavaTest agent running in the same Java Virtual Machine (JVM).

A wrapper class for the schema compiler should implement the method with the following signature:

    public int <compile_method>(String[] args, java.io.PrintStream out, java.io.PrintStream err)

where `args` contains the following parameters (optional parameters are enclosed in square brackets [ ]):

    package_option valueP outputdir_option valueD [extra_options] schema_file

- `package_option`: The package option name; you can specify the parameter in the test harness configuration editor.

- `valueP`: The value of the `package_option` is constructed by the TCK.

- `outputdir_option`: The output directory option name; you can specify this parameter in the test harness configuration editor.

- `valueD`: The value of the `outputdir_option` is constructed by the TCK.

- `extra_options`: The additional options and their values; you can specify these parameters in the test harness configuration editor.

- `schema_file` : The path constructed by the TCK to the schema to be compiled.

You specify the wrapper class name and the method name in the test harness configuration editor. You should compile the wrapper class before test execution.

#### Sample Class for Running the Reference Schema Compiler

The Jakarta XML Binding TCK provides sample wrapper class, `src/share/classes/com/sun/jaxb_tck/lib/Xjc.java`, which works for the Jakarta XML Binding CI and can be used to develop wrapper classes for other Jakarta XML Binding implementations.

The class provides the following method:

    public int compile(String[] args, PrintStream out, PrintStream err)

This method supports the following `args`:

- `-d <DIR_NAME>`: Path to the output directory

- `-p <PACKAGE_NAME>`: Package name to which generated Java classes should belong

- `extra_options`: Other options to pass to reference schema compiler

### Schema Generator

A wrapper for a schema generator under test should compile Java source files into XML schemas.

#### Running a Schema Generator in `MultiJVM` Execution Mode

In `multiJVM` execution mode, a schema generator is invoked as a separate process for each test requiring schema generation. The TCK invokes a wrapper script for a schema generator using the `java.lang.Runtime.exec(String[] cmdarray, String[] envp)` method, where `cmdarray` contains the following parameters:

    command [classpath_option valueC] package_option valueP outputdir_option valueD [extra_options] java_file

Optional parameters are enclosed in square brackets ([]).

- `command`: The path to a wrapper to schema generator; you can specify the parameter in the test harness configuration editor.

- `classpath_option`: The name of optional classpath; you can specify the parameter in the test harness configuration editor or by using an environment variable.

- `valueC`: The value of the `classpath_option` is constructed by the TCK.

- `package_option`: The package option name; you can specify this parameter in the test harness configuration editor.

- `valueP`: The value of the `package_option` is constructed by the TCK.

- `outputdir_option`: The output directory option name; you can specify this parameter in the test harness configuration editor.

- `valueD`: The value of the `outputdir_option` is constructed by the TCK.

- `extra_options`: The additional options and their values; you can specify these parameters in the test harness configuration editor.

- `java_file`: The path constructed by the TCK to the `java` source to be compiled into schema.

You can use the test harness configuration editor to specify the following values for the `envp` parameter:

- `CLASSPATH` environment variable, which is an alternative to the class path option. The configuration editor lets you choose between these two alternatives.

- Additional environment variables, as required.

#### Sample Scripts for Running the Reference Schema Generator

The TCK provides two sample scripts, which work with the Jakarta XML Binding CI and can be used to develop scripts for other Jakarta XML Binding implementations:

- `solaris/bin/schemagen.sh` (`linux/bin/schemagen.sh`, `macos/bin/schemagen.sh`): The `ksh` script that is used to run the TCK tests with the Jakarta XML Binding CI on Solaris or Linux platforms. This script also requires the following environment variables to be set:

  - `JAVA_HOME`: The path to reference Java

  - `JAXB_HOME`: The path to Jakarta XML Binding CI

  - `CLASSPATH`: The classpath required for TCK tests

- `win32/bin/schemagen.bat`: The Windows batch script that is similar to the script described above

#### Running a Schema Generator in `singleJVM` Execution Mode

In `singleJVM` execution mode, all invocations of a schema generator are made from the JavaTest agent running in the same JVM.

A wrapper class to a schema compiler should implement the method with the following signature:

    public int <generate_method>(String[] args, java.io.PrintStream out, java.io.PrintStream err)

where `args` contains the following parameters:

`package_option valueP outputdir_option valueD [extra_options] java_file`

Optional parameters are enclosed in square brackets ([]).

- `package_option`: The package option name; you can specify this parameter in the test harness configuration editor.

- `valueP`: The value of the `package_option` is constructed by the TCK.

- `outputdir_option`: The output directory option name; you can specify this parameter in the test harness configuration editor.

- `valueD`: The value of the `outputdir_option` is constructed by the TCK.

- `extra_options`: The additional options and their values; you can specify these parameters in the test harness configuration editor.

- `java_file`: The path constructed by the TCK to the `java` source to be compiled into schema.

You specify the wrapper class name and the method name in the test harness configuration editor. You should compile the wrapper class before test execution.

#### Sample Class for Running the Reference Schema Generator

The TCK provides sample wrapper class, `src/share/classes/com/sun/jaxb_tck/lib/SchemaGen.java`, which works for the Jakarta XML Binding CI and can be used to develop wrapper classes for other Jakarta XML Binding implementations. The class provides the following method:

    public int generate(String[] args, PrintStream out, PrintStream err)

The method supports the following `args` parameters:

- `-d <DIR_NAME>`: Path to the output directory

- `-p <PACKAGE_NAME>`: Package name to which generated schema should belong

- `extra_options` : Other options to pass to reference schema generator

Release Notes Jakarta XML Binding Technology Compatibility Kit, Release 3.0