Sun Java System Application Server Platform Edition 8.1 2005Q2 Update 2 Upgrade and Migration Guide

Migrating Web Applications

Application Server 6.x support servlets (Servlet API 2.2), and JSPs (JSP 1.1). Sun Java System Application Server 8.1 supports Servlet API 2.4 and JSP 2.0.

Within these environments it is essential to group the different components of an application (servlets, JSP and HTML pages and other resources) together within an archive file (J2EE-standard Web application module) deploying it on the application server.

According to the J2EE specification, a Web application is an archive file (WAR file) with the following structure:

Migrating Java Server Pages and JSP Custom Tag Libraries

Application Server 6.x complies with the JSP 1.1 specification and Application Server 8.1 complies with the JSP 2.0 specification.

JSP 2.0 specification contains many new features, as well as updates to the JSP 1.1 specification.

These changes are enhancements and are not required to migrate to JSP pages from JSP 1.1 to 2.0.

The implementation of JSP custom tag libraries in Application Server 6.x complies with the J2EE specification. Consequently, migrating JSP custom tag libraries to the Application Server Platform Edition 8.1does not pose any particular problem, nor require any modifications.

Migrating Servlets

Application Server 6.x supports the Servlet 2.2 API. Sun Java System Application Server 8.1 supports the Servlet 2.4 API.

Servlet API 2.4 leaves the core of servlets relatively untouched. Most changes are concerned with adding new features outside the core.

The most significant features are:

These changes are enhancements and are not required to be made when migrating servlets from Servlet API 2.2 to 2.4.

However, if the servlets in the application use JNDI to access resources in the J2EE application (such as data sources or EJBs), some modifications might be needed in the source files or in the deployment descriptor.

These modifications are explained in detail in the following sections:

One last scenario might require modifications to the servlet code. Naming conflicts can occur with Application Server 6.x if a JSP page has the same name as an existing Java class. In this case, the conflict must be resolved by modifying the name of the JSP page in question. This in turn can mean editing the code of the servlets that call this JSP page. This issue is resolved in Application Server as it uses a new class loader hierarchy. In the new version of the application server, for a given application, one class loader loads all EJB modules and another class loader loads web module. As these two loaders do not talk with each other, there is no naming conflict.

Obtaining a Data Source from the JNDI Context

To obtain a reference to a data source bound to the JNDI context, look up the data source’s JNDI name from the initial context object. The object retrieved in this way is then be cast as a DataSource type object:

ds = (DataSource)ctx.lookup(JndiDataSourceName);

For detailed information, refer to section “Migrating JDBC Code.”

Declaring EJBs in the JNDI Context

Please refer to section Declaring EJBs in the JNDI Context in Chapter 5, Migrating from EJB 1.1 to EJB 2.0.”

Potential Servlets and JSP Migration Problems

The actual migration of the components of a Servlet / JSP application from Application Server 6.x to Application Server 8.1does not require any modifications to the component code.

If the Web application is using a server resource, a DataSource for example, the Application Server requires that this resource to be declared inside the web.xml file and, correspondingly, inside the sun-web.xml file. To declare a DataSource called jdbc/iBank, the <resource-ref> tag in the web.xml file is as follows:


The corresponding declaration inside the sun-web.xml file looks like this:

<?xml version="1.0" encoding="UTF-8"?>
<! DOCTYPE FIX ME: need confirmation on the DTD to be used for this file

Migrating Web Application Modules

Migrating applications from Application Server 6.x to Sun Java System Application Server 8.1 does not require any changes to the Java code or Java Server Pages. However, you must change the following files:

The Application Server adheres to J2EE 1.4 standards, according to which, the web.xml file inside a WAR file must comply with the revised DTD at This DTD is a superset of the previous versions’ DTD, hence only the <! DOCTYPE definition needs to be changed inside the web.xml file, which is to be migrated. The modified <! DOCTYPE declaration looks like:

<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.// 
                        DTD Web Application 2.3//EN" 

In Application Server Platform Edition 8.1, the name of this file is changed to sun-web.xml.

This XML file must declare the Application Server-specific properties and resources that are required by the Web application.

See Potential Servlets and JSP Migration Problems for information about important inclusions to this file.

If the ias-web.xml of the Application Server 6.5 application is present and does declare Application Server 6.5 specific properties, then this file needs to be migrated to Application Server standards. The DTD file name has to be changed to sun-web.xml. For more details, see URL

Once you have made these changes to the web.xml and ias-web.xml files, the Web application (WAR file) can be deployed from the Application Server’s deploytool GUI interface or from the command line utility asadmin. The deployment command must specific the type of application as web.

Invoke the asadmin command line utility by running asadmin.bat file or the script in the Application Server’s bin directory.

The command at the asadmin prompt is:

asadmin deploy -u username -w password
-H hostname 
-p adminport 
--type web 
[--contextroot contextroot] 
[--name component-name] 
[--upload=true] filepath