<!-- Fragment document type declaration subset:
Arbortext, Inc., 1988-2006, v.4002
<!DOCTYPE SOLBOOK PUBLIC "-//Sun Microsystems//DTD SolBook 3.1//EN" [
<!ENTITY % TCKentities SYSTEM "TCKentities.ent">
%TCKentities;
]>
-->
<?Pub UDT _bookmark _target>
<?Pub CX solbook(>
<chapter id="GBFVV"><?Pub Dtl><?Pub Caret><title>Setup and Configuration</title>
<highlights><?Pub Dtl>
<para>This chapter describes how to set up the &TCKShortName; and JavaTest
harness software. Before proceeding with the instructions in this chapter,
be sure to install all required software, as described in <olink
type="custom-text" targetptr="GBFTP">Chapter 3</olink>.</para>
<para>After completing the instructions in this chapter, proceed to <olink
type="custom-text" targetptr="GBFWO">Chapter 5</olink> for instructions on
running the &TCKShortName;.</para>
<para>This chapter includes the following topics:</para>
<itemizedlist>
<listitem><para><olink targetptr="GBFVU">Configuring Your Environment to Run
the &TCKShortName;</olink></para></listitem>
<listitem><para><olink targetptr="GCFQK">Deploying the &TCKShortName; Tests</olink></para>
</listitem>
<listitem><para><olink targetptr="GBWKV">Configuring and Starting Your Java
Web Server</olink></para></listitem>
<listitem><para><olink targetptr="GBFUY">Using the JavaTest Harness Software</olink></para>
</listitem>
<listitem><para><olink targetptr="GBFWG">Using the JavaTest Harness Configuration
GUI</olink></para></listitem>
</itemizedlist>
</highlights>
<sect1 id="GBFVU"><?Pub Dtl><title>Configuring Your Environment to Run the &TCKShortName;</title>
<para>This section describes how to configure the &TCKShortName; for your
environment. After configuring your environment, continue with the instructions
in <olink type="custom-text" targetptr="GBFUY">Using the JavaTest Harness
Software</olink>.</para>
<note><para>In these instructions, variables in angle brackets need to be
expanded for each platform. For example, <literal>&lt;TS_HOME></literal> becomes <literal>
$TS_HOME</literal> on Solaris/Linux and <literal>%TS_HOME%</literal> on Windows
2000/XP. In addition, the forward slashes (<literal>/</literal>) used in all
of the examples need to be replaced with backslashes (<literal>\</literal>)
for Windows 2000/XP. Finally, be sure to use the appropriate separator for
your operating system when specifying multiple path entries (<literal>;</literal> on
Windows, <literal>:</literal> on UNIX/Linux).</para></note>
<task id="GBFWN"><title>To Configure Your Environment for the &TCKShortName;</title>
<procedure>
<step><para>Set the following environment variables in your shell environment:</para>
<substeps>
<step><para><literal>JAVA_HOME</literal> to the directory in which &J2SEversion; is
installed</para></step>
<step><para><literal>TS_HOME</literal> to the directory in which the &TCKShortName; &TechnologyVersion; software
is installed</para></step>
<step><para><literal>SAAJ_HOME</literal> to the directory in which the &TechnologyShortName; RI
software is installed</para></step>
<step><para><literal>CATALINA_HOME</literal> to the directory in which the
Apache Tomcat 5.5.<emphasis>x</emphasis> Web Container is installed</para>
</step>
<step><para><literal>ANT_HOME</literal> should <emphasis>not</emphasis> be
set in your environment. If it is set, either unset it or make sure it is
set to <filename>&lt;TS_HOME>/tools/ant</filename>. The <command>tsant</command> script
automatically sets <literal>ANT_HOME</literal> if it is unset in the environment.
</para></step></substeps>
</step>
<step><para>Edit your <filename>&lt;TS_HOME>/bin/ts.jte</filename> file and
set the following environment variables:</para>
<substeps>
<step><para>Set the <literal>webServerHost</literal> property to the name
of the host on which your Web server is running.</para><para>The default setting
is <literal>localhost</literal>.</para></step>
<step><para>Set the <literal>webServerPort</literal> property to the port
number of the host on which the Web server is running.</para><para>The default
setting is <literal>8080</literal>.</para></step>
<step><para>Set the <literal>local.classes</literal> property to point to
the SAAJ RI classes/jars. You also need to include the <literal>servlet-api.jar</literal>,
which you can include from the appropriate location within the reference implementation
under test.</para><para>For the Apache Tomcat 5.5.<emphasis>x</emphasis> standalone
Web Container your <literal>local.classes</literal> property setting should
be:</para>
<screen>local.classes=${env.SAAJ_HOME}/lib/saaj-api.jar:
${env.SAAJ_HOME}/lib/saaj-impl.jar:
${env.SAAJ_HOME}/lib/activation.jar:
${env.CATALINA_HOME}/common/lib/servlet-api.jar</screen>
</step>
<step><para>Set the <literal>webserver.container</literal> property to the
supported web container type used for testing.</para><para>The supported web
container type for standalone web applications is Tomcat via <filename>tomcat.xml
</filename>. By default this is set to <filename>tomcat.xml</filename>.</para>
</step>
<step><para>Set the <literal>webcontainer.home</literal> property to the location
in which the Web container under test is installed.</para><para>The supported
web container type for standalone Web applications is Tomcat, so this property
should be set to where your Tomcat is installed.</para></step>
<step><para>Set the <literal>porting.ts.url.class.1</literal> property to
your porting implementation class that is used for obtaining URLs.</para><para>The
default setting for the Sun RI porting implementation is:</para>
<screen>com.sun.ts.lib.implementation.sun.common.SunRIURL</screen>
</step></substeps>
</step>
<step><para>Provide your own implementations of the porting package interfaces
provided with the &TCKShortName;.</para><para>The porting interfaces are:</para>
<itemizedlist>
<listitem><para><literal>TSURLInterface.java</literal> &mdash; Obtains URL
strings for web resources in an implementation-specific manner</para></listitem>
</itemizedlist>
<para>API documentation for the <literal>TSURLInterface.java</literal> porting
package interface is available in the <filename>&lt;TS_HOME>/docs/api</filename> directory.
</para></step>
</procedure>
</task>
</sect1>
<sect1 id="GCFQK"><?Pub Dtl><title>Deploying the &TCKShortName; Tests</title>
<task id="GCFQX"><title>To Deploy the &TCKShortName; Tests</title>
<procedure>
<step><para>Change to the <filename>&lt;TS_HOME>/dist</filename> directory.</para>
</step>
<step><para>Copy the &TCKShortName; WAR files to the appropriate container.</para>
<para>For example, for the Apache Tomcat 5.5.<emphasis>x</emphasis> Web container,
use the following command:</para>
<screen>cp *war &lt;CATALINA_HOME>/webapps</screen>
</step>
</procedure>
</task>
</sect1>
<sect1 id="GBWKV"><?Pub Dtl><title>Configuring and Starting Your Java Web
Server</title>
<para>Complete the following two procedures to configure your Web server environment
for Java Web Services Developers Pack.</para>
<task id="GBWKY"><title>To Configure the Java Web Server</title>
<procedure>
<step><para>Set the following environment variables in your shell environment:</para>
<substeps>
<step><para><literal>JAVA_HOME</literal> to the directory in which &J2SEversion; is
installed</para></step>
<step><para><literal>TS_HOME</literal> to the directory in which the &TCKShortName; &TechnologyVersion; software
is installed</para></step>
<step><para><literal>SAAJ_HOME</literal> to the directory in which the &TechnologyShortName; RI
software is installed</para></step>
<step><para><literal>CATALINA_HOME</literal> to the directory in which the
Apache Tomcat 5.5.<emphasis>x</emphasis> Web Container is installed</para>
</step></substeps>
</step>
<step><para>Copy the required jar files to the Web server shared library directory:
</para><para>For the Apache Tomcat 5.5.<emphasis>x</emphasis> Web Container,
use the following commands:</para>
<screen>cp &lt;TS_HOME>/lib/tsharness.jar &lt;TS_HOME>/lib/saajtck.jar &lt;CATALINA_HOME>/shared/lib
cp &lt;SAAJ_HOME>/lib/*.jar &lt;CATALINA_HOME>/shared/lib</screen>
</step>
</procedure>
</task>
<task id="GBWJI"><title>To Start the Java Web Server</title>
<procedure role="single-step">
<step><para>Execute the <filename>&lt;CATALINA_HOME>/bin/startup.sh</filename> script
or the <filename>&lt;CATALINA_HOME>/bin/startup.bat</filename> batch file.</para>
<para>Wait for the Web server to come up. Look at the file <filename>&lt;CATALINA_HOME>/logs/launcher.server.log
</filename> and wait until the messages stop printing to the file. After a
series of startup and initialization messages, you will see the following
message when the web server has completed its startup:</para>
<screen>[INFO] Http11Protocol - -Starting Coyote HTTP/1.1 on port 8080
[INFO] Catalina - -Server startup in 126511 ms</screen>
</step>
</procedure>
</task>
</sect1>
<sect1 id="GBFUY"><?Pub Dtl><title>Using the JavaTest Harness Software</title>
<para>There are two general ways to run the &TCKShortName; test suite using
the JavaTest harness software:</para>
<itemizedlist>
<listitem><para>Through the JavaTest GUI; if using this method, please continue
on to <olink type="custom-text" targetptr="GBFWG">Using the JavaTest Harness
Configuration GUI</olink>.</para></listitem>
<listitem><para>In JavaTest batch mode, from the command line in your shell
environment; if using this method, please proceed directly to <olink
type="custom-text" targetptr="GBFWO">Chapter 5</olink>.</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="GBFWG"><?Pub Dtl><title>Using the JavaTest Harness Configuration
GUI</title>
<para>You can use the JavaTest harness GUI to modify general test settings
and to quickly get started with the default &TCKShortName; test environment.
This section covers the following topics:</para>
<itemizedlist>
<listitem><para><olink targetptr="GBFVA">Configuration GUI Overview</olink></para>
</listitem>
<listitem><para><olink targetptr="GBFVD">Starting the Configuration GUI</olink></para>
</listitem>
<listitem><para><olink targetptr="GBFVX">The Configuration Interview</olink></para>
</listitem>
<listitem><para><olink targetptr="GBFUU">Modifying the Default Test Configuration
</olink></para></listitem>
</itemizedlist>
<note><para>It is only necessary to proceed with this section if you want
to run the JavaTest harness in GUI mode. If you plan to run the JavaTest harness
in command-line mode, skip the remainder of this chapter, and continue with <olink
type="custom-text" targetptr="GBFWO">Chapter 5</olink>.</para></note>
<sect2 id="GBFVA"><?Pub Dtl><title>Configuration GUI Overview</title>
<para>In order for the JavaTest harness to execute the test suite, it requires
information about how your computing environment is configured. The JavaTest
harness requires two types of configuration information:</para>
<itemizedlist>
<listitem><para><emphasis role="strong">Test environment</emphasis> &mdash;
This is data used by the tests. For example, the path to the Java runtime,
how to start the product being tested, network resources, and other information
required by the tests in order to run. This information does not change frequently
and usually stays constant from test run to test run.</para></listitem>
<listitem><para><emphasis role="strong">Test parameters</emphasis> &mdash;
This is information used by the JavaTest harness to run the tests. Test parameters
are values used by the JavaTest harness that determine which tests in the
test suite are run, how the tests should be run, and where the test reports
are stored. This information often changes from test run to test run.</para>
</listitem>
</itemizedlist>
<para>The first time you run the JavaTest harness software, you are asked
to specify the test suite and work directory that you want to use. (These
parameters can be changed later from within the JavaTest harness GUI.)</para>
<para>Once the JavaTest harness GUI is displayed, whenever you choose <emphasis>Run
Tests->Start</emphasis> to begin a test run, the JavaTest harness determines
whether all of the required configuration information has been supplied:</para>
<itemizedlist>
<listitem><para>If the test environment and parameters have been completely
configured, the test run starts immediately.</para></listitem>
<listitem><para>If any required configuration information is missing, the
configuration editor displays a series of questions asking you the necessary
information. This is called the configuration interview . When you have entered
the configuration data, you are asked if you wish to proceed with running
the test.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="GBFVD"><title>Starting the Configuration GUI</title>
<para>Before you start the JavaTest harness software, you must have a valid
test suite and &J2SEversion; installed on your system.</para>
<para>The &TCKShortName; includes an Ant script that is used to execute the
JavaTest harness from the <literal>&lt;TS_HOME></literal> directory. Using
this Ant script to start the JavaTest harness is part of the procedure described
in <olink type="custom-text" targetptr="GBFVX">The Configuration Interview</olink>.
</para>
<para>When you execute the JavaTest harness software for the first time, the
JavaTest harness displays a Welcome dialog box that guides you through the
initial startup configuration.</para>
<itemizedlist>
<listitem><para>If it is able to open a test suite, the JavaTest harness displays
a Welcome to JavaTest dialog box that guides you through the process of either
opening an existing work directory or creating a new work directory as described
in the JavaTest online help.</para></listitem>
<listitem><para>If the JavaTest harness is unable to open a test suite, it
displays a Welcome to JavaTest dialog box that guides you through the process
of opening both a test suite and a work directory as described in the JavaTest
documentation.</para></listitem>
</itemizedlist>
<para>After you specify a work directory, you can use the Test Manager to
configure and run tests as described in <olink type="custom-text"
targetptr="GBFVX">The Configuration Interview</olink>.</para></sect2>
<sect2 id="GBFVX"><title>The Configuration Interview</title>
<para>The answers you give to some of the configuration interview questions
are specific to your site. For example, the name of the host on which the
JavaTest harness is running. Other configuration parameters can be set however
you wish. For example, where you want test report files to be stored.</para>
<task id="GBFUW"><title>To configure the JavaTest harness to run the &TCKShortName; tests
</title>
<tasksummary>
<para>Note that you only need to complete all these steps the first time you
start the JavaTest test harness. After you complete these steps, you can either
run all of the tests by completing the steps in <olink type="custom-text"
targetptr="GBFUZ">Starting JavaTest</olink> or run a subset of the tests by
completing the steps in <olink type="custom-text" targetptr="GBFWM">Running
a Subset of the Tests</olink>.</para></tasksummary>
<procedure>
<step><para>Change to the <filename>&lt;TS_HOME>/bin</filename> directory
and start the JavaTest test harness:</para>
<literallayout><command>cd &lt;TS_HOME>/bin</command>
<command>./tsant gui</command></literallayout><para>If the Welcome Screen
does not appear do the following, otherwise skip to next step.</para></step>
<step><para>Click <emphasis>File->Open Quick Start Wizard</emphasis>.</para>
<para>The Welcome screen displays.</para></step>
<step><para>Click <emphasis>Start a new test run</emphasis>, and then click <emphasis>
Next</emphasis>.</para><para>You are prompted to Create a new configuration
or use a configuration template.</para></step>
<step><para>Select <emphasis>Create a new configuration</emphasis>, and then
click <emphasis>Next</emphasis>.</para><para>You are prompted to select a
test suite.</para></step>
<step><para>Accept the default suite (<filename>&lt;TS_HOME>/src</filename>),
and then click <emphasis>Next</emphasis>.</para><para>You are prompted to
specify a work directory to use to store your test results.</para></step>
<step><para>Type a work directory name or use the <emphasis>Browse</emphasis> button
to select a work directory, and then click <emphasis>Next</emphasis>.</para>
<para>You are prompted to start the configuration editor or start a test run.
At this point, the &TCKShortName; is configured to run the default test suite.</para>
</step>
<step><para>Uncheck the <emphasis>Start the configuration editor</emphasis> option,
and then click <emphasis>Finish</emphasis>.</para></step>
<step><para>Click Run Tests->Start.</para><para>The JavaTest harness starts
running the tests.</para></step>
<step><para>To Reconfigure the JavaTest test harness, click <emphasis>Configuration->New
Configuration</emphasis> or <emphasis>Configuration->Change Configuration</emphasis>.
</para></step>
<step><para>Click <emphasis>Report->Create Report</emphasis>.</para></step>
<step><para>Specify the directory in which the JavaTest test harness will
write the report, and then click <emphasis>OK</emphasis>.</para><para>A report
is created, and you are asked whether you want to view it.</para></step>
<step><para>Click <emphasis>Yes</emphasis> to view the report.</para></step>
</procedure>
</task>
</sect2>
<sect2 id="GBFUU"><title>Modifying the Default Test Configuration</title>
<para>The JavaTest GUI enables you to configure numerous test options. These
options are divided into two general dialog box groups:</para>
<itemizedlist>
<listitem><para><emphasis role="strong">Group 1</emphasis> &mdash; Available
from the JavaTest <emphasis>Configure->Change Configuration</emphasis> submenus,
the following options are displayed in a tabbed dialog box:</para>
<itemizedlist>
<listitem><para><emphasis>Tests to Run</emphasis></para></listitem>
<listitem><para><emphasis>Exclude List</emphasis></para></listitem>
<listitem><para><emphasis>Keywords</emphasis></para></listitem>
<listitem><para><emphasis>Prior Status</emphasis></para></listitem>
<listitem><para><emphasis>Test Environment</emphasis></para></listitem>
<listitem><para><emphasis>Concurrency</emphasis></para></listitem>
<listitem><para><emphasis>Timeout Factor</emphasis></para></listitem>
</itemizedlist>
</listitem>
<listitem><para><emphasis role="strong">Group 2</emphasis> &mdash; Available
from the JavaTest <emphasis>Configure->Change Configuration->Other Values</emphasis> submenu,
or by pressing <keycap>Ctrl+E</keycap>, the following options are displayed
in a paged dialog box:</para>
<itemizedlist>
<listitem><para><emphasis>Environment Files</emphasis></para></listitem>
<listitem><para><emphasis>Test Environment</emphasis></para></listitem>
<listitem><para><emphasis>Specify Tests to Run</emphasis></para></listitem>
<listitem><para><emphasis>Specify an Exclude List</emphasis></para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>Note that there is some overlap between the functions in these two dialog
boxes; for those functions use the dialog that is most convenient for you.
Please refer to the JavaTest Harness documentation or the online help for
complete information about these various options.</para></sect2>
</sect1>
</chapter>
<?Pub *0000019233 0>
