Previous     Contents     Index     DocHome     Next     
iPlanet Application Server Migration Guide



Chapter 1   Migration Overview


This chapter introduces the iPlanet Application Server 6.0 programming model and compares it to both the NAS 4.0 programming model and the NAS 2.1 programming model. It also describes the basics of migrating NAS applications to the new iPlanet Application Server 6.0 model. Finally, this chapter describes the procedures required for redeploying iPlanet Application Server 6.0 SP1 applications to iPlanet Application Server 6.0 SP3 using the new redeploy command utility.

The new iPlanet Application Server 6.0 programming model is for Java applications only. C++ applications continue to use the NAS 2.1 model. Note the following compatibility issues:

  • iPlanet Application Server 6.0 is backward compatible with NAS 2.1 applications. NAS 2.1 applications can run on iPlanet Application Server 6.0 without code alteration.

  • iPlanet Application Server 6.0 is compatible with NAS 4.0 applications with conversion to the J2EE standard. NAS 4.0 applications do require some conversion.

This chapter describes the following topics:



The New J2EE Programming Model

iPlanet Application Server 6.0 is Java 2 Platform, Enterprise Edition (J2EE) specification version 1.2 compliant and is based on standards developed by the Java community, namely: servlets, JavaServer Pages, and Enterprise JavaBeans. This is in contrast to the proprietary AppLogic-based programming model used in NAS 2.1. NAS 4.0 is based on the J2EE programming model but uses earlier versions of the standards.

Application flow is similar between the iPlanet 6.0 model and the previous 4.0 and 2.1 models. Each user interaction is handled by one (or more) application components that process the inputs, perform business logic functions, interact with a database, and provide an output page that answers the input and sets up the next user interaction. The 6.0 model, like the 4.0 model, is more modular and segregates activities into more discrete components.

The new programming model describes three tiers of application logic, each of which is represented by a set of components or APIs. These tiers are described in the following table:



Programming Tier

NAS 2.1 component

NAS 4.0 component

iPlanet Application Server 6.0 component

Description

Presentation Logic  

AppLogic  

Java servlet and proprietary standards  

Java servlet  

Controls the application's interface to the user by processing requests, generating content in response, formatting and delivering that content back to the user. In 6.0, servlets process incoming requests and orchestrate the response. Business logic is normally off-loaded to EJBs, and output is usually off-loaded to JSPs.  

Presentation Layout (part of Presentation Logic)  

HTML template  

JavaServer Page (JSP) and proprietary standards  

JavaServer Page (JSP)  

Controls the appearance of each page. Part of the presentation logic, usually handled by JavaServer Pages. JSPs are HTML pages that contain embedded Java, and thus are much more versatile and powerful than 2.1 HTML templates.  

Business Logic  

AppLogic  

Enterprise JavaBeans (EJBs) and proprietary standards  

Enterprise JavaBeans (EJBs)  

Controls business logic. EJBs enable business logic to be persistent across calls, offer improved caching, and are designed to work closely with JDBC for database transactions.  

Data Access Logic  

DAE  

JDBC and proprietary standards  

JDBC  

Controls database storage and retrieval. The JDBC API is available to all Java components, as are all APIs, though database transactions are usually controlled by EJBs in the 6.0 model.  

This section includes the following additional topics:


Component Modularity and Flexibility

The terms "normally" and "usually" appear frequently in this document and in the Developer's Guide (Java) with regard to the roles of iPlanet Application Server 6.0 components. Since servlets, JSPs, and EJBs all reside within the same virtual machine and are all Java objects, they share a flexibility that allows each task to be addressed by more than one component. There are no hard and fast rules specifying which tasks are appropriate for which components. For example, an entire complex application could be written using only JSPs, or only servlets.

However, the components are designed to work together in a modular way, taking advantage of the strengths of each component. For example, it is more cumbersome to perform layout tasks in a servlet, but JSPs (as HTML pages) are highly suitable for layout tasks. Alternatively, presentation logic is compact and elegant in a servlet.

The segregation and order of components describes a powerful application model that runs well in a distributed environment. Choose components that perform the tasks you need, using the programming tiers described here as a guideline.


Presentation Logic and Layout

Presentation logic describes the flow of an application from the perspective of each user interaction: request processing, followed by content generation and delivery. The goal of presentation logic is to create a logical answer to a request, and to prompt for another request. The goal of presentation layout is to display the content of this answer in a predetermined format. Application functions such as user sessions, security and user authentication, and input validation are also handled by the presentation logic.

