<!-- Fragment document type declaration subset:
Arbortext, Inc., 1988-2008, v.4002
<!DOCTYPE SOLBOOK PUBLIC "-//Sun Microsystems//DTD SolBook 3.1//EN" [
<!ENTITY % TCKentities SYSTEM "TCKentities.ent">
%TCKentities;
]>
-->
<?Pub UDT _bookmark _target>
<?Pub EntList bull rArr sect>
<?Pub Inc>
<?Pub CX solbook(book(title()subtitle()bookinfo()>
<chapter id="GBFOW"><title>Introduction</title>
<highlights>
<para>This chapter provides an overview of the principles that apply generally
to all Technology Compatibility Kits (TCKs) and describes the &TechnologyFullName; TCK
(&TCKShortName; &TechnologyVersion;) (&JSR;). It also includes a high level
listing of what is needed to get up and running with the &TCKShortName;.</para>
</highlights>
<sect1 id="GBFTK"><title>Compatibility Testing</title>
<para>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:</para>
<itemizedlist>
<listitem><para>Rely on hardware or operating system-specific behavior</para>
</listitem>
<listitem><para>Are difficult to port</para></listitem>
<listitem><para>Mask or abstract hardware or operating system behavior</para>
</listitem>
</itemizedlist>
<para>Compatibility test development for a given feature relies on a complete
specification and reference implementation for that feature. Compatibility
testing is not primarily concerned with robustness, performance, or ease of
use.</para>
<sect2 id="GBFQN"><?Pub Dtl><title>Why Compatibility Testing is Important</title>
<para>Java platform compatibility is important to different groups involved
with Java technologies for different reasons:</para>
<itemizedlist>
<listitem><para>Compatibility testing is the means by which Sun Microsystems
ensures that the Java platform does not become fragmented as it is ported
to different operating systems and hardware environments.</para></listitem>
<listitem><para>Compatibility testing benefits developers working in the Java
programming language, allowing them to write applications once and then to
deploy them across heterogeneous computing environments without porting.</para>
</listitem>
<listitem><para>Compatibility testing allows application users to obtain applications
from disparate sources and deploy them with confidence.</para></listitem>
<listitem><para>Conformance testing benefits Java platform implementors by
ensuring a level playing field for all Java platform ports.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="GBFPR"><title>TCK Compatibility Rules</title>
<para>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 <olink targetptr="GBFSN">Chapter&nbsp;2,
Procedure for Java API for RESTful Web Services 1.0 Certification</olink>.</para>
</sect2>
<sect2 id="GBFPW"><title>TCK Overview</title>
<para>A TCK is a set of tools and tests used to verify that a licensee's implementation
of Sun Microsystems's technology conforms to the applicable specification.
All tests in the TCK are based on the written specifications for the Java
platform. A TCK tests compatibility of a licensee's implementation of Sun
Microsystems's technology to the applicable specification of the technology.
Compatibility testing is a means of ensuring correctness, completeness, and
consistency across all implementations developed by Sun Microsystems technology
licensees.</para>
<para>The set of tests included with each TCK is called the <firstterm>test
suite</firstterm>. 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.</para>
<para>The definition of required tests will change over time. Before your
final certification test pass, be sure to download the latest Exclude List
for the TCK you are using.</para></sect2>
<sect2 id="GBFPB"><?Pub Dtl><title>Java Community Process (JCP) Program and
Compatibility Testing</title>
<para>The <trademark>Java Community Process</trademark> (JCP) program is the
formalization of the open process that Sun Microsystems, Inc. has been using
since 1995 to develop and revise Java technology specifications in cooperation
with the international Java community. The JCP program specifies that the
following three major components must be included as deliverables in a final
Java technology release under the direction of the responsible Expert Group:</para>
<itemizedlist>
<listitem><para>Technology Specification</para></listitem>
<listitem><para>Reference Implementation</para></listitem>
<listitem><para>Technology Compatibility Kit (TCK)</para></listitem>
</itemizedlist>
<para>For further information about the JCP program, go to &JCPURL;.</para>
</sect2>
</sect1>
<sect1 id="GBFQR"><title>About the &TCKShortName; &TechnologyVersion;</title>
<para>The &TCKShortName; &TechnologyVersion; is designed as a portable, configurable,
automated test suite for verifying the compatibility of a licensee's implementation
of Sun Microsystems's &TechnologyShortName; &TechnologyVersion; Specification.</para>
<sect2 id="GBFQV"><title>&TCKShortName; Specifications and Requirements</title>
<para>This section lists the applicable requirements and specifications.</para>
<itemizedlist>
<listitem><para><emphasis role="strong">Specification Requirements</emphasis> &mdash;
Software requirements for a &TechnologyShortName; implementation are described
in detail in the &TechnologyShortName; &TechnologyVersion; Specification.
Links to the &TechnologyShortName; specification and other product information
can be found at &SpecURL;.</para></listitem>
<listitem><para><emphasis role="strong">&TechnologyShortName; Version</emphasis> &mdash;
The &TCKShortName; &TechnologyVersion; is based on the &TechnologyShortName; Specification,
Version &TechnologyVersion;.</para></listitem>
<listitem><para><emphasis role="strong">Reference Runtime</emphasis> &mdash;
The designated Reference Runtime for conformance testing of implementations
based upon the &TechnologyShortName; Specification &TechnologyVersion; is
Sun's &TechnologyShortName; &RIVersion; Reference Implementation (Jersey RI).
The Sun &TechnologyShortName; RI is available from &JavaPartnerURL;. See the
RI documentation page at &RIdocURL; for more information.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="GBFSQ"><title>&TCKShortName; Components</title>
<para>The &TCKShortName; &TechnologyVersion; includes the following components:</para>
&TCKComponents;
<para>The &TCKShortName; tests run on the following platforms:</para>
&SupportedPlatforms;</sect2>
<sect2 id="GBFSA"><title>JavaTest Harness</title>
<para>The <trademark>JavaTest</trademark> harness version &JavaTestVersion; is
a set of tools designed to run and manage test suites on different Java platforms.
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.</para>
<para>The JavaTest harness includes the applications and tools that are used
for test execution and test suite management. It supports the following features:
</para>
<itemizedlist>
<listitem><para>Sequencing of tests, allowing them to be loaded and executed
automatically</para></listitem>
<listitem><para>Graphic user interface (GUI) for ease of use</para></listitem>
<listitem><para>Automated reporting capability to minimize manual errors</para>
</listitem>
<listitem><para>Failure analysis</para></listitem>
<listitem><para>Test result auditing and auditable test specification framework</para>
</listitem>
<listitem><para>Distributed testing environment support</para></listitem>
</itemizedlist>
<para>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 <olink targetptr="GBFVV">Chapter&nbsp;4, Setup and Configuration</olink>.</para>
</sect2>
<sect2 id="GBFRA"><title>TCK Compatibility Test Suite</title>
<para>The <emphasis>test suite</emphasis> 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 &TCKShortName; &TechnologyVersion; to
test a &TechnologyShortName; &TechnologyVersion; implementation. The tests
are designed to verify that a licensee's runtime implementation of the technology
complies with the appropriate specification. The individual tests correspond
to assertions of the specification.</para>
<para>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.</para></sect2>
<sect2 id="GBFSH"><title>Exclude Lists</title>
<para>Each version of a TCK includes an Exclude List contained in a <filename>.jtx
</filename> 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.</para>
<para>A licensee is not required to pass any test&mdash;or even run any test&mdash;on
the Exclude List. The Exclude List file, <filename>&lt;TS_HOME>/bin/ts.jtx</filename>,
is included in the &TCKShortName;.</para>
<note><para>From time to time, updates to the Exclude List are made available
on the &JavaPartnerURL; Web site. You should always make sure you are using
an up-to-date copy of the Exclude List before running the &TCKShortName; to
verify your implementation.</para></note>
<para>A test might be in the Exclude List for reasons such as:</para>
<itemizedlist>
<listitem><para>An error in an underlying implementation API has been discovered
which does not allow the test to execute properly.</para></listitem>
<listitem><para>An error in the specification that was used as the basis of
the test has been discovered.</para></listitem>
<listitem><para>An error in the test itself has been discovered.</para>
</listitem>
<listitem><para>The test fails due to a bug in the tools (such as the JavaTest
harness, for example).</para></listitem>
</itemizedlist>
<para>In addition, all tests are run against the Sun Microsystems reference
implementations. Any tests that fail when run on a reference Java 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.</para>
<note><para>Licensees are not permitted to alter or modify Exclude Lists.
Changes to an Exclude List can only be made by using the procedure described
in <olink targetptr="GBFRX">Java API for RESTful Web Services 1.0 Test Appeals
Process</olink>.</para></note>
</sect2>
<sect2 id="GBFRR"><title>&TCKShortName; Configuration</title>
<para>You need to set several variables in your test environment, modify properties
in the <filename>&lt;TS_HOME>/bin/ts.jte</filename> file, and then use the
JavaTest harness to configure and run the &TechnologyShortName; tests, as
described in <olink targetptr="GBFVV">Chapter&nbsp;4, Setup and Configuration</olink>.
</para></sect2>
</sect1>
<sect1 id="GBFQW"><title>Getting Started With the &TCKShortName;</title>
<para>This section provides an general overview of what needs to be done to
install, set up, test, and use the &TCKShortName;. These steps are explained
in more detail in subsequent chapters of this guide.</para>
<task id="GBFRE"><title>To Get Started With the &TCKShortName;</title>
<procedure>
<step><para>Make sure that the following software has been correctly installed
on the system hosting the JavaTest harness:</para>
<itemizedlist>
<listitem><para>&J2EEversion; RI</para></listitem>
<listitem><para>Java SE 5 or higher</para></listitem>
<listitem><para>Jersey 1.1</para></listitem>
<listitem><para>JAX-RS TCK version 1.1, which includes:</para>
<itemizedlist>
<listitem><para>Apache httpclient 3.1</para></listitem>
<listitem><para>Apache Ant 1.7.1</para></listitem>
<listitem><para>Apache logging 1.1.1</para></listitem>
<listitem><para>Apache codec 1.3</para></listitem>
<listitem><para>JDOM1.0</para></listitem>
</itemizedlist>
</listitem>
<listitem><para>The JAX-RS 1.1 Vendor Implementation (VI)</para></listitem>
</itemizedlist>
<para>See the documentation for each of these software applications for installation
instructions. See <olink targetptr="GBFTP">Chapter&nbsp;3, Installation</olink> for
instructions on installing the &TCKShortName;.</para></step>
<step><para>Set up the &TCKShortName; software.</para><para>See <olink
targetptr="GBFVV">Chapter&nbsp;4, Setup and Configuration</olink> for details
about the following steps.</para>
<substeps>
<step><para>Set up your shell environment.</para></step>
<step><para>Modify the required properties in the <filename>&lt;TS_HOME>/bin/ts.jte
</filename> file.</para></step>
<step><para>Configure the JavaTest harness.</para></step></substeps>
</step>
<step><para>Test the &TechnologyShortName; &TechnologyVersion; implementation.</para>
<para>Test the &TechnologyShortName; implementation installation by running
the test suite. See <olink targetptr="GBFWO">Chapter&nbsp;5, Executing Tests</olink>.
</para></step>
</procedure>
</task>
</sect1>
</chapter>
<?Pub *0000014152 0>
