Migrate Web applications

Migration of Web applications that were deployed in WAS Version 4.x is not necessary. While version 2.3 of the servlet specification and version 1.2 of the JavaServer Pages (JSP) specification are supported by WAS Version 5.x, versions 1.1 and 1.2 of the JavaServer Pages (JSP) specification are compatible and the difference between versions 2.2 and 2.3 of the servlet specification are minor. However, there are behavioral differences between the Java 2 Enterprise Edition (J2EE) 1.2 and 1.3 specifications. Bear in mind that the J2EE 1.3 specification is implemented in Version 5, and it overrides any J2EE 1.2 behaviors.

Note: This topic does not describe how to migrate your entire configuration to Version 5. For more information about migrating your configuration, see Migration for migration instructions and tools.

Servlet migration might be a concern for your application if it has these characteristics:

• It implements a WebSphere internal servlet to bypass a Version 4.x single application path restriction.
• It extends a PageListServlet that relies on configuration information in the servlet configuration XML file.
• It uses a servlet to generate HTML output.
• It calls the response.sendRedirect() method for a servlet by using the encodeRedirectURL function or by running it within a non-context root.
• URIs at WAS Version 4 and Version 5 are case sensitive when handled by the file serving servlet. That is, when a request is sent to WAS to serve a file, the filename as it exists in the file system must match the case as is specified on the URI. This is also true starting with WAS Version 3.5.6 and beyond. If you are migrating a Web application from WAS 3.5.5 (or earlier), you need to ensure your Web applications use proper case when referencing file served files.
• It is migrated from WAS Version 3.5, and it uses ServletContext attributes. Such attributes are accessed via the ServletContext.getAttribute() API during servlet execution. WAS Version 3.5 provided these ways of setting ServletContext attributes:
  • Use the ServletContext.setAttribute( ) - a runtime servlet API available at v2.1 and v2.2.
  • By configuring at the administrative console by clicking on a the Advanced tab for a web application and updating the name and value pair for the Attributes field. Such attributes are set at application server or web application startup.

  The second method of setting ServletContext methods is no longer available at WAS Version 4 and Version 5, thus attributes can only be be set during servlet runtime using ServletContext.setAttribute( ) - the first method above. If your web application at Version 3.5 relied on setting ServletContext attributes using the second method, convert over to use getInitParameter( ) and getInitParameterNames( ), which are new servlet APIs as of v2.2.

JSP migration might be a concern if your application references JSP implementation classes in unnamed packages, or if you install WAS Version 4.x EAR files that contain compiled JSP classes, in Version 5. Your 4.x EAR files may contain compiled JSP classes if:

• You used the PreCompile JSPs option during installation of the Web application to your Version 4 application server.
• You used a development tool, such as WebSphere Development Studio Client or IBM VisualAge for Java, to compile the JSPs and to add the resulting classes to your Web application prior to deployment.
• You manually copied your compiled JSP classes to your Web application.

If you use the IBM <tsx:dbquery> tag in any of your JSPs, you might need to make additional updates. In Version 5.0, the behavior of the tag's id attribute changed. In previous versions, the id attribute specified the object name of the bean, but now refers to the bean's key name that is stored in the page context. For more information, see <tsx:dbquery> in the Application Development topic.

Here are some tips for migrating your Web applications:

• Use WAS Version 5 package names for any WAS Version 4.x internal servlets, which are implemented in your application.

  To bypass the errors, and to enable the serving of static files from the root context, WAS 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 the EAR file in the Application Assembly Tool (AAT) and enable the SimpleFileServlet static file setting.

  The other internal servlets that are affected by the Version 5 package name change are DefaultErrorReporter and AutoInvoker. Use the Version 5 package name, com.ibm.ws.webcontainer.servlet.DefaultErrorReporter and com.ibm.ws.webcontainer.servlet.AutoInvoker for these servlets. If servlet classes are built for WAS Version 5 using the old package names for these internal servlets, the WebSphere Studio family of development tools, including WebSphere Studio Development Client, reports this error:

  com.ibm.servlet.engine cannot be resolved or is not a type

• You need to migrate servlets that extend PageListServlet and rely on configuration information in the associated XML servlet configuration file. The XML servlet configuration file is not supported in WAS Version 5.

  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 configuration of the PageList servlet has changed in Version 5. See the PageList servlet section in migration configuration mapping document for more information.

• Set a content type if your servlet generates HTML output.

  The default behavior of the Web container changed in WAS 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 the WAR file in the Application Assembly Tool (AAT) and enable the autoResponseEncoding static file setting.

• 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 WAS 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 or 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/myPlege, or if the com.ibm.websphere.sendredirect.compatibility variable is set to true.

  To set the com.ibm.websphere.sendredirect.compatability variable, perform these steps in the WebSphere administrative console:

  1. Click Servers --> Application Servers in the console navigation menu.
  2. On the Application Server page, click on the name of the server whose settings you want to configure.
  3. On the settings page for the selected application server, click Process Definition.
  4. On the Process Definition page, click Java Virtual Machine.
  5. On the Java Virtual Machine page, click Custom Properties.
  6. On the Properties page, click New.
  7. On the settings page for a property, specify a name of com.ibm.websphere.sendredirect.compatibility and true for the value, then click OK.
  8. Click Save on the console taskbar.
  9. Stop the application server and then restart the application server.

• The WAS Version 4.x JSP implementation class files are not compatible with the WAS Version 5 JSP container. If you install Version 4.x EAR files that were deployed with the JSP Precompile option, either select the Pre-compile JSP option in the administrative console Install New Application page, or specify the -preCompileJSPs option when you use the wsadmin tool.

• Import your classes if your application uses unnamed packages. According to the JSP 1.2 specification, and unnamed package should not be used unless the class is explicitly imported.

  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 WAS 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 in Java 2 SDK 1.4, the compiler does not accept simple names (or unnamed packages) in the import statements.

Issues concerning the migration of JSPs and Servlets
When you migrate from Version 3.5 to Version 5, servlets and JSPs that are installed in the default Web application (default_app) are not migrated by the WAS migration tools. Options to migrate application components that are installed in the default_app Web application are as follows:

1. Install the servlets and JSPs to a different Web application. The WAS migration tools migrate these application components.
2. Use the WAS migration tools to migrate the resources used by the servlets and JSPs that are installed in the default Web application. The migration tools migrate resources, such as data sources and virtual hosts. After you migrate the resources, manually migrate the servlets and JSPs without using the WAS migration tools.