Introduction

## 1 Introduction

This chapter provides an overview of the principles that apply generally to all Technology Compatibility Kits (TCKs) and describes the Jakarta XML Binding TCK (XML Binding 3.0 TCK). It also includes a high level listing of what is needed to get up and running with the XML Binding TCK.

This chapter includes the following topics:

- Compatibility Testing

- About the TCK

- Getting Started With the TCK

### 1.1 Compatibility Testing

Compatibility testing differs from traditional product testing in a number of ways. The focus of compatibility testing is to test those features and areas of an implementation that are likely to differ across other implementations, such as those features that:

- Rely on hardware or operating system-specific behavior

- Are difficult to port

- Mask or abstract hardware or operating system behavior

Compatibility test development for a given feature relies on a complete specification and compatible implementation (CI) for that feature. Compatibility testing is not primarily concerned with robustness, performance, nor ease of use.

#### 1.1.1 Why Compatibility Testing is Important

Jakarta platform compatibility is important to different groups involved with Jakarta technologies for different reasons:

- Compatibility testing ensures that the Jakarta platform does not become fragmented as it is ported to different operating systems and hardware environments.

- Compatibility testing benefits developers working in the Jakarta programming language, allowing them to write applications once and then to deploy them across heterogeneous computing environments without porting.

- Compatibility testing allows application users to obtain applications from disparate sources and deploy them with confidence.

- Conformance testing benefits Jakarta platform implementors by ensuring a level playing field for all Jakarta platform ports.

#### 1.1.2 TCK Compatibility Rules

Compatibility criteria for all technology implementations are embodied in the TCK Compatibility Rules that apply to a specified technology. Each TCK tests for adherence to these Rules as described in Chapter 2, "Procedure for Certification."

#### 1.1.3 TCK Overview

A TCK is a set of tools and tests used to verify that a vendor’s compatible implementation of a Jakarta EE technology conforms to the applicable specification. All tests in the TCK are based on the written specifications for the Jakarta EE platform. A TCK tests compatibility of a vendor’s compatible implementation of the technology to the applicable specification of the technology. Compatibility testing is a means of ensuring correctness, completeness, and consistency across all implementations developed by technology licensees.

The set of tests included with each TCK is called the test suite. Most tests in a TCK’s test suite are self-checking, but some tests may require tester interaction. Most tests return either a Pass or Fail status. For a given platform to be certified, all of the required tests must pass. The definition of required tests may change from platform to platform.

The definition of required tests will change over time. Before your final certification test pass, be sure to download the latest version of this TCK.

#### 1.1.4 Jakarta EE Specification Process (JESP) Program and Compatibility Testing

The Jakarta EE Specification Process (JESP) program is the formalization of the open process that has been used since 2019 to develop and revise Jakarta EE technology specifications in cooperation with the international Jakarta EE community. The JESP program specifies that the following three major components must be included as deliverables in a final Jakarta EE technology release under the direction of the responsible Expert Group:

- Technology Specification

- Compatible Implementation (CI)

- Technology Compatibility Kit (TCK)

For further information about the JESP program, go to Jakarta EE Specification Process community page https://jakarta.ee/specifications.

### 1.2 About the TCK

The XML Binding TCK 3.0 is designed as a portable, configurable, automated test suite for verifying the compatibility of a vendor’s implementation of the XML Binding 3.0 Specification.

#### 1.2.1 TCK Specifications and Requirements

This section lists the applicable requirements and specifications.

- Specification Requirements: Software requirements for a XML Binding implementation are described in detail in the XML Binding 3.0 Specification. Links to the XML Binding specification and other product information can be found at https://jakarta.ee/specifications/xml-binding/3.0/.

- XML Binding Version: The XML Binding 3.0 TCK is based on the XML Binding Specification, Version 3.0.