In short, presentation logic involves everything related to the application's interface with the user.

In the NAS 2.1 programming model, presentation logic was controlled by the AppLogic class, while layout was handled by an HTML template. At run-time, AppLogic objects provided output to populate the template.

In the iPlanet Application Server 6.0 programming model, presentation logic is usually handled by a Java servlet. Layout is usually handled by a JSP. At runtime, the servlet uses a JSP to format the content generated by the business logic.

The two major alternatives to this basic model are as follows:

  • Handle all presentation logic and layout for a given interaction in a JSP. This can be an easy way to control an interaction that has no business logic and little to process from the previous interaction. For example, the "front page" for an application often requires no processing at all.

  • Handle all presentation logic and layout in a servlet. This can be efficient for interactions that have very little layout. For example, a simple database report might just list the rows retrieved from a database query. It doesn't make sense to incur the overhead of a JSP call when the page can be simply output from a servlet.


Business Logic

Business logic describes the activities that involve the generation of specific content: storing and retrieving data, and performing computations on that data. The goal of business logic is to perform the activities that generate or determine answers to questions posed by the presentation logic.

In short, business logic involves the content provided by and generated for the application.

In the NAS 2.1 programming model, business logic was controlled by the same AppLogic that handled the presentation logic for a given user interaction.

In the iPlanet Application Server 6.0 programming model, business logic is usually handled by one or more Enterprise JavaBeans (EJBs), which control database transactions and encapsulate the results. EJBs are powerful, reusable components that empower applications with a great deal of flexibility, since EJBs can be invoked or inspected from any other object and can be made to be persistent.

One alternative to this model is to handle business logic in the presentation logic (servlets and/or JSPs), much the same way that AppLogics handled business logic. This can be efficient for short, directed business events such as specific directory requests, but this approach lacks the flexibility and power that EJBs bring to the programming model.


Data Access Logic

Data access logic describes transactions with a database or directory server. The goal of data access logic is to provide an interface between an application and the set of data that concerns it. Data access is normally performed as a function of business logic.

In short, data access logic involves the storage and retrieval of the content collected or generated by business logic.

In the NAS 2.1 programming model, data access logic was controlled by calls made from an AppLogic using APIs from several classes and interfaces, including the DataSet, DBDataSet, and DBStoredProcedure classes and the ICallableStmt, IColumn, IDataConn, IDataConnSet, IHierQuery, IHierResultSet, IListDataSet, IPreparedQuery, IQuery, IResultSet, ITable, ITrans, and IValList interfaces.

In the iPlanet Application Server 6.0 programming model, data access logic is handled by the JDBC standard set of APIs. The previous APIs are all deprecated in iPlanet Application Server 6.0.



Migrating NAS 2.1 Applications to iPlanet Application Server 6.0


Migration involves altering an application written for the NAS 2.1 programming model so that it conforms to the iPlanet Application Server 6.0 programming model. There are three approaches to this process, each of which is covered in this document:

  • No migration. This approach involves no actions by the developer and depends solely on backward-compatible support by the server. This is an acceptable approach if you do not want to take advantage of the flexibility and power that the new standards-based model provides, although many of the APIs supported in NAS 2.1 are now deprecated and may not be supported in future releases.

    Backward-compatibility is described in ."

  • Partial migration. In this approach, part of the application conforms to the new programming model, while the rest relies on backward-compatibility. This enables developers to migrate one portion of an application at a time (for example, one level of interaction with a user, or one programming tier) while still retaining the portions of the application that are known and tested.

    iPlanet Application Server 6.0 supports partial migration by providing "glue" between the old components and the new components. This support is described in

  • Complete migration to the new programming model. This approach requires a lot of development resources and involves a full redesign, but it enables the application to take full advantage of the features of the new programming model.

    This approach is described in ."



Migrating NAS 4.0 Applications to iPlanet Application Server 6.0

NAS 4.0 uses Netscape and older Java standards which have been replaced with J2EE 1.2 standards in iPlanet Application Server 6.0. You need to replace deprecated methods and redeploy your applications with the new XML descriptors. Tools are provided to help with the process. For more information, see Chapter 4 "Running NAS 4.0 Applications."



