/opt/hpws22/tomcat/hpws_docs/tomcat6.migration.guide

		hp-ux web server suite

Migration Guide for HP-UX Tomcat-based Servlet Engine

TABLE OF CONTENTS
Objective
Migration from HP Tomcat 4.1.29 to HP Tomcat 5.5.x
Migration from HP Tomcat 5.5.x to HP Tomcat 6.0.x
Will it be difficult ?
Runtime Dependencies
Debugging and Error Logging
Legal Notices

OBJECTIVE
This migration guide will aid you in migrating your applications from
HP-UX Tomcat 4.1.29 to (Tomcat 6.0.35) and HP-UX Tomcat 5.5.x to (Tomcat 6.0.35). Additionally
we will discuss some configuration changes that need to be made
when migrating from HP-UX Tomcat version 4.1.29.x to HP-UX Tomcat-based Servlet
Engine (Tomcat 6.0.35) and HP-UX Tomcat 5.5.x to (Tomcat 6.0.35).

This guide however, does not cover issues related to different servlet
specifications. Tomcat 6.0.x implements Servlet 2.5 and JSP 2.1 specifications,
whereas Tomcat 4.x implement Servlet 2.3 and JSP 1.2 specs, Tomcat 5.5.x implement Servlet 2.4 and JSP 2.0 specs.
For differences on these specs see http://www.javaworld.com/javaworld/jw-03-2003/jw-0328-servlet.html

Full Servlet specification can be found at http://java.sun.com/products/servlet
and JSP at http://java.sun.com/products/jsp.

MIGRATION FROM HP TOMCAT 4.1.29 to HP TOMCAT 5.5.x

Will it be difficult ?

If you have maintained a clean, specification-compliant webapp, your upgrade may be as simple as "rebuild" and "adjust the config files".

1.1 Tomcat 5 implements newer versions of the servlet and JSP specs

Rebuild your application using JDK 1.4.x, if you're not already using it.
The newer JDK is a Tomcat 6 requirement. Be sure to check for deprecated
methods.

As Tomcat 5 implements newer versions of the servlet and JSP specifications,
you must rebuild your applications against the newer JAR files provided
with Tomcat 5. Also check for deprecations as some interfaces and methods
have been deprecated. Please note that the servlet and jsp api jar files are
renamed as servlet-api.jar and jsp-api.jar.

For compiling with newer jar files, do the following:

In your build $CLASSPATH, replace any references to

/opt/hpws22/tomcat/common/lib/servlet.jar
/opt/hpws22/tomcat/common/lib/jsp.jar
with
/opt/hpws22/tomcat/common/lib/servlet-api.jar
/opt/hpws22/tomcat/common/lib/jsp-api.jar

Note: There have been some changes to the servlet specification between 2.3 and 2.4;
for example, SingleThreadModel has been deprecated. Review the specification to make
sure you don't have to make any code-level changes.

1.2 Changes in the Configuration files

The <Connector> element in server.xml has changed.

Tomcat 4:

Tomcat 5:

Note that the "className" attribute is not required, specifying
protocol="HTTP/1.1" indicates that the HTTP connector is to be used.

NOTE: The JK2/Coyote Connector used for connecting to mod_jk2 is no more valid in Tomcat 5.5.x.
Its functionality is incorporated into AJP 1.3 connector.

When using mod_jk2, you need to specify which jk2 properties file to use by Tomcat.
For this use "propertiesFile" attribute as shown below in the AJP 1.3 connector element.

<Connector port="8009" propertiesFile="conf/jk2.properties"
enableLookups="false" redirectPort="8443" protocol="AJP/1.3" />

The Serverwide web.xml and catalina.policy have changed. If you use the single Tomcat
install (all of your webapps are under the Tomcat install directory), your webapp will
pick this up automatically. If, instead, you use multiple Tomcat instances
($CATALINA_BASE vs $CATALINA_HOME), you must copy the new file to $CATALINA_BASE/conf.

1.3 Compile JSP Using Eclipse JDT

