Why and when to perform this task

Migration of Web applications deployed in WebSphere Application Server Version 5.x is not necessary; version 2.2 and 2.3 of the Java Servlet specification and version 1.2 and 1.4 of the JavaServer Pages (JSP) specification are still supported. However, where there are behavioral differences between the Java 2 Platform, Enterprise Edition (J2EE) 1.2 and J2EE 1.3 specifications, bear in mind that J2EE 1.3 specifications are implemented in WebSphere Application Server Version 5 and will override any J2EE 1.2 behaviors.

Servlet migration might be a concern if your application:

• Implements a WebSphere internal servlet to bypass a WebSphere Application Server Version 4.x single application path restriction.

• Extends a PageListServlet that relies on configuration information in the servlet configuration XML file.

• Uses a servlet to generate Hypertext Markup Language (HTML) output.

• Calls the response.sendRedirect method for a servlet using the encodeRedirectURL function or executing within a non-context root.

JSP migration might be a concern if your application references JSP page implementation classes in unnamed packages, or if you install WebSphere Application Server Version 4.x EAR files (deployed in Version 4.x with the JSP Precompile option), in Version 5.

Follow these steps if migration issues apply to your Web application:

1. Use WebSphere Application Server Version 5 package names for any WebSphere Application Server Version 4.x internal servlets, which are implemented in your application.

   In WebSphere Application Server Version 4.x, Web modules with a context root setting of / are not supported. Accessing Web modules with this root context results in HTTP 404 - File not Found errors.

   To bypass the errors, and to enable the serving of static files from the root context, WebSphere Application Server Version 4.x users are advised to add the servlet class, com.ibm.servlet.engine.webapp.SimpleFileServlet , to their Web module.

   The Version 4.x single path limitation does not exist in Version 5. However, users who choose to use the com.ibm.servlet.engine.webapp.SimpleFileServlet in Version 5 must do one of the following:

   • Rename com.ibm.servlet.engine.webapp.SimpleFileServlet to com.ibm.ws.webcontainer.servlet.SimpleFileServlet.

   • Open a Web deployment descriptor editor using an assembly tool and select File serving enabled on the Extensions tab.

   The following list identifies the other internal servlets affected by the Version 6 package name change:

   • DefaultErrorReporter

   • AutoInvoker

   Use the Version 5 package name, com.ibm.ws.webcontainer.servlet. servlet class name for these servlets.

2. Use the WASPostUpgrade tool to migrate servlets that extend PageListServlet and rely on configuration information in the associated XML servlet configuration file. In Version 4.x, the XML servlet configuration file provides configuration data for page lists and augments servlet configuration information. This file is named as either servlet_class_name.servlet or servlet_name .servlet, and is stored in the same directory as the servlet class file.

   The XML servlet configuration file is not supported in WebSphere Application Server Version 5.

3. Use the WASPostUpgrade tool to migrate servlets that extend PageListServlet and rely on configuration information in the associated XML servlet configuration file. In Version 4.x, the XML servlet configuration file provides configuration data for page lists and augments servlet configuration information. This file is named as either servlet_class_name.servlet or servlet_name.servlet, and is stored in the same directory as the servlet class file.

   The XML servlet configuration file is not supported in WebSphere Application Server Version 5.

4. The default behavior of the Web container changed in WebSphere Application Server Version 5. If the servlet developer does not specify a content type in the servlet then the container is forbidden to set one automatically. Without an explicit content type setting, the content type is set to null. The Netscape browser displays HTML source as plain text with a null content type setting.

   To resolve this problem, do one of the following:

   • Explicitly set a content type in your servlet.

   • Open a Web deployment descriptor editor in an assembly tool and select Automatic Response Encoding enabled on the Extensions tab.

5. Set the Java environment variable, com.ibm.websphere.sendredirect.compatibility , to true if you want your URLs interpreted relative to the application root.

   The default value of the Java environment variable com.ibm.websphere.sendredirect.compatibility changed in WebSphere Application Server Version 5. In Version 4, the default setting of this variable is true. In Version 5, the setting is false.

   When this variable is set to false, if a URL has a leading slash, the URL is interpreted relative to the Web module/application root. However, if the URL does not have a leading slash, it is interpreted relative to the Web container root (also known as the Web server document root). Therefore, if an application has a WAR file that has a context root of myPledge_app and a servlet that has a servlet mapping of /Intranet/, a JSP file in the WAR file cannot access the servlet when its encodeRedirectURL is set to /Intranet/myPledge . The JSP file can access the servlet if the encodeRedirectURL is set to myPledge_app/Intranet/myPledge, or if the com.ibm.websphere.sendredirect.compatibility variable is set to true.

   See the Setting the sendredirect variable article for more information.

6. Use the WASPostUpgrade tool to migrate WebSphere Version 4.x enterprise applications to Version 5.

   Note: The WebSphere Application Server Version 4.x JSP page implementation class files are not compatible with the WebSphere Application Server Version 5 JSP container.

   The WASPostUpgrade tool automatically precompiles JSP files, which ensures the JSP page implementation class files are compatible with Version 5.

   If you install Version 4.x EAR files, deployed with the JSP Precompile option, in Version 5, and you choose not to follow the migration path, do one of the following:

   • Select the Pre-compile JSP option in the administrative console Install New Application window.

     See article Installing a new application for more information.

   • Specify the -preCompileJSPs option when using the wsadmin tool.

7. Import your classes if your application uses unnamed packages.

   Section 8.2 of the JSP 1.2 specification states:

   The JSP container creates a JSP page implementation class for each JSP page.
   The name of the JSP page implementation class is implementation dependent.
   The JSP page implementation object belongs to an implementation-dependent named package. The package used may vary between one JSP and another, so minimal assumptions should be made. The unnamed package should not be used without an explicit import of the class.

   For example, if myBeanClass is in the unnamed package, and you reference it in a jsp:useBean tag, then explicitly import myBeanClass with the page directive import attribute, as shown in the following example:

    <%@page import="myBeanClass" %>
                  . . .
    <jsp:useBean id="myBean" class="myBeanClass" scope="session"/>   

   In WebSphere Application Server Version 5, the JSP engine creates JSP page implementation classes in the org.apache.jsp package. If a class in the unnamed package is not explicitly imported, then the javac compiler assumes the class is in package org.apache.jsp, and the compilation fails. Note: Avoid using the unnamed package altogether because of a change made in JDK 1.4 that will affect the JSP 2.0 specification. WebSphere Application Server Version 5 ships with JDK 1.3.1, so this is not an issue with the Version 5 JSP engine, but it will become an issue in future releases.

   The Incompatibilities section of the version 1.4.Java 2 Platform, Standard Edition (J2SE) documentation states:

        The compiler now rejects import statements that import a type from the unnamed namespace. Previous versions of the compiler would accept such 
   import declarations, even though they were arguably not allowed by the 
   language (because the type name appearing in the import clause is not in 
   scope). The specification is being clarified to state clearly that you 
   cannot have a simple name in an import statement, nor can you import from 
   the unnamed namespace.
        To summarize, the syntax:
   
           import SimpleName;
   
   is no longer legal. Nor is the syntax 
           import ClassInUnnamedNamespace.Nested;
   
   which would import a nested class from the unnamed namespace. 
       To fix such problems in your code, move all of the classes from the 
   unnamed namespace into a named namespace.

Related tasks
Migrating and coexisting
Hot deployment and dynamic reloading

Related reference
Web applications: Resources for learning
Configuring JVM sendRedirect calls to use context root