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

- Previous: Migrating Deployment Descriptors
- Next: Migrating Enterprise EJB Modules

# 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:

- A root directory containing the HTML pages, JSP, images and other static resources of the application.

- A `META-INF/` directory containing the archive manifest file `MANIFEST.MF` containing the version information for the SDK used and, optionally, a list of the files contained in the archive.

- A `WEB-INF/` directory containing the application deployment descriptor (`web.xml` file) and all the Java classes and libraries used by the application, organized as follows:

  - A `classes/` sub-directory containing the tree-structure of the compiled classes of the application (servlets, auxiliary classes), organized into packages

    - A `lib/` directory containing any Java libraries (JAR files) used by the application

## 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:

- Servlets now require JDK 1.2 or later

- Filter mechanisms have been created

- Application lifecycle events have been added

- Internationalization support has been added

- Error and security attributes have been expanded

- HttpUtils class has been deprecated

- Several DTD behaviors have been expanded and clarified

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:

- Obtaining a Data Source from the JNDI Context

- Declaring EJBs in the JNDI Context

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:

    <resource-ref>
       <res-ref-name>jdbc/iBank</res-ref-name>
       <res-type>javax.sql.XADataSource</res-type>
       <res-auth>Container</res-auth>
       <res-sharing-scope>Shareable</res-sharing-scope>
    </resource-ref>

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
    <sun-web-app>
       <resource-ref>
          <res-ref-name>jdbc/iBank</res-ref-name>
          <jndi-name>jdbc/iBank</jndi-name>
       </resource-ref>
     </sun-web-app>

## 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:

- `web.xml`

- `ias-web.xml`

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 `http://java.sun.com/dtd/web-app_2_3.dtd`. 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"
                            "http://java.sun.com/dtd/web-app_2_3.dtd">

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 `http://wwws.sun.com/software/dtd/appserver/sun-web-app_2_4-1.dtd`

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 `asadmin.sh` 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]
    [--force=true]
    [--name component-name]
    [--upload=true] filepath

- Previous: Migrating Deployment Descriptors
- Next: Migrating Enterprise EJB Modules

- © 2010, Oracle Corporation and/or its affiliates