HP-UX Tomcat 5.5 uses the Eclipse JDT Java compiler for compiling JSP pages.
This means you no longer need to have the complete Java Development Kit (JDK)
to run Tomcat, but a Java Runtime Environment (JRE) is sufficient. The Eclipse JDT
Java compiler is bundled with the HP-UX Tomcat engine. Tomcat can also be
configured to use the compiler from the JDK to compile JSPs, or any other
Java compiler supported by Apache Ant.

1.4 All Classes needs to be packaged

If your app uses packageless classes -- that is, you use bare ClassName and
not some.package.ClassName -- you must package them. This is required by the
servletspec 2.4, and Tomcat enforces it.

1.5 JARs not included with this version

The JavaMail JARs -- such as activation.jar and mail.jar -- are no longer
included with Tomcat. Depending on your needs you can download them from Sun
or simply copy them to from your old Tomcat install, into /opt/hpws22/tomcat/common/lib.

1.6 Use of context.xml for context-specific settings

It is encouraged that context-specific settings be placed in context.xml
and not in the serverwide server.xml. The context.xml contains a raw <Context> element.
It permits you to change per-webapp settings without disturbing the global server.xml file.
For more information on how to make context level settings please visit:
http://jakarta.apache.org/tomcat/tomcat-5.5-doc/config/context.html

1.7 New XML parser

Tomcat 5 includes a newer, pickier XML parser (Xerces 2.6.0). If you suddenly
encounter problems parsing XML, this is the place to look.

1.8 JSP 2.0's new rule for jsp:useBean usage

JSP spec 2.0 adds a rule that may conflict with your use of <jsp:useBean>:
if the specified object is not found in the specified context, containers may throw
an exception or attempt to create the object using the default (no-args) constructor.
If the object doesn't have a no-args constructor, problems will ensue.
Tomcat will fail to compile the page, because it cannot instantiate the object.
(Refer to Tomcat Bugzilla ID 26444)

MIGRATION FROM HP TOMCAT 5.5.x to HP TOMCAT 6.0.x

Java 5 required
Apache Tomcat 6.0.x requires Java 5 or later, unlike Apache Tomcat 5.5.x which could use a compatibility
package to run on JRE 1.4.1.

Modified directory structure

1.1 Shared libraries
HP-UX Tomcat 5.5.x used, by default, a directory structure including common, shared and
server subdirectories. HP-UX Tomcat 6.0.x uses a single lib directory.
The lib directory is the direct replacement for both common/lib and common/classes
subdirectories: it accepts both JARs and exploded class hierarchies. The conf/catalina.properties
file can be used to modify the directory structure. Starting with version 6.0.21, Apache Tomcat support
both the $CATALINA_BASE/lib and $CATALINA_HOME/lib directories. The jars and classes in
$CATALINA_BASE/lib are earlier on the class path and thus take precedence.

1.2 Endorsed libraries
The $CATALINA_HOME/common/endorsed subdirectory is replaced by the $CATALINA_HOME/endorsed directory.
This directory is absent by default. The JAVA_ENDORSED_DIRS environment variable can be used with catalina.bat|sh
scripts to provide alternative location of this directory.

1.3 Default web applications
The Manager and Host Manager web applications are no longer in server/webapps.
All of the default web applications are now located in the webapps directory.
Note, that if deployOnStartup or autoDeploy options on the Host are enabled, the META-INF/context.xml files
of manager and host-manager applications will be copied into the $CATALINA_BASE/conf/[engine_name]/[host_name]
directory when Tomcat starts for the first time.
When using a shared webhosting environment, it is recommended to forbid the use of context.xml inside
the web applications (using the deployXML attribute of the Host element). (This option is also available in Tomcat 5.5).

2. Modified classloading
As a result of the modification of the directory structure, the common, shared and server classloaders have
been merged into one. Effectively, the shared and server classloaders are not configured by default and the common
classloader is mapped to the lib directory, as described above.
This behavior and structure can be modified using the conf/catalina.properties file.

