Sun Java System Web Server 6.1 SP7 Programmer's Guide to Web Applications

Appendix B Migrating Legacy Servlets

Netscape Enterprise Server/ iPlanet Web Server 4.0 and 4.1 supported the Java Servlet 2.1 specification. This specification did not include web applications. A deployment scheme was developed to make servlet deployment simpler. With the advent of Java web applications (.war files) and their deployment descriptors, it is no longer necessary to maintain a proprietary deployment system.

iPlanet Web Server 6.0 supported both types of deployment schemes, but the 4.x implementation (referred to as legacy servlets) was marked as deprecated (See Chapter 8: “Legacy Servlet and JSP Configuration” of the iPlanet Web Server, Enterprise Edition Programmer's Guide to Servlets).

Sun Java System Web Server 6.1 no longer supports legacy servlets. The legacy-style properties files for the server you want to migrate (,, and are removed during migration. For more information about these files, see "Appendix A" in the Sun Java System Web Server 6.1 SP7 Administrator’s Configuration File Reference.

Because there is no one-to-one mapping for all of the features, legacy servlets cannot be migrated automatically. This section describes the main features involved in migrating legacy servlets to web applications.

This appendix includes the following topics:

JSP by Extension

In Sun Java System Web Server 6.1, JSP by extension works as it did in previous releases. Any file in the document tree that is named as an extension of .jsp will be treated as a JSP as long as the Java is turned on for the virtual server.

Servlet by Extension of Servlet by Directory

This is not supported in Sun Java System Web Server 6.1. You can deploy a web application to respond to a directory, but all of the servlets must be in the WEB-INF/classes directory of the web application. You can no longer copy a servlet in the .class file into the document tree and have it run as a servlet or have all of the contents of a directory run as a servlet. The web application will treat only .class files as servlets.

Registered Servlets

In the legacy servlet system there was a two-step process of registering servlets ( and mapping them to a URL ( In Sun Java System Web Server 6.1, the servlets must be moved into a web application, and these settings will be maintained in the web.xml file of that web application.


A registered servlet contains entries in both the and files.

The following example uses a servlet file called BuyNow1A.class, which respons to /buynow. It is assumed that the web application is deployed at '/'.

The file has:

servlet.BuyNowServlet.initArgs=arg1=45,arg2=online,arg3="quick shopping"

The file has:


Those must be translated to a web.xml setting.

The setting will translate into the <servlet> element.

The classpath is automated so there is no classpath setting. All classes to be used must be in the WEB-INF/classes directory or in a .jar file in the WEB-INF/lib directory of the web application.

The servlet-name element is the part between the dots in the file. The code translates to the servlet-class. IntArgs translate to init-params. This entry would translate to:

    <servlet-name> BuyNowServlet </servlet-name>
    <servlet-class> BuyNow1A </servlet-class>
          <param-name> arg1 </param-name>
          <param-value> 45 </param-value>
          <param-name> arg2 </param-name>
          <param-value> online </param-value>
          <param-name> arg3 </param-name>
          <param-value> “quick shopping” </param-value>

The entries translate to servlet-mapping elements. This entry would translate to.

    <servlet-name> BuyNowServlet </servlet-name>
    <url-pattern> /buynow </url-pattern>

Some other entries in the file map to the web.xml file. These include.