<!-- 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 CX solbook(>
<chapter id="GBFVV"><title>Setup and Configuration</title>
<highlights>
<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>
<note><para>The &TCKShortName; &TechnologyVersion; contains two configuration
values in <filename>&lt;TS_HOME>/bin/ts.jte</filename> that correspond to
the two implementations used during test execution. These two properties are <literal>
jaxws.home</literal> and <literal>jaxws.home.ri</literal>.</para><para>The <literal>
jaxws.home</literal> property should point to the implementation under test.
In most cases, this will be your implementation of &TechnologyShortName;.
However, it is recommended that you initially set this to the location of
the Sun &TechnologyShortName; RI to familiarize yourself with the JAX-WS TCK
suite and JavaTest software, as well as ensure that your environment is correctly
configured.</para><para>The <literal>jaxws.home.ri</literal> property must
always be set to the location of the Sun Reference Implementation. The installation
to which <literal>jaxws.home.ri</literal> points to is used when running reverse
tests. These tests can only be run after you have successfully rebuilt the
tests using your implementation of the &TechnologyShortName; &TechnologyVersion; toolset.
Please see <olink type="custom-text" targetptr="GCLIZ">Appendix B</olink> for
more information on rebuilding tests.</para></note>
<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 remap="jumplist">
<listitem><para><olink targetptr="GBFVU">Configuring Your Environment to Run
the JAX-WS TCK Against the Sun Reference Implementation</olink></para>
</listitem>
<listitem><para><olink targetptr="GCLHU">Configuring Your Environment to Run
the JAX-WS TCK Against the Vendor Implementation</olink></para></listitem>
<listitem><para><olink targetptr="GCLHF">Configuring Your Environment to Rebuild
and Run the JAX-WS TCK Against the Sun RI</olink></para></listitem>
<listitem><para><olink targetptr="GCLIK">Configuring Your Environment to Simultaneously
Run the JAX-WS TCK Against the VI and the Sun RI</olink></para></listitem>
<listitem><para><olink targetptr="GCFOI">Configuring and Starting Your Application
Server(s)</olink></para></listitem>
<listitem><para><olink targetptr="GCLIN">Deploying the JAX-WS TCK Tests</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"><title>Configuring Your Environment to Run the &TCKShortName; Against
the Sun Reference Implementation</title>
<para>After configuring your environment as described in this section, continue
with the instructions in <olink type="custom-text" targetptr="GBFUY">Using
the JavaTest Harness Software</olink>.</para>
<note>
<itemizedlist>
<listitem><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
XP/Vista. In addition, the forward slashes (<literal>/</literal>) used in all
of the examples need to be replaced with backslashes (<literal>\</literal>)
for Windows XP/Vista. 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></listitem>
<listitem><para>On Windows, you must escape any backslashes with an extra
backslash in path separators used in any of the following properties, or use
forward slashes as a path separator instead. For example, if the Sun Java EE 6 RI
installation is <filename>C:\Sun\JavaEE6</filename>,
you must specify it as <filename>C:\\Sun\\JavaEE6</filename> or <filename>C:/Sun/JavaEE6
</filename>.</para></listitem>
</itemizedlist>
</note>
<task id="GBFWN"><title>To Configure Your Environment to Run the &TCKShortName; Against
the Sun RI</title>
<procedure>
<step><para>The term Sun RI refers to the Sun Java EE 6 RI which
contains the &TechnologyShortName; RI implementation classes/jars.</para></step>
<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>ANT_HOME</literal> must be set to <filename>&lt;TS_HOME&gt;/tools/ant
</filename></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 hostname
where the web server is running that is configured with the Sun RI.</para><para>The
default setting is <literal>localhost</literal>.</para></step>
<step><para>Set the <literal>webServerPort</literal> property to the port
number where the web server is running that is configured with the Sun RI.</para>
<para>The default setting is <literal>8000</literal>.</para></step>
<step><para>Set the <literal>jaxws.home</literal> property to the location
where the Sun RI is installed.</para><para>The default setting is <literal>${webcontainer.home}
</literal>.</para></step>
<step><para>Set the <literal>jaxws.classes</literal> property to point to
the Sun RI classes/jars.</para><para>Note that this property is already set
and should not require any changes.</para></step>
<step><para>Verify that the <literal>tools.jar</literal> property is set to
the location of the <filename>tools.jar</filename> file that is distributed
with &J2SEversion;.</para></step>
<step><para>Set the <literal>impl.vi, impl.vi.deploy.dir, impl.vi.host, and
impl.vi.port</literal> properties to the supported web container, deploy directory,
host and port for the Sun RI.</para><para>The supported web container for
the Sun RI is the Sun Java EE 6 RI. So the default settings
for these properties are as follows:</para>
<screen>impl.vi.deploy.dir=${webcontainer.home}/domains/domain1/autodeploy
impl.vi=glassfish.xml
impl.vi.host=${webServerHost}
impl.vi.port=${webServerPort}</screen>
</step>
<step><para>Set the <literal>webcontainer.home</literal> property to the location
where the web server is installed for the Sun RI. This will be where the Sun
Java EE 6 RI is installed.</para></step>
<step><para>Set the <literal>porting.ts.url.class.1</literal> property to
the 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>
<step><para>Set the <literal>user</literal> and <literal>password</literal> properties
to the user name and password used for the basic authentication tests.</para>
<para>The default setting is <literal>j2ee</literal> for both.</para></step>
<step><para>Set the <literal>authuser</literal> and <literal>authpassword</literal> properties
to the user name and password used for the basic authentication tests.</para>
<para>The default setting for both is <literal>javajoe</literal>.</para></step>
<step><para>Set the <literal>http.server.supports.endpoint.publish</literal> property
based on whether Endpoint Publish APIs are supported on the container.</para>
</step>
<step><para>If using Java SE 6 or above, verify that the property <literal>endorsed.dirs
</literal> is set to the location of the VI API jars for those technologies
you wish to override.  Java SE 6 contains an implementation of &TechnologyShortName; 2.1
which will conflict with &TechnologyShortName; &TechnologyVersion;, therefore
this property must be set so that &TechnologyShortName; &TechnologyVersion; will
be used during the building of tests and during test execution.</para></step>
</substeps>
</step>
<step><para>Edit the catalog file <filename>&lt;TS_HOME>/bin/catalog/META-INF/jax-ws-catalog.xml
</filename>, replacing the host and port settings of <literal>systemId</literal> with
the value of your host and port setting where the WSDL is published.</para>
</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>
<step><para>The <filename>&lt;TS_HOME>/bin/jaxws-url-props.dat</filename> file
contains the webservice endpoint and WSDL URLs that the TCK tests use when
running against the Sun RI. In the Sun porting package that the TCK uses,
the URLs are returned as is since this is the form that the Sun RI expects.
You may need an alternate form of these URLs in order to run the TCK tests
in your environment. However, you MUST NOT modify the <literal>jaxws-url-props.dat
</literal> file, but instead make any necessary changes in your own porting
implementation class to transform the URLs appropriately for your environment.</para>
</step>
</procedure>
</task>
</sect1>
<sect1 id="GCLHU"><title>Configuring Your Environment to Run the &TCKShortName; Against
the Vendor Implementation</title>
<para>After configuring your environment as described in this section, continue
with the instructions in <olink type="custom-text" targetptr="GBFUY">Using
the JavaTest Harness Software</olink>.</para>
<note>
<itemizedlist>
<listitem><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
XP/Vista. In addition, the forward slashes (<literal>/</literal>) used in all
of the examples need to be replaced with backslashes (<literal>\</literal>)
for Windows XP/Vista. 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></listitem>
<listitem><para>On Windows, you must escape any backslashes with an extra
backslash in path separators used in any of the following properties, or use
forward slashes as a path separator instead. For example, if the Sun Java EE 6 RI 
installation is <filename>C:\Sun\JavaEE6</filename>,
you must specify it as <filename>C:\\Sun\\JavaEE6</filename> or <filename>C:/Sun/JavaEE6
</filename>.</para></listitem>
</itemizedlist>
</note>
<task id="GCLIC"><title>To Configure Your Environment to Run the &TCKShortName; Against
the VI</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>ANT_HOME</literal> must be set to <filename>&lt;TS_HOME&gt;/tools/ant
</filename></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 hostname
where the web server is running that is configured with the Vendor Implementation.
</para><para>The default setting is <literal>localhost</literal>.</para></step>
<step><para>Set the <literal>webServerPort</literal> property to the port
number where the web server is running that is configured with the Vendor
Implementation.</para><para>The default setting is <literal>8000</literal>.</para>
</step>
<step><para>Set the <literal>jaxws.home</literal> property to the location
where the Vendor Implementation is installed.</para><para>The default setting
is <literal>${webcontainer.home}</literal>.</para></step>
<step><para>Set the <literal>jaxws.classes</literal> property to point to
the Vendor Implementation classes/jars.</para><para>As an example, the <filename>ts.jte
</filename> file contains the property <literal>jaxws.classes.ri</literal>,
which contains the classes/jar files that the Sun Java EE 6 RI uses. The <literal>jaxws.classes.ri
</literal> settings for the Sun Java EE 6 RI web container are as follows:</para>
<screen>jaxws.home.ri=${webcontainer.home.ri}
jaxws.lib.ri=${jaxws.home.ri}/modules
endorsed.dirs.ri=${jaxws.home.ri}/modules/endorsed</screen>
<screen>jaxws.classes.ri=${endorsed.dirs.ri}/webservices-api-osgi.jar:
${endorsed.dirs.ri}/jaxb-api-osgi.jar:
${jaxws.lib.ri}/webservices-osgi.jar:
${jaxws.lib.ri}/jaxb-osgi.jar:
${jaxws.lib.ri}/gmbal.jar:
${jaxws.lib.ri}/management-api.jar:
${jaxws.lib.ri}/mimepull.jar</screen>
<para>The <literal>jaxws.classes.ri </literal> settings if using the Apache Tomcat web container with
the Standalone &TechnologyShortName; &TechnologyVersion; Sun RI would be as follows:</para>
<screen>jaxws.home.ri=${webcontainer.home.ri}
jaxws.lib.ri=${jaxws.home.ri}/shared/lib
endorsed.dirs.ri=${jaxws.home.ri}/common/endorsed</screen>
<screen>jaxws.classes.ri=${endorsed.dirs.ri}/jaxws-api.jar:
${endorsed.dirs.ri}/jsr181-api.jar:
${endorsed.dirs.ri}/jsr250-api.jar:
${endorsed.dirs.ri}/jsr173_api.jar:
${endorsed.dirs.ri}/activation.jar:
${endorsed.dirs.ri}/management-api.jar:
${endorsed.dirs.ri}/saaj-api.jar:
${endorsed.dirs.ri}/jaxb-api.jar:
${jaxws.lib.ri}jaxws-rt.jar:
${jaxws.lib.ri}/jaxws-tools.jar:
${jaxws.lib.ri}/resolver.jar:
${jaxws.lib.ri}/http.jar:
${jaxws.lib.ri}/saaj-impl.jar:
${jaxws.lib.ri}/FastInfoset.jar:
${jaxws.lib.ri}/jaxb-impl.jar:
${jaxws.lib.ri}/jaxb-xjc.jar:
${jaxws.lib.ri}/woodstox.jar:
${jaxws.lib.ri}/stax-ex.jar:
${jaxws.lib.ri}/gmbal.jar:
${jaxws.lib.ri}/mimepull.jar:
${jaxws.lib.ri}/policy.jar:
${jaxws.lib.ri}/streambuffer.jar</screen>
</step>
<step><para>Verify that the <literal>tools.jar</literal> property is set to
the location of the <filename>tools.jar</filename> file that is distributed
with &J2SEversion;.</para></step>
<step><para>Set the <literal>impl.vi, impl.vi.deploy.dir, impl.vi.host, and
impl.vi.port</literal> properties to the supported web container, deploy directory,
host and port for the Vendor Implementation.</para><para>As an example, the 
the <filename>ts.jte</filename> file contains the ri settings for the Sun Java EE 6 RI
 which are as follows:</para>
<screen>webcontainer.home.ri=/sun/javaee6
impl.ri.deploy.dir=${webcontainer.home.ri}/domains/domain1/autodeploy
impl.ri=glassfish.xml
impl.ri.host=${webServerHost.2}
impl.ri.port=${webServerPort.2}</screen>
<para>The ri settings is using the Apache Tomcat web container with the
Standalone &TechnologyShortName; &TechnologyVersion; Sun RI would be as follows:</para>
<screen>webcontainer.home.ri=/tomcat
impl.ri=tomcat
impl.ri.deploy.dir=${webcontainer.home.ri}/webapps
impl.ri.host=${webServerHost.2}
impl.ri.port=${webServerPort.2}</screen>
</step>
<step><para>Set the <literal>webcontainer.home</literal> property to the location
where the web container for the Vendor Implementation is installed.</para>
</step>
<step><para>Set the <literal>porting.ts.url.class.1</literal> property to
the 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>
<step><para>Set the <literal>user</literal> and <literal>password</literal> properties
to the user name and password used for the basic authentication tests.</para>
<para>The default setting for both is <literal>j2ee</literal>.</para></step>
<step><para>Set the <literal>authuser</literal> and <literal>authpassword</literal> properties
to the user name and password used for the basic authentication tests.</para>
<para>The default setting for both is <literal>javajoe</literal>.</para></step>
<step><para>Set the <literal>http.server.supports.endpoint.publish</literal> property
based on whether Endpoint Publish APIs are supported on the container.</para>
</step>
<step><para>If using Java SE 6 or above, verify that the property <literal>endorsed.dirs
</literal> is set to the location of the RI API jars for those technologies
you wish to override.  Java SE 6 contains an implementation of &TechnologyShortName; 2.1
which will conflict with &TechnologyShortName; &TechnologyVersion;, therefore
this property must be set so that &TechnologyShortName; &TechnologyVersion; will
be used during the building of tests and during test execution.</para></step>
</substeps>
</step>
<step><para>Edit the catalog file <filename>&lt;TS_HOME>/bin/catalog/META-INF/jax-ws-catalog.xml
</filename>, replacing the host and port settings of <literal>systemId</literal> with
the value of your host and port setting where the WSDL is published.</para>
</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>
<step><para>The <filename>&lt;TS_HOME>/bin/jaxws-url-props.dat</filename> file
contains the webservice endpoint and WSDL URLs that the TCK tests use when
running against the Sun RI. In the Sun porting package that the TCK uses,
the URLs are returned as is since this is the form that the Sun RI expects.
You may need an alternate form of these URLs in order to run the TCK tests
in your environment. However, you MUST NOT modify the <literal>jaxws-url-props.dat
</literal> file, but instead make any necessary changes in your own porting
implementation class to transform the URLs appropriately for your environment.</para>
</step>
</procedure>
</task>
</sect1>
<sect1 id="GCLHF"><title>Configuring Your Environment to Rebuild and Run the &TCKShortName; Against
the Sun RI</title>
<para>This section describes the steps needed to configure the &TCKShortName; so
that the tests can be rebuilt (using the Vendors Implementation toolset),
and then deployed and run against the Sun Reference Implementation.</para>
<para>If you are not ready to proceed with this portion of the testing process,
skip this section for now and proceed to <olink type="custom-text"
targetptr="GCFOI">Configuring and Starting Your Application Server(s)</olink>.
After configuring your environment, continue with the instructions in <olink
type="custom-text" targetptr="GBFUY">Using the JavaTest Harness Software</olink>.
</para>
<note>
<itemizedlist>
<listitem><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
XP/Vista. In addition, the forward slashes (<literal>/</literal>) used in all
of the examples need to be replaced with backslashes (<literal>\</literal>)
for Windows XP/Vista. 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></listitem>
<listitem><para>On Windows, you must escape any backslashes with an extra
backslash in path separators used in any of the following properties, or use
forward slashes as a path separator instead. For example, if the Sun Java EE 6 RI
 installation is <filename>C:\Sun\JavaEE6</filename>, you
must specify it as <filename>C:\\Sun\\JavaEE6</filename> or <filename>C:/Sun/JavaEE6
</filename>.</para></listitem>
</itemizedlist>
</note>
<task id="GCLHY"><title>To Configure Your Environment to Rebuild and Run Against
the Sun RI</title>
<procedure>
<step><para>The term Sun RI refers to the Sun Java EE 6 RI which
contains the &TechnologyShortName; RI implementation classes/jars.</para></step>
<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>ANT_HOME</literal> must be set to <filename>&lt;TS_HOME&gt;/tools/ant
</filename></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 hostname
where the web server for the Vendor Implementation is running.</para></step>
<step><para>Set the <literal>webServerPort</literal> property to the port
number where the web server for the Vendor Implementation is running.</para>
</step>
<step><para>Set the <literal>webServerHost.2</literal> property to the hostname
where the web server for the Sun RI is running.</para><para>The default setting
is <literal>localhost</literal>.</para></step>
<step><para>Set the <literal>webServerPort.2</literal> property to the port
number where the web server for the Sun RI is running.</para><para>The default
setting is <literal>8000</literal>.</para></step>
<step><para>Set the <literal>jaxws.home</literal> property to the location
where the Vendor Implementation is installed.</para></step>
<step><para>Set the <literal>jaxws.classes</literal> property to point to
the Vendors Implementation classes/jars.</para></step>
<step><para>Set the <literal>jaxws.home.ri</literal> property to the location
where the Sun RI is installed.</para></step>
<step><para>The <literal>jaxws.classes.ri</literal> property is already configured
to point to the Sun RI classes/jars.</para><para>No changes are necessary
for this property.</para></step>
<step><para>Set the <literal>wsgen.ant.classname</literal> property to the
Vendor Implementation class that mimics the Sun RI ant task, which in turn
calls the Sun <literal>wsgen</literal> Java-to-WSDL tool.</para></step>
<step><para>Set the <literal>wsimport.ant.classname</literal> property to
the Vendor Implementation class that mimics the Sun RI ant task, which in
turn calls the Sun <literal>wsimport</literal> WSDL-to-Java tool.</para></step>
<step><para>Set the <literal>impl.vi, impl.vi.deploy.dir, impl.vi.host, and
impl.vi.port</literal> properties to the supported web container, deploy directory,
host and port used for the Vendor implementation.</para></step>
<step><para>Set the <literal>impl.ri, impl.ri.deploy.dir, impl.ri.host, and
impl.ri.port</literal> properties to the supported web container, deploy directory,
host and port used for Sun Reference implementation.</para><para>The supported
web container for standalone web applications is the Sun Java EE 6 RI. 
So the default settings for these properties are as follows:</para>
<screen>impl.ri.deploy.dir=${webcontainer.home.ri}/domains/domain1/autodeploy
impl.ri=glassfish.xml
impl.ri.host=${webServerHost.2}
impl.ri.port=${webServerPort.2}</screen>
</step>
<step><para>Set the <literal>webcontainer.home</literal> property to the location
where the web container for the Vendor Implemenation is installed.</para></step>
<step><para>Set the <literal>webcontainer.home.ri</literal> property to the
location where the web container for the Sun Reference Implementation 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 points to the Sun RI porting implementation which is:</para>
<screen>com.sun.ts.lib.implementation.sun.common.SunRIURL</screen>
</step>
<step><para>Set the <literal>porting.ts.url.class.2</literal> property to
the Sun RI porting implementation class that is used for obtaining URLs.</para>
<para>No changes are necessary for this property.</para></step>
<step><para>Set the <literal>user</literal> and <literal>password</literal> properties
to the user name and password used for the basic authentication tests.</para>
<para>The default setting for both is <literal>j2ee</literal>.</para></step>
<step><para>Set the <literal>authuser</literal> and <literal>authpassword</literal> properties
to the user name and password used for the basic authentication tests.</para>
<para>The default setting for both is <literal>javajoe</literal>.</para></step>
<step><para>Set the <literal>http.server.supports.endpoint.publish</literal> property
based on whether Endpoint Publish APIs are supported on the container.</para>
</step>
<step><para>If using Java SE 6 or above, verify that the property <literal>endorsed.dirs
</literal> is set to the location of the VI API jars for those technologies
you wish to override.  Java SE 6 contains an implementation of &TechnologyShortName; 2.1
which will conflict with &TechnologyShortName; &TechnologyVersion;, therefore
this property must be set so that &TechnologyShortName; &TechnologyVersion; will
be used during the building of tests and during test execution.</para></step>
<step><para>If using Java SE 6 or above, verify that the property <literal>endorsed.dirs.ri
</literal> is set to the location of the RI API jars for those technologies
you wish to override.  Java SE 6 contains an implementation of &TechnologyShortName; 2.1
which will conflict with &TechnologyShortName; &TechnologyVersion;, therefore
this property must be set so that &TechnologyShortName; &TechnologyVersion; will
be used during the building of tests and during test execution.</para></step>
</substeps>
</step>
<step><para>Edit the catalog file <filename>&lt;TS_HOME>/bin/catalog/META-INF/jax-ws-catalog.xml
</filename>, replacing the host and port settings of <literal>systemId</literal> with
the value of your host and port setting where the WSDL is published.</para>
</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>
<step><para>The <filename>&lt;TS_HOME>/bin/jaxws-url-props.dat</filename> file
contains the webservice endpoint and WSDL URLs that the TCK tests use when
running against the Sun RI. In the Sun porting package that the TCK uses,
the URLs are returned as is since this is the form that the Sun RI expects.
You may need an alternate form of these URLs in order to run the TCK tests
in your environment. However, you MUST NOT modify the <literal>jaxws-url-props.dat
</literal> file, but instead make any necessary changes in your own porting
implementation class to transform the URLs appropriately for your environment.</para>
<para>Refer to <olink type="custom-text" targetptr="GCLIZ">Appendix B</olink> for
instructions on rebuilding the &TCKShortName;.</para></step>
</procedure>
</task>
</sect1>
<sect1 id="GCLIK"><title>Configuring Your Environment to Simultaneously Run
the &TCKShortName; Against the VI and the Sun RI</title>
<para>This section describes the steps needed to configure the &TCKShortName; so
that all tests can be run; forward tests against the Vendors Implementation
and reverse tests against the Sun Reference Implementation.</para>
<para>Since the &TCKShortName; needs to be tested against both the Sun Reference
Implementation and the Vendors Implementation, two separate Web servers need
to be configured. Two individual Web servers are required, and the same steps,
below, must be performed to configure each Web server.</para>
<para>If you are not going to perform this kind of testing at this time, skip
this section and proceed to <olink type="custom-text" targetptr="GCFOI">Configuring
and Starting Your Application Server(s)</olink>, otherwise perform the steps
described in the following sections:</para>
<itemizedlist>
<listitem><para><olink targetptr="GCLHU">Configuring Your Environment to Run
the JAX-WS TCK Against the Vendor Implementation</olink></para></listitem>
<listitem><para><olink targetptr="GCLHF">Configuring Your Environment to Rebuild
and Run the JAX-WS TCK Against the Sun RI</olink></para></listitem>
</itemizedlist>
</sect1>
<sect1 id="GCFOI"><title>Configuring and Starting Your Application Server(s)</title>
<para>Complete the following two procedures to configure your Application
server environments for RI and VI.</para>
<task id="GCFOC"><?Pub Dtl><title>To Configure the Vendor implementation as
your VI environment</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>ANT_HOME</literal> must be set to <filename>&lt;TS_HOME&gt;/tools/ant
</filename></para></step></substeps>
</step>
<step><para>Ensure <literal>ts.jte</literal> settings for Vendor specific
properties have been configured.</para></step>
<step><para>Run <literal>ant config.vi</literal> target to configure for Vendor
implementation.</para>
<screen>cd &lt;TS_HOME>/bin
&lt;ANT_HOME>/bin/ant config.vi</screen>
</step>
</procedure>
</task>
<task id="GCFFB"><?Pub Dtl><title>To Configure the Sun Reference implementation
as your RI environment</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>ANT_HOME</literal> must be set to <filename>&lt;TS_HOME&gt;/tools/ant
</filename></para></step></substeps>
</step>
<step><para>Ensure <literal>ts.jte</literal> settings for RI specific properties
have been configured.</para></step>
<step><para>Run <literal>ant config.ri</literal> target to configure for RI
implementation.</para>
<screen>cd &lt;TS_HOME>/bin
&lt;ANT_HOME>/bin/ant config.ri</screen>
</step>
</procedure>
</task>
</sect1>
<sect1 id="GCLIN"><title>Deploying the &TCKShortName; Tests</title>
<para>The &TCKShortName; provides an automatic way of deploying both the prebuilt
and Vendor-built archives to the configured web container(s) via deployment
handlers.</para>
<para>The handler file (<filename>&lt;TS_HOME>/bin/xml/impl/glassfish/deploy.xml</filename>
is written to be used with
the Sun Java EE 6 RI. If the Vendor chooses not to use Sun
Java EE 6 RI with their implementation, or chooses to rebuild
the &TCKShortName; tests using some other method than the infrastructure provided,
they should create their own version handler file to provide this functionality.</para>
<para>This section describes the various commands used for deploying the WAR
files to the configured web container.</para>
<itemizedlist remap="jumplist">
<listitem><para><olink targetptr="GCLJG">Generic Deployment Command Scenarios</olink></para>
</listitem>
<listitem><para><olink targetptr="GCLIW">Deploying the JAX-WS TCK Prebuilt
Archives</olink></para></listitem>
<listitem><para><olink targetptr="GCLIL">Deploying the Rebuilt JAX-WS TCK
Tests Against the Sun Reference Implementation</olink></para></listitem>
</itemizedlist>
<sect2 id="GCLJG"><title>Generic Deployment Command Scenarios</title>
<para>The <literal>keywords</literal> system property enables you to deploy
a subset of the tests that would normally be deployed in batch mode by means
of <command>&lt;ANT_HOME>/bin/ant deploy</command>. To specify it, add the
option <command>-Dkeywords=</command><varname>value</varname> to the <command>ant
</command> command, where <varname>value</varname> is either <literal>forward</literal>, <literal>
reverse</literal>, or <literal>all</literal>. The supported values control
the directions in which the  rebuildable tests are deployed.</para>
<itemizedlist>
<listitem><para>Setting this property to <literal>all</literal> (the default)
deploys both the prebuilt and vendor build tests.</para></listitem>
<listitem><para>Setting the property to <literal>forward</literal> deploys
the prebuilt tests in the forward direction only.</para></listitem>
<listitem><para>Setting the property to <literal>reverse</literal> deploys
the vendor rebuilt tests in the reverse direction only.</para></listitem>
</itemizedlist>
<task id="GCLJK"><title>To Deploy all the WAR Files From the <filename>&lt;TS_HOME>/dist
</filename> to Both Web Servers</title>
<procedure role="single-step">
<step><para>Enter the following command:</para>
<screen>&lt;ANT_HOME>/bin/ant deploy.all</screen>
<para>or</para>
<screen>&lt;ANT_HOME>/bin/ant -Dkeywords=all deploy.all</screen>
</step>
</procedure>
</task>
<task id="GCLII"><title>To Deploy a Single Test Directory in the Forward Direction
</title>
<procedure role="single-step">
<step><para>Enter the following commands:</para>
<screen>cd &lt;TS_HOME>/src/com/sun/ts/tests/jaxws/api/javax_xml_ws/Dispatch
&lt;ANT_HOME>/bin/ant -Dkeywords=forward deploy</screen>
</step>
</procedure>
</task>
<task id="GCLJC"><title>To Deploy a Subset of Test Directories in the Reverse
Direction</title>
<procedure role="single-step">
<step><para>Enter the following commands:</para>
<screen>cd &lt;TS_HOME>/src/com/sun/ts/tests/jaxws/api 
&lt;ANT_HOME>/bin/ant -Dkeywords=reverse deploy</screen>
<note><para>The <literal>-Dkeywords</literal> option is supported by the <command>
deploy</command>, <command>undeploy</command>, <command>deploy.all</command>,
and <command>undeploy.all</command> commands.</para></note>
</step>
</procedure>
</task>
</sect2>
<sect2 id="GCLIW"><?Pub Dtl><title>Deploying the &TCKShortName; Prebuilt Archives
</title>
<para>This section explains issues regarding the deployment of the &TCKShortName; prebuilt
archives. Before conducting any deployment, ensure that your environment has
been configured by following the instructions in either the <olink
type="custom-text" targetptr="GBFVU">Configuring Your Environment to run the
JAX-WS TCK against the Sun Reference Implementation</olink> or the <olink
type="custom-text" targetptr="GCLHU">Configuring Your Environment to run the
JAX-WS TCK Against the Vendor Implementation</olink> sections.</para>
<para>The <filename>&lt;TS_HOME>/dist</filename> directory contains all the
WAR files for the &TCKShortName; web service endpoint tests that have been
compiled and generated using the Sun Reference Implementation and packaged
for deployment on a Servlet 2.4-compliant web container using the standard
Web Archive (WAR) format.</para>
<para>These WAR files contain only portable artifacts for all the TCK web
service endpoint tests, and are tailored to run against the Sun Reference
Implementation via the <filename>web.xml</filename> file in addition to a
runtime file <filename>sun-jaxws.xml</filename>. These WAR files allow you
to deploy (without any additional setup or modification) against the Sun Reference
Implementation to test the various features and functionality of this implementation.
</para>
<para>A vendor is required to deploy the prebuilt WAR files as is on their &TechnologyShortName; implementation
without any changes to the WAR archives with the exception of replacing and/or
removing only the <filename>web.xml</filename> and the <filename>sun-jaxws.xml</filename> files.
</para>
<para>To deploy the tests, the vendor should perform a deployment using either
the deploy or deployall batch command as described in the <olink
type="custom-text" targetptr="GCLJG">Generic Deployment Command Scenarios</olink>,
and specify the <literal>-Dkeywords=forward</literal> option.</para></sect2>
<sect2 id="GCLIL"><?Pub Dtl><title>Deploying the Rebuilt &TCKShortName; Tests
Against the Sun Reference Implementation</title>
<para>This section describes how to deploy the Vendor rebuilt &TCKShortName; tests
against the Vendor Implementation. Before conducting the deployment, ensure
that you have followed the instructions ins <olink type="custom-text"
targetptr="GBFVU">Configuring Your Environment to run the JAX-WS TCK against
the Sun Reference Implementation</olink>.</para>
<para>This deployment scenario assumes that the Vendor has rebuilt all the &TCKShortName; tests
using the existing infrastructure, and that the WAR files exist alongside
the Sun prebuilt war files in the <filename>&lt;TS_HOME>/dist</filename> directory.
The rebuilt WAR files will be prepended with the text <literal>vi_built_</literal>.
</para>
<para>If the Vendor chooses some other method of rebuilding the tests, they
may still be able to use this deployment method as long as the WAR files are
built correctly and are prepended with the text <literal>vi_built_</literal>.
Refer to the <olink type="custom-text" targetptr="GCLIZ">Appendix B</olink> to
learn about rebuilding the &TCKShortName; tests.</para>
<para>To deploy the tests, the vendor should perform a deployment using either
the <command>deploy</command> or <command>deployall</command> batch command,
as described in the <olink targetptr="GCLJG">Generic Deployment Command Scenarios
</olink> section, and specify the <literal>-Dkeywords=reverse</literal> option</para>
</sect2>
</sect1>
<sect1 id="GBFUY"><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"><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 remap="jumplist">
<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"><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></literallayout>
<literallayout><command>&lt;ANT_HOME>/bin/ant 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>
