<?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_jbuilder4">

  <properties>
    <title>JBuilder 4 Integration</title>
  </properties>

  <body>

    <section title="Forewords and Requirements">
      <p>
        First of all, you need to download the
        <link href="site:downloads">Cactus distribution</link>
      </p>
    </section>

    <section title="Step 1: Create JBuilder libraries">

      <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.
        Let's also assume <strong><code>{Tomcat dir}</code></strong> to be the Tomcat directory.
      </p>

      <figure src="images/jb_libraries.gif" alt="jbuilder libraries" />

      <section title="Create the JUnit library">

        <p>
          Create a JUnit library and include <code>junit.jar</code>.
        </p>

      </section>

      <section title="Create the Cactus library">

        <p>
          Create a Cactus library containing <code>cactus.jar</code> and
          <code>aspectjrt.jar</code> (you can actually create a separate
          library for AspectJ if you wish).
        </p>

        <note>
          You can also add the source file directories in the source tab.
          This way, you will be able to debug inside cactus sources.
        </note>

      </section>

      <section title="Create the tomcat library">
        <p>
          Create another library named <code>tomcat</code>
          and add all the jar files from <code>{Tomcat dir}/lib</code>.
        </p>

        <note>
          If you use JBuilder 4 Enterprise or JBuilder 4 Professionnal, you don't need to create
          this library because Tomcat 3.1 is provided with those versions.
        </note>

      </section>
    </section>

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

      <p>
        Edit a new file named <code>cactus.properties</code>
        (see the <link href="site:howto_config">Configuration Howto</link>
        tutorial for more details on <code>cactus.properties</code>).
      </p>
      <p>
        Copy your <code>cactus.properties</code> file to a directory present
        in your classpath. You can copy it to a directory and add this
        directory in the class tab of the cactus library.
      </p>

    </section>

    <section title="Step 3: Configure Tomcat Environment">

      <section title="Create a cactus webapp">

        <p>
          Create and edit the file
          <code>{Tomcat dir}/webapps/cactus/WEB-INF/web.xml</code>. Here is an
          example for Servlet API 2.2:
        </p>

<source><![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE web-app
    PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"
    "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

<web-app>
    <servlet>
        <servlet-name>ServletRedirector</servlet-name>
        <servlet-class>org.apache.cactus.server.ServletTestRedirector</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>ServletRedirector</servlet-name>
        <url-pattern>/ServletRedirector</url-pattern>
    </servlet-mapping>
</web-app>
]]></source>

      </section>

      <note>
        You can edit <code>{Tomcat dir}/conf/web.xml</code> instead if you
        prefer. <br/>
        You can also edit the <code>web.xml</code> file of the webapp where is
        located the servlet(s) you want to test. <br/>
        Don't forget to modify <code>cactus.properties</code> file accordingly.
      </note>
    </section>

    <section title="Step 4: Configure your project">
      <ol>
        <li>
          Put <code>-classic -Dtomcat.home="{Tomcat dir}"</code> as the VM
          parameters for your project and
          <code>org.apache.tomcat.startup.Tomcat</code> as the main class.
        </li>
        <li>
          Add the following libraries in the <code>Required Libraries</code>
          tab in the project properties:
          <ul>
            <li>tomcat</li>
            <li>servlet</li>
            <li>junit</li>
            <li>cactus</li>
          </ul>
          <figure src="images/jb_paths.gif" alt="jbuilder libraries" />
        </li>
      </ol>
    </section>

    <section title="Step 5: Test and debug your servlet">

      <section title="Test your servlet">
        <ol>
          <li>
            Start Tomcat using the <code>Run/Run Project</code> menu.
          </li>
          <li>
            Run your unit tests: right click on the file containing your test
            case and click on <code>run</code>
          </li>
        </ol>
      </section>

      <section title="Debug your servlet and your tests">
        <p>
          You can easily print the results of the methods on the server-side
          itself.
        </p>
        <p>
          You can also start Tomcat in debug mode (<code>Run/debug
          project</code>). This way, you can stop at breakpoints on methods
          that are executed on the server side (<code>void testXXX()</code> for
          example)
        </p>
        <p>
          If you right click on the file containing your test case and click
          on <code>debug</code>, you can stop at breakpoints on methods that
          are executed on the client side like
          <code>void endXXX(WebResponse)</code> or
          <code>void beginXXX(WebRequest)</code>
        </p>
      </section>
    </section>

  </body>
</document>
