<?xml version="1.0"?>

<!--
 * ========================================================================
 * 
 * Copyright 2001-2004 The Apache Software Foundation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *   http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * 
 * ========================================================================
-->

<document id="howto_ide_vajava_wte">

  <properties>
    <title>VAJava and WebSphere Test Environment</title>
  </properties>

  <body>

    <section title="Forewords and Requirements">

      <note>
        <strong>This tutorial is written for Cactus 1.2 only. It will need
        to adapted if you're using Cactus 1.3</strong>
      </note>

      <p>
        This tutorial explains how to run Cactus tests within VisualAge for
        Java WebSphere Test Environment.
      </p>
      <p>
        We have received reports that the following tutorial works with
        VAJava 3.5.2 and 3.5.3. Please tell us if you find that it works with
        other versions.
      </p>

    </section>

    <section title="Step 1: Import the correct packages in VAJava">

      <p>
        Let's assume the following conventions:
        <strong><code>{Cactus dir}</code></strong> is the directory where you
        have unzipped the Cactus distribution or sources and
        <strong><code>{VAJava dir}</code></strong> is the directory where
        VAJava is installed. Let's also define <strong><code>{WTE dir}</code>
        </strong> to be the WebSphere Test Environment directories, i.e.
        <code>{VAJava dir}/ide/project_resources/IBM WebSphere Test
        Environment</code>.
      </p>

      <p>
        You need to create 4 projects: one for JUnit, one for Cactus (
        let's call it "Cactus"), one for HttpClient and
        optionally one for Log4j. Note that the Log4j one is useful only if
        wish to get some Cactus runtime logs. If you don't import the Log4j
        classes, some Cactus classes will appear with a red cross in VAJava
        but you can safely ignore them as they won't be executed.
      </p>

      <note>
        You can either import the source files or the compiled classes as you
        wish. If you import the source file, you should import the following
        directories: <code>{Cactus dir}/src/framework/servlet22</code> and
        <code>{Cactus dir}/src/framework/share</code>. You also need to
        copy the following files into
        <code>{VAJava dir}/ide/project_resources/Cactus</code>:
        <code>log_client.properties</code> and
        <code>log_server.properties</code> which are located in
        <code>{Cactus dir}/sample/conf/test</code>. If you have imported from
        the Cactus jar file, and you have selected to import resources files
        then they have been automatically imported for you.
      </note>

    </section>

    <section title="Step 2: Set up the cactus.properties file">

      <p>
        Copy your <code>cactus.properties</code> file (see the
        <link href="site:howto_config">Configuration Howto</link>
        tutorial for details on <code>cactus.properties</code>) to
        <code>{VAJava dir}/ide/project_resources/Cactus</code>.
      </p>

      <note>
        As WebSphere does not support the <code>jsp-file</code> tag in
        <code>web.xml</code>, we cannot map the redirector JSP to a name, so
        instead of writing
        "<code>cactus.jspRedirectorURL =
        http://localhost:8080/test/JspRedirector</code>" in
        <code>cactus.properties</code>, you should simply
        put the JSP file name, as in
        "<code>cactus.jspRedirectorURL =
        http://localhost:8080/test/jspRedirector.jsp</code>". This is only needed
        if you have test cases that extend <code>JspTestCase</code>.
      </note>

    </section>

    <section title="Step 3: Modify WebSphere Test Environment">

      <section title="Edit default.servlet_engine">

        <p>
          Edit <code>{WTE dir}/properties/default.servlet_engine</code> and
          add the following under the <code>default_app</code> webgroup:
        </p>

<source><![CDATA[
    <websphere-webgroup name="test">
       <description>Cactus Testing Web Application</description>
       <document-root>$approot$/web</document-root>
       <classpath>$approot$/servlets</classpath>
       <root-uri>/test</root-uri>
       <auto-reload enabled="true" polling-interval="3000"/>
       <shared-context>false</shared-context>
    </websphere-webgroup>
]]></source>

        <note>
          The <code>init-parameter</code> is only needed if you wish to run
          sample application provided in the Cactus distribution. Also, in
          order to run this sample application you'll need to copy the
          <code>{Cactus dir}/sample/web/test/test.jsp</code> file to
          <code>{WTE dir}/hosts/default_host/test/web/test</code> as it is
          used by a test case.
        </note>

      </section>

      <section title="Create a test directory">

        <p>
          Create a directory called <code>test</code> under
          <code>{WTE dir}/hosts/default_host</code>. Under <code>test</code>
          create another 2 subdirectories: <code>servlets</code> and
          <code>web</code>.
        </p>

      </section>

      <section title="Create a test.webapp file">

        <p>
          Create a test.webapp file in
          <code>{WTE dir}/hosts/default_host/test/servlets</code> and put the
          following content:
        </p>

<source><![CDATA[
<?xml version="1.0"?>
<webapp>
   <name>test</name>
   <description>Cactus testing web application</description>
   <error-page>/ErrorReporter</error-page>

   <servlet>
      <name>ServletRedirector</name>
      <description>Cactus Testing ServletRedirector</description>
      <code>org.apache.cactus.server.ServletTestRedirector</code>
      <servlet-path>/ServletRedirector</servlet-path>
      <autostart>false</autostart>
      <init-parameter>
        <name>param1</name>
        <value>value1 used for testing</value>
    </init-parameter>
   </servlet>

   <!-- Note: We don't provide a mapping for the JSP Redirector because
        WebSphere does not support the jsp-file tag of the Servlet 2.2
        specification -->

   <servlet>
      <name>ErrorReporter</name>
      <description>Default error reporter servlet</description>
      <code>com.ibm.servlet.engine.webapp.DefaultErrorReporter</code>
      <servlet-path>/ErrorReporter</servlet-path>
      <autostart>true</autostart>
   </servlet>

   <servlet>
      <name>jsp</name>
      <description>JSP support servlet</description>

      <!--
        WARNING:

        If you use the JSP 1.0 compiler, use the following
          <code>com.ibm.ivj.jsp.runtime.JspDebugServlet</code>

        If you use the JSP 1.1 compiler (VAJava 3.5.3 only), use the following
          <code>com.ibm.ivj.jsp.jasper.runtime.JspDebugServlet</code>
      -->
      <code>com.ibm.ivj.jsp.jasper.runtime.JspDebugServlet</code>

      <init-parameter>
         <name>workingDir</name>
         <value>$server_root$/temp/default_app</value>
      </init-parameter>
      <init-parameter>
         <name>jspemEnabled</name>
         <value>true</value>
      </init-parameter>
      <init-parameter>
         <name>scratchdir</name>
         <value>$server_root$/temp/JSP1_1/default_app</value>
      </init-parameter>
      <init-parameter>
         <name>keepgenerated</name>
         <value>true</value>
      </init-parameter>
      <autostart>true</autostart>
      <servlet-path>*.jsp</servlet-path>
   </servlet>

   <servlet>
      <name>file</name>
      <description>File serving servlet</description>
      <code>com.ibm.servlet.engine.webapp.SimpleFileServlet</code>
      <servlet-path>/</servlet-path>
      <init-parameter>
         <name></name>
         <value></value>
      </init-parameter>
      <autostart>true</autostart>
   </servlet>
</webapp>
]]></source>

      </section>

      <section title="Copy the Cactus JSP Redirector file">

        <p>
          Copy the <code>{Cactus dir}/sample/web/test/jspRedirector.jsp</code>
          file to <code>{WTE dir}/hosts/default_host/test/web</code>.
        </p>

      </section>

    </section>

    <section title="Step 4: Edit VAJava workspace classpath">

      <p>
        Add the following to the VAJava workspace classpath (select menu
        "Window... | Resources" under VAJava):
      </p>

<source><![CDATA[
{VAJava dir}\ide\project_resources\JUnit\;
{VAJava dir}\ide\project_resources\Cactus\;
{VAJava dir}\ide\project_resources\HttpClient\;
{VAJava dir}\ide\project_resources\Log4j\;
{VAJava dir}\ide\project_resources\Servlet API Classes\;
]]></source>

    </section>

    <section title="Step 5: Edit VAJava workspace classpath">

      <p>
        In the WebSphere Test Environment under Servlet Engine, add Cactus,
        JUnit, HttpClient, Log4j, and the project that contained the tests to
        the classpath.
      </p>

    </section>

    <section title="Final note">

      <note>
        With this configuration, you'll find <code>cactus_client.log</code>
        under <code>{VAJava dir}/ide/project_resources/{project being
        tested}</code> and <code>cactus_server.log</code> under
        <code>{VAJava dir}/ide/tools/com-ibm-ivj-ui-webcontrolcenter</code>
        when you run your tests.
      </note>

      <note>
        If you get a "Failed to invoke suite():
        java.lang.NoClassDefFoundError" error message, you msy get around that
        problem by explicitly adding the test cases to the TestSuite that's
        returned in suite(), for your test case.
      </note>

    </section>

  </body>
</document>