3. Internal Logging API package renaming
HP-UX Tomcat 5.5.x relied on the Apache Commons Logging library for its internal logging. HP-UX Tomcat 6.0.x
and later no more uses the library directly, but uses a private copy of it.
The classes are in the org.apache.juli.logging package.
The rationale behind this change is that so that application logging can be as independent as
possible from the container,
while still having the possibility of being unified.
By default only a subset of Apache Commons Logging classes that are needed to perform logging to java.util.logging is
included with Tomcat. If you want to configure Tomcat to redirect its logging into Log4J, or any other logging framework
supported by the full Apache Commons Logging library, you will have to replace one of Tomcat JARs with
the full implementation.
The JAR is available as an extras component. See the logging and extras documentation for more details.
4. commons-logging.jar
As Apache Tomcat no longer directly uses the Apache Commons Logging library, the commons-logging-api.jar
library is no longer provided for the web applications. The web applications that use Apache Commons Logging
have to provide their own copy of that library. It is recommended to put it into their WEB-INF/lib directory,
like any other JAR.
5. SSLEnabled attribute on Connector
For all SSL enabled connectors, the SSLEnabled flag must be set to true to enable encryption.
Tomcat no longer relies on using the protocol and other parameters to determine if the transport should
be encrypted, to give maximum flexibility in proxied scenarios.
6. Connector thread pools
The Connector thread pools have been simplified. They now grow to the maximum size specified but never shrink.
The attributes associated with shrinking the thread pool (e.g. minSpareThreads) will be ignored. If you require a thread
pool that grows and shrinks with demand you'll need to configure an Executor and then configure your Connector to use it.
7. Clustering configuration changes
Clustering configuration was refactored.

RUNTIME DEPENDENCIES
Apache Tomcat 6.0.x requires Java 5 or later, unlike Apache Tomcat 5.5.x which could use a compatibility
package to run on JRE 1.4.
This compatibility package is bundled along with HP-UX Tomcat, so it would work even
with your older JVMs.
However it is recommended to run using latest JDK 1.5. The latest version
of Java can be downloaded from http://www.hp.com/go/java.

To find out your version enter:

$ java -version

You will see something like:

1) on PA machine:

java version "1.5.0.01"
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0.01-_17_may_2005_17_33)
Java HotSpot(TM) Server VM (build 1.5.0 FCS (JS B64) jinteg:05.17.05-16:53 PA2.0 (aCC_AP), mixed mode)

2) on IPF machine:

DEBUGGING AND ERROR LOGGING

Tomcat 5.5 uses Commons Logging Log throughout its internal code for logging
purposes. Commons Logging provides tomcat the ability to log hierarchially
across various log levels without needing to rely on a particular logging
implementation.
For more information on Commons Logging and its configuration,
Please refer to: http://jakarta.apache.org/commons/logging/index.html

Tomcat 6.0 comes with a default logging implementation called JULI.
For more information on configuration of JULI see,
http://jakarta.apache.org/tomcat/tomcat-6.0-doc/logging.html

1) Logging server start and stop

By default, output from standard error and output are stored in
/opt/hpws22/tomcat/logs/catalina.out file. You can examine it if
you are having problems starting/stopping HP-UX Tomcat-based Servlet Engine.

***************************************************************************

LEGAL NOTICES

The information in this document is subject to change without notice.

WARRANTY DISCLAIMER
HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS
INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  Hewlett-Packard
shall not be liable for errors contained herein or for direct, indirect,
special, incidental or consequential damages in connection with the
furnishing, performance or use of this material.

RESTRICTED RIGHTS LEGEND
Use, duplication or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c)  (1) (ii) of the Rights in
Technical Data and Computer Software clause at DFARS 252.227-7013 for DOD
agencies.  Rights for non-DOD U.S. Government Department and Agencies are
as set forth in FAR 52.227-19 (c)(1,2).

COPYRIGHT NOTICES
Copyright 2001-2007 Hewlett-Packard Development Company, L.P.
This document contains information which is protected by copyright.
All Rights Reserved. Reproduction, adaptation, or translation without
prior written permission is prohibited, except as allowed under the
copyright laws.

TRADEMARK NOTICES
UNIX is a registered trademark in the United States and other countries,
licensed exclusively through X/Open Company Limited.

Java and all Java-based trademarks and logos are trademarks or
registered trademarks of Sun Microsystems, Inc. in the U.S. and
other countries.

ACKNOWLEDGEMENTS
This product includes software developed by the Apache Software Foundation.
This documentation is based on information from the Apache Software Foundation
(http://www.apache.org).