Redeploying iPlanet Application Server 6.0 SP1 Applications


This section describes how you can use the new redeploy command utility to redeploying your iPlanet Application Server 6.0 SP1 applications to iPlanet Application Server 6.0 SP3.

Note that you are not required to redeploy existing applications from iPlanet Application Server 6.0 SP2 to SP3.

This section describes the following topics:


About the Redeploy Command Utility

If you are upgrading an iPlanet Application Server 6.0 SP1 installation to iPlanet Application Server 6.0 EE SP3, you would see the following message at the end of the installation procedure:

Windows Platforms:

You have upgraded from iAS 6.0 SP1 to iAS 6.0 SP3. You must re-deploy applications previously deployed on SP1 using the utility <install-dir>/ias/bin/redeploy.exe.

Solaris Platforms:

You have upgraded from iAS 6.0 SP1 to iAS 6.0 SP3. You must re-deploy applications previously deployed on SP1 using the utility <install-dir>/ias/bin/redeploy.

where <install-dir> refers to the root directory of iPlanet Application Server installation.

A new command redeploy utility is provided to complete the deployment of existing applications after the upgrade to SP3. This is due to the following changes in iPlanet Application Server 6.0 SP3:

  • iPlanet Application Server 6.0 directly extracts class files in a .war file under <install-dir>/ias/APPS directory. From iPlanet Application Server 6.0 SP2, the class files are extracted under the directory <install-dir>/ias/APPS/<app-name>/<module-name>/classes. The JASPER compiler integrated with iPlanet Application Server 6.0 SP3 specifically expects this directory structure. For more information, refer to iPlanet Application Server 6.0 SP3 Release Notes, under the Jasper Integration section in Core Server Enhancements within the "What's New in iPlanet Application Server 6.0 SP3" section.

    The Fortune application which ships with iPlanet Application Server 6.0 (all versions). In iPlanet Application Server 6.0 SP1, on deploying this application, the class file FortuneServlet, which constitutes this application, is extracted directly under <install-dir>/ias/APPS/sample/fortune, according to its package structure: sample.fortune.FortuneServlet.

    In iPlanet Application Server 6.0 SP2 and SP3, a directory called <install-dir>/ias/APPS/fortune/fortune is created.Within this directory, a directory called WEB-INF is created. This WEB-INF directory contains a classes directory containing sample/fortune/FortuneServlet.class and the web.xml file.

    The following information shows the difference in the locations where the class sample.fortune.FortuneServlet is extracted after deploying the Fortune Application on iPlanet Application Server SP1and SP3:

    Fully Qualified ClassName

    sample.fortune.FortuneServlet

    Location where .class file is extracted in SP1

    <install-dir>/ias/APPS/samples/fortune

    Location where .class file is extracted in SP3

    <install-dir>/ias/APPS/fortune/fortune/WEB-INF/classes/samples/fortune

  • The new iASClassLoader implemented in iPlanet Application Server 6.0 SP3 can not load classes if class files from previously deployed .war components of .ear files are placed directly under the <install-dir>/ias/APPS directory.

    This is because the <install-dir>/ias/APPS directory is in the kjs classpath. After deploying applications on iPlanet Application Server 6.0 SP1, the servlet classes can be found directly under the directory <install-dir>/ias/APPS. Any class which is in the kjs classpath is loaded by the system class-loader, while the ejb classes which are under a different directory are loaded by the iPlanet Application Server classloader. However, if a servlet class is found directly under the kjs classpath, the system classloader loads it. Note that the ejb classes are not in the kjs classpath and require the iPlanet Application Server classloader to load them. Once the system classloader is invoked, the responsibility for loading the ejb classes cannot be delegated to the iPlanet Application Server class loader.

  • Therefore an application consisting of a servlet invoking an ejb method gives ClassDefNotFoundException. For more information, refer to iPlanet Application Server 6.0 SP3 Release Notes, under the Dynamic Class Reloading section in Core Server Enhancements within the "What's New in iPlanet Application Server 6.0 SP3" section.

    In addition, the redeploy utility described later in this section moves certain class files for applications deployed on iPlanet Application Server 6.0 SP1 to a different directory, to ensure that after redeploying, both the servlet classes and the ejb classes invoked by these servlet classes are loaded by the iPlanet Application Server ClassLoader.

  • User authentication has been modified in iPlanet Application Server 6.0 SP3. In particular, if an application tries to read username and password from an HTTP request string, it would not work in iPlanet Application Server 6.0 SP3. The user name and password are currently removed from the HTTP request by the Form Authentication module of iPlanet Application Server. For more information, see "Limitations" later in this section.


