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

  <properties>
    <title>Migration Howto</title>
  </properties>

  <body>

    <section title="From Cactus 1.4.1 to newer version">

      <p>
        Release notes are now provided in the distribution in an
        ANNOUNCEMENT.txt file. Please make sure you read it.
      </p>

    </section>
    
    <section title="From Cactus 1.3 to 1.4">

      <p>
        See the 
        <jump href="site:changes" anchor="release_changes">Changes</jump> 
        page for full list of changes.
      </p>
      <p>
        Here are the changes that might affect your previous installation of
        Cactus 1.3:
      </p>
      <ul>
        <li>
          Configuring Cactus logging has changed. See the
          <link href="site:howto_config">Config Howto</link> page. Thus, the old
          <code>cactus.enableLogging</code> property no longer has any effect.
        </li>
        <li>
          One new jar needs to be put in both client and server side classpaths:
          <code>commons-logging.jar</code>, due to the new logging system.
        </li>
        <li>
          The following classes have been removed (they were
          deprecated in Cactus 1.2):
          <ul>
            <li>
              <code>org.apache.cactus.ServletTestRequest</code>,
            </li>
            <li>
              <code>org.apache.cactus.util.ClientCookie</code>,
            </li>
            <li>
              <code>org.apache.cactus.util.AssertUtils</code>
            </li>
          </ul>
        </li>
        <li>
          External jars provided by Cactus have been renamed to contain their
          version suffixed to their name.
        </li>
        <li>
          The <code>jspRedirector.jsp</code> now creates a HTTP Session by
          default (it was not previously).
        </li>
      </ul>

    </section>

    <section title="From Cactus 1.2 to 1.3">

      <p>
        Here are the steps to migrate from Cactus 1.2 to 1.3
      </p>

      <note>
        This migration guide does not explain any of the new feature of
        Cactus 1.3 but concentrates on making you move from Cactus 1.2 to 1.3.
      </note>

      <p>
        Let's call <code>CACTUS_HOME</code> the directory where you unzipped
        the Cactus distribution.
      </p>

      <p>
        Follow these steps:
      </p>
      
      <section title="Step 1">

        <p>
          Put <code>aspectjrt.jar</code> (found in
          <code>CACTUS_HOME/lib</code>) in both your client side and server
          side classpaths.
        </p>

      </section>

      <section title="Step 2">

        <p>
          Modify your <code>cactus.properties</code> to the new format. For
          example:
        </p>
<source><![CDATA[
cactus.contextURL = http://localhost:8000/cactus
cactus.servletRedirectorName = ServletRedirector
]]></source>

      </section>

      <section title="Step 3">

        <p>
          Ensure that <code>cactus.servletRedirectorName</code> does not end
          with a "/" and that the mapping in <code>web.xml</code> matches it:
        </p>
<source><![CDATA[
    <servlet-mapping>
        <servlet-name>ServletRedirector</servlet-name>
        <url-pattern>/ServletRedirector</url-pattern>
    </servlet-mapping>
]]></source>

      </section>

      <p>
        The Cactus sample is supposed to work with Ant 1.4. However, we
        introduced an incompatibility at the last moment (i.e. a feature only
        supported by Ant 1.5). If you're using Ant 1.4, simply remove the
        failing line (it is an optional line).
      </p>

    </section>

  </body>
</document>