- Compatible Implementation: One XML Binding 3.0 Compatible Implementation, Eclipse Implementation of JAXB is available from the Eclipse EE4J project (https://projects.eclipse.org/projects/ee4j). See the CI documentation page at https://github.com/eclipse-ee4j/jaxb-ri for more information.

See the XML Binding TCK Release Notes for more specific information about Java SE version requirements, supported platforms, restrictions, and so on.

#### 1.2.2 TCK Components

The XML Binding TCK 3.0 includes the following components:

- JavaTest harness version 5.0 and related documentation. See the `ReleaseNotes-jtharness.html` file and the JT Harness web site for additional information.

- XML Binding TCK signature tests; check that all public APIs are supported and/or defined as specified in the XML Binding Version 3.0 implementation under test.

- If applicable, an exclude list, which provides a list of tests that your implementation is not required to pass.

- API tests for all of the XML Binding API in all related packages:

  - `jakarta.xml.bind`

  - `jakarta.xml.bind.annotation`

  - `jakarta.xml.bind.annotation.adapters`

  - `jakarta.xml.bind.attachment`

  - `jakarta.xml.bind.helpers`

  - `jakarta.xml.bind.util`

The XML Binding TCK tests run on the following platforms:

- CentOS Linux 7

#### 1.2.3 JavaTest Harness

The JavaTest harness version 5.0 is a set of tools designed to run and manage test suites on different Java platforms. To JavaTest, Jakarta EE can be considered another platform. The JavaTest harness can be described as both a Java application and a set of compatibility testing tools. It can run tests on different kinds of Java platforms and it allows the results to be browsed online within the JavaTest GUI, or offline in the HTML reports that the JavaTest harness generates.

The JavaTest harness includes the applications and tools that are used for test execution and test suite management. It supports the following features:

- Sequencing of tests, allowing them to be loaded and executed automatically

- Graphic user interface (GUI) for ease of use

- Automated reporting capability to minimize manual errors

- Failure analysis

- Test result auditing and auditable test specification framework

- Distributed testing environment support

To run tests using the JavaTest harness, you specify which tests in the test suite to run, how to run them, and where to put the results as described in Chapter 4, "Setup and Configuration."

#### 1.2.4 TCK Compatibility Test Suite

The test suite is the collection of tests used by the JavaTest harness to test a particular technology implementation. In this case, it is the collection of tests used by the XML Binding TCK 3.0 to test a XML Binding 3.0 implementation. The tests are designed to verify that a vendor’s runtime implementation of the technology complies with the appropriate specification. The individual tests correspond to assertions of the specification.

The tests that make up the TCK compatibility test suite are precompiled and indexed within the TCK test directory structure. When a test run is started, the JavaTest harness scans through the set of tests that are located under the directories that have been selected. While scanning, the JavaTest harness selects the appropriate tests according to any matches with the filters you are using and queues them up for execution.

#### 1.2.5 Exclude Lists

Each version of a TCK includes an Exclude List contained in a `.jtx` file. This is a list of test file URLs that identify tests which do not have to be run for the specific version of the TCK being used. Whenever tests are run, the JavaTest harness automatically excludes any test on the Exclude List from being executed.

A vendor’s compatible implementation is not required to pass or run any test on the Exclude List. The Exclude List file, `<TS_HOME>/lib/jaxb_tck23.jtx`, is included in the XML Binding TCK.

Note | From time to time, updates to the Exclude List are made available. The exclude list is included in the Jakarta TCK ZIP archive. Each time an update is approved and released, the version number will be incremented. You should always make sure you are using an up-to-date copy of the Exclude List before running the XML Binding TCK to verify your implementation.

A test might be in the Exclude List for reasons such as:

- An error in an underlying implementation API has been discovered which does not allow the test to execute properly.

- An error in the specification that was used as the basis of the test has been discovered.

- An error in the test itself has been discovered.

- The test fails due to a bug in the tools (such as the JavaTest harness, for example).

In addition, all tests are run against the compatible implementations. Any tests that fail when run on a compatible Jakarta platform are put on the Exclude List. Any test that is not specification-based, or for which the specification is vague, may be excluded. Any test that is found to be implementation dependent (based on a particular thread scheduling model, based on a particular file system behavior, and so on) may be excluded.

Note | Vendors are not permitted to alter or modify Exclude Lists. Changes to an Exclude List can only be made by using the procedure described in Section 2.3.1, "TCK Test Appeals Steps."

#### 1.2.6 TCK Configuration

You need to set several variables in your test environment, modify properties in the `<TS_HOME>/lib/jaxb_tck23.jte` file, and then use the JavaTest harness to configure and run the XML Binding tests, as described in Chapter 4, "Setup and Configuration."

#### 1.2.7 XML Binding Technology Overview

The XML Binding TCK 3.0 test suite comprises six test categories:

- Schema to Java mapping tests

- Java to schema mapping tests

- XML Binding framework API tests

- Content tree tests

- XML-to-Java name convention tests

- XML validation tests

##### Schema Compiler Tests

The schema compiler tests verify the following:

1. The schema compiler finds errors in invalid schema.

2. The schema compiler successfully compiles valid schema and the signatures of generated Java classes are appropriate.

3. The schema compiler appropriately compiles schema annotated with XML Binding custom binding declarations:

   - Successfully compiles valid source schema with well-formed binding declarations.

   - Fails to compile valid source schema with non-well-formed binding declarations.

##### XML Binding Framework API Tests

The XML Binding framework API tests cover public classes and interfaces defined in the `javax.xml.bind` package and sub-packages.

##### Content Tree Tests

The content tree tests test the classes generated by the XML Binding schema compiler, including:

1. Unmarshalling valid documents: the documents must be unmarshalled and validated correctly.

2. Marshalling documents: invokes marshalling for valid documents and checks that no errors are reported.

3. Content tree evaluating: check data in content tree after unmarshalling.

4. Content tree validating: modify data in content tree to make the tree invalid and, if the modification does not report an error, then enable XML Binding 3.0 validation on Marshaller, and verify that Marshaller reports the error.

##### XML-to-Java Name Conversion Tests

The XML-to-Java name conversion tests check that XML-to-Java name conversion rules are implemented correctly and support most of the Unicode characters that are allowed for XML names.

##### Schema Generator Tests

The schema generator tests verify that:

1. The schema generator supports all the Java Types to XML mapping.

2. The schema generator appropriately maps Java program elements to XML Schema constructs.

3. The schema generator appropriately maps Java program elements that are customized using mapping annotations and program annotations that are based on JSR–175 program annotation facility:

   - Successfully generates valid target schema from correctly annotated Java program element.

   - Fails to process annotated Java program elements that have constraint violations as specified in the `Java Types to XML` section of the XML Binding 3.0 specification and `javax.xml.bind.annotation` javadocs.

   - The schema generator successfully produces a well-formed schema; all documents expected to be valid against generated schema are valid and all documents expected to be invalid against generated schema are invalid.

##### XML Validation Tests

XML Validation tests are designed to check schema validation when a mechanisms other than JAXP is used. Note that XML validation tests are mandatory when XML validation is not performed via JAXP.

Note | The Jakarta EE Specification Process support multiple compatible implementations. These instructions explain how to get started with the Eclipse Implementation of JAXB CI. If you are using another compatible implementation, refer to material provided by that implementation for specific instructions and procedures.

### 1.3 Getting Started With the TCK

This section provides an general overview of what needs to be done to install, set up, test, and use the XML Binding TCK. These steps are explained in more detail in subsequent chapters of this guide.

1. Make sure that the following software has been correctly installed on the system hosting the JavaTest harness:

- Java SE 8

- A CI for XML Binding 3.0. One example is Eclipse Implementation of JAXB.

- XML Binding TCK version 3.0, which includes:

  - (no additional libraries)

- The XML Binding 3.0 Vendor Implementation (VI)
  See the documentation for each of these software applications for installation instructions. See Chapter 3, "Installation," for instructions on installing the XML Binding TCK.

  1. Set up the XML Binding TCK software.
     See Chapter 4, "Setup and Configuration," for details about the following steps.

     1. Set up your shell environment.

     2. Modify the required properties in the `<TS_HOME>/lib/jaxb_tck23.jte` file.

     3. Configure the JavaTest harness.

  2. Test the XML Binding 3.0 implementation.
     Test the XML Binding implementation installation by running the test suite. See Chapter 5, "Executing Tests."

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