Using the Redeploy Command Utility

The redeploy command utility provided with iPlanet Application Server 6.0 SP3 enables you to redeploy applications which were deployed on iPlanet Application Server 6.0 SP1 before upgrade to iPlanet Application Server 6.0 SP3.

This utility is present in the installation as:

<install-dir>/ias/bin/redeploy (shell script on Solaris platforms)

<install-dir>/ias/bin/redeploy.exe (binary on Windows platforms)

where <install-dir> refers to the root directory of iPlanet Application Server installation.

You can run this utility once after the upgrade from iPlanet Application Server 6.0 SP1 to SP3. Note that you are not required to redeploy existing applications from iPlanet Application Server 6.0 SP2 to SP3.

The redeploy utility finds all applications already deployed on iPlanet Application Server 6.0 SP1, and their corresponding .ear files and redeploys each such application on iPlanet Application Server 6.0 SP3.

The redeploy utility also moves class files from .war components of applications previously deployed on iPlanet Application Server 6.0 SP1 to a trash directory. This is done so that the new iPlanet Application Server class loader can function correctly.

Note that your class files extracted from iPlanet Application Server 6.0 SP1 installation are not deleted. They are moved to the <install-dir>/ias/trash/sp1 directory, and placed in a directory corresponding to the package structure of that class. For example, on deploying the Fortune application, you obtain the FortuneServlet class under <install-dir>/ias/APPS/sample/fortune directory. The redeploy utility would move this file to the <install-dir>/ias/trash/sp1/sample/fortune directory.


Limitations Using the Redeploy Command Utility

This section describes the limitations regarding how you use the redeploy command utility.

  • The redeploy utility will not find out applications deployed on iPlanet Application Server 6.0 SP1 which consist of only .war files (not packaged within any .ear file). Such applications have to be re-deployed manually by the user after the upgrade.

  • If an application deployed on iPlanet Application Server 6.0 SP1 uses a database client not supported on iPlanet Application Server 6.0 SP3, the redeploy utility cannot manage such situations. You must register a database client compatible with iPlanet Application Server 6.0 SP3 using the db_setup utility, and register the datasources for these applications.

  • Your application must not contain code which tries to read username and password from a HTTP request. When running such an application, an Authentication Error will result even after re-deploying the application on iPlanet Application Server 6.0 SP3.


Example

Consider the following code snippet from the BankLoginServlet.java file which was shipped with iPlanet Application Server 6.0 SP1:

public class BankLoginServlet extends HttpServlet {

public void doGet (HttpServletRequest request,HttpServletResponse response)

   throws ServletException, IOException {
      response.setContentType("text/html");

      PageDispatcher dispatcher = new PageDispatcher(this,
      request,response);

      PrintWriter out = response.getWriter();

      String userName = request.getParameter(Constants.USER_NAME);
      String passWord = request.getParameter(Constants.PASSWORD);

      if ((userName == null || userName.equals("")) || (passWord ==
      null || passWord.equals("")))

      {
      request.setAttribute("error", new ErrorReporter("Login
      failed: username or password was null"));

      dispatcher.showPage(Constants.LOGIN_ERROR_PAGE);

      return;
      }

   }

}

The above code tries to parse the HttpRequest string for the values of username and password. However, retaining the username and password in the HttpRequest string is a security loophole. This has been corrected in iPlanet Application Server 6.0 SP3, that is, the username and password are removed from the HttpRequest string after Form-based authentication in SP3. Thereafter the user program would not be able to read the values of username and password from the HttpRequest. Applications having code as shown above, would not work on iPlanet Application Server 6.0 SP3 even after re-deployment.


Running the Redeploy Command Utility

To run the redeploy utility, perform the following steps:

  1. Please ensure that you run the redeploy utility once after upgrading from SP1 to SP3.

    On Solaris platforms:

    cd <install-dir>/ias/bin

    ./redeploy

    On Windows platforms:

    cd <install-dir>/ias/bin redeploy

  2. Restart the iPlanet Application Server before running any of the re-deployed applications.


Previous     Contents     Index     DocHome     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated June 14, 2001