<!-- 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(book(title()subtitle()bookinfo()chapter()appendix()>
<appendix id="GCLIZ"><title><?Pub Caret>Packaging the &TCKShortName; Test
Applications in Servlet-Compliant WAR Files With VI-Specific Information</title>
<highlights>
<para>The &TechnologyShortName; &TechnologyVersion; specification specifies
how &TechnologyShortName; applications are to be published in a Java SE environment,
JAX-WS endpoint, or Servlet&ndash;compliant Web container.</para>
<para>&TCKShortName; test application classes that are to be published in
a Java SE environment are located under <filename>$TS_HOME/classes</filename>.</para>
<para>The &TCKShortName; comes with prebuilt test WAR files for deployment
on &J2EEversion; RI , which provides a Servlet&ndash;compliant Web container.
The WAR files are Jersey-specific, with Jersey's servlet class and Jersey's
servlet defined in the <literal>web.xml</literal> deployment descriptor. To
run the TCK tests against the VI in a Servlet&ndash;compliant Web container,
 the tests need to be repackaged to include the VI-specific servlet, and the
VI-specific servlet must be defined in the deployment descriptor.</para>
<para>The &TCKShortName; makes it easier for the vendor by including template
WAR files that contain all of the necessary files except for the VI-specific
servlet adaptor class. The &TCKShortName; provides a tool to help with the
repackaging task.</para>
<para>This appendix contains the following sections:</para>
<itemizedlist remap="jumplist">
<listitem><para><olink targetptr="GCLIO">Overview</olink></para></listitem>
<listitem><para><olink targetptr="GCLLW">Creating the &TCKShortName; VI-Specific
Servlet&ndash;Compliant WAR Files</olink></para></listitem>
</itemizedlist>
</highlights>
<sect1 id="GCLIO"><title>Overview</title>
<para>The set of prebuilt archives and classes that ship with the &TCKShortName; were
built using the Sun Reference Implementation, and must be deployed on &J2EEversion; RI
 and run against the Jersey RI.</para>
<para>The prebuilt Jersey-specific Servlet&ndash;compliant WAR files are located
under <filename><replaceable>$TS_HOME</replaceable>/dist</filename>, and have <filename>
jersey</filename> as part of their name; for example:</para>
<screen>$TS_HOME/dist/com/sun/ts/tests/jaxrs/ee/rs/getTest/jaxrs_rs_getTest_web.war.jersey
</screen>
<para>The names are made unique by including <filename>jersey</filename> to
minimize the chances that the files will be overwritten or modified.</para>
<para>The Vendor must create VI-specific Servlet&ndash;compliant WAR files
if the Vendor chooses to publish on a Servlet&ndash;compliant Web container,
so that the VI-specific Servlet  class will be included instead of the Jersey-specific
Servlet class.</para></sect1>
<sect1 id="GCLLW"><title>Creating the &TCKShortName; VI-Specific Servlet&ndash;Compliant
WAR Files</title>
<para>All resource and application class files are already compiled. The Vendor
needs to package these files. All tests also come with a <filename>web.xml.template
</filename> file to be used for generating deployment descriptor files with
a VI-specific Servlet definition.</para>
<para>Each test that has a &TechnologyShortName; resource class to publish
comes with a template deployment descriptor file. For example, the file <filename>
$TS_HOME/src/com/sun/ts/tests/jaxrs/ee/rs/getTest/web.xml.template</filename> contains
the following elements:</para>
<screen>&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" \
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" \
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee \
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
    &lt;servlet>
        &lt;servlet-name>CTSJAX-RSGET&lt;/servlet-name>
        &lt;servlet-class>servlet_adaptor&lt;/servlet-class>
        &lt;init-param>
            &lt;param-name>javax.ws.rs.Application&lt;/param-name>
            &lt;param-value>com.sun.ts.tests.jaxrs.ee.rs.getTest.TSAppConfig&lt;/param-value>
        &lt;/init-param>
        &lt;load-on-startup>1&lt;/load-on-startup>
    &lt;/servlet>
    &lt;servlet-mapping>
        &lt;servlet-name>CTSJAX-RSGET&lt;/servlet-name>
        &lt;url-pattern>/*&lt;/url-pattern>
    &lt;/servlet-mapping>
    &lt;session-config>
        &lt;session-timeout>30&lt;/session-timeout>
    &lt;/session-config>
&lt;/web-app>

</screen>
<para>In this example, the <literal>&lt;servlet-class></literal> element has
a value of <literal>servlet_adaptor</literal>, which is a placeholder for
the implementation-specific Servlet class. A Jersey-specific deployment descriptor
also comes with the &TCKShortName;, and has the values for the <literal>com.sun.jersey.spi.container.servlet.ServletContainer
</literal>:</para>
<screen>&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee" \
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" \
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee \
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
   &lt;servlet>
        &lt;servlet-name>CTSJAX-RSGET&lt;/servlet-name>
        &lt;servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer&lt;/servlet-class>
        &lt;init-param>
            &lt;param-name>javax.ws.rs.Application&lt;/param-name>
            &lt;param-value>com.sun.ts.tests.jaxrs.ee.rs.getTest.TSAppConfig&lt;/param-value>
        &lt;/init-param>
        &lt;load-on-startup>1&lt;/load-on-startup>
    &lt;/servlet>
    &lt;servlet-mapping>
        &lt;servlet-name>CTSJAX-RSGET&lt;/servlet-name>
        &lt;url-pattern>/*&lt;/url-pattern>
    &lt;/servlet-mapping>
    &lt;session-config>
        &lt;session-timeout>30&lt;/session-timeout>
	    &lt;/session-config>
&lt;/web-app></screen>
<para>The &TCKShortName; provides a tool, <literal>${ts.home}/bin/xml/impl/glassfish/jersey.xml
</literal>, for the &J2EEversion; RI that you can use as a model to help you
create your own VI-specific Web test application.</para>
<task id="GCLMA"><title>To Create a VI-Specific Deployment Descriptor</title>
<procedure>
<step><para>Create a VI handler file.</para><para>Create a VI-specific handler
file <filename>$TS_HOME/bin/xml/impl/${<replaceable>impl.vi</replaceable>}/<replaceable>
jaxrs_impl_name</replaceable>.xml</filename> if one does not already exist.
Make sure the <literal>jaxrs_impl_name</literal> property is set in the <literal>
ts.jte</literal>, file and that it has a unique name so no file will be overwritten.
</para></step>
<step><para>Set the VI Servlet class property.</para><para>Set the <literal>servlet_adaptor
</literal> property in the <filename>ts.jte</filename> file. This property
will be used to set the value of the <literal>&lt;servlet-class&gt;</literal> element
in the deployment descriptor.</para></step>
<step><para>Create VI Ant tasks.</para><para>Create a <literal>update.jaxrs.wars</literal> target
in the VI handler file. Reference this <literal>update.jaxrs.wars</literal> target
in the <filename>jersey.xml</filename> file.</para><para>This target will
create a <filename>web.xml.${<replaceable>jaxrs_impl_name</replaceable>}</filename> for
each test that has a deployment descriptor template. The <filename>web.xml.${<replaceable>
jaxrs_impl_name</replaceable>}</filename> will contain the VI-specific Servlet
class name. It will also create the test WAR files will be created under <filename>
$TS_HOME/dist</filename>; for example:</para>
<screen>ls $TS_HOME/dist/com/sun/ts/tests/jaxrs/ee/rs/getTest/ \
jaxrs_rs_getTest_web.war.jersey
jaxrs_rs_getTest_web.war.${impl_name}</screen>
</step>
<step><para>Change to the <filename>$TS_HOME/bin</filename> directory and
execute the <literal>update.jaxrs.wars</literal> Ant target. </para><para>This
creates a <filename>web.xml.<replaceable>VI_name</replaceable></filename> file
for each test based on the VI's servlet class name and repackage the tests.</para>
</step>
</procedure>
</task>
</sect1>
</appendix>
<?Pub *0000008291 0>
