Sun ONE logo      Previous      Contents      Index      Next     

Sun ONE Application Server 7 Migrating and Redeploying Server Applications Guide

Chapter 4
Migration from NetDynamics to Sun ONE AS 7

NetDynamics applications can be migrated to J2EE web modules using iPlanet Migration Toolkit (iMT 1.2.3). The resulting web modules can be deployed and executed on any J2EE web container.

Introduction

Before continuing, be sure you have read the %MIGTBX_HOME%/bin/readme.txt file so that you are aware of the latest information and any issues that might be relevant to you and your environment. The readme file also describes proper installation and configuration of the Migration Toolbox and its environment, which must be complete before beginning the migration process described in this document.

[%MIGTBX_HOME% represents the directory in which you installed/unzipped the iPlanet Migration Toolbox (iMT)].

This document covers the minimal process of migrating a NetDynamics application to J2EE. It is not intended to be an exhaustive reference for the migration process, in large part because there are only a few common aspects between any two migrations. Instead, this document provides the information necessary to understand the basic migration process using the iPlanet Migration Toolbox (iMT).

Migration Preparation

Migration Process Overview

There are two main phases to full migration of a NetDynamics proprietary project to its J2EE equivalent. These phases are the automated migration phase and the manual migration phase. The automated migration itself consists of two steps called extraction and translation.

Automated Migration Phase

This phase consists of manually preparing a NetDynamics project for migration and then using the iMT to perform automated extraction and translation. The input to this phase is a proprietary NetDynamics project or set of projects, and the result is a partially (or in some cases, fully) migrated application consisting entirely of non-proprietary J2EE-compliant components (servlets and JSPs).

The output from the translation process entirely replicates the component structure present in the original NetDynamics project. This process also uses the declarative property information present in the project's INTRP files to generate equivalent features in the migration application. However, the translation phase does not (currently) automatically port code written to the NetDynamics Spider API to its J2EE equivalent. This porting will be the primary task during the manual migration phase. The process does, however, place the original source code in the appropriate location in the new output. For example, code from the NetDynamics onBeforeDisplay event handlers is placed in the analogous event handler methods in the migrated application.

Manual Migration Phase

The degree of application migration accomplished in the automated phase is directly related to the amount of declarative versus API features used in the original application. In those rare cases where a project used entirely declarative features, that project can frequently be automatically migrated fully and be immediately deployable and runnable in a J2EE container without any manual work. Consequently, projects that use fewer declarative features will require more manual work to become functional as J2EE applications.

In general, the manual migration phase consists of reviewing the automatically migrated application output and porting Spider-API-specific code to J2EE-specific code. Understand that this process does not typically require a redesign of the application or its architecture; rather, it is largely a straightforward 1-to-1 mapping of API calls. This is possible because of the use of JATO, a powerful J2EE-compliant web application foundation targeted by the automated translation process.

Preparing your Working Environment

Before going further, ensure you've done the following:

  1. Make sure you've installed the iPlanet Migration Toolbox.
      • Unzip the distribution archive into the desired target directory. Follow the directions in the readme.txt file.
      • Test the installation by trying to start the Toolbox application. Run toolbox.bat in the %MIGTBX_HOME%/bin directory. An empty Toolbox should appear after a few moments. If nothing appears, check that the Migration Toolbox was installed properly and that all appropriate environment settings have been set in %MIGTBX_HOME%/bin/setenv.bat.
  2. To avoid class version issues, we strongly recommend that you remove all JAR files from your JDK's extension directory (%JAVA_HOME%/jre/lib/ext) while running the Toolbox application. We have included all the classes necessary for running the Toolbox with the distribution. Please note that simply renaming the JAR files in the extension directory is not sufficent; you must move them to a different location.
  3. Copy the NetDynamics project(s) you wish to migrate into the %MIGTBX_HOME%/work/NDProjects directory (or any other convenient directory). This directory will be referred to as the NetDynamics projects directory below. This directory is not necessarily the actual project directory used by a NetDynamics installation on the same machine (although it could be). Instead, it is the directory in which you will place the NetDynamics projects to be migrated. Note that NetDynamics need not be installed on the machine running the Migration Toolbox. However, if NetDynamics is installed on the machine that will be used to run iMT, you must be sure that the installed NetDynamics does not interfere with the iMT. This will happen if the installed ND's classpath is referenced in the system environment variable called CLASSPATH. When iMT is started, it appends its own necessary classpaths to the end of the system classpath. If the installed ND's classpath is part of the system classpath, then the iMT will not operate properly.
  4. At this point, you may also want to install Sun™ ONE Application Server 7 or another J2EE-compliant servlet/JSP container
      • Follow the installation instructions for the server or container
      • Test the installation by starting the server or container and trying to load the default home or index page. If an error occurs, troubleshoot the installation process before continuing

Preparing a Project for Automated Migration

Because NetDynamics allowed developers immense latitude (with both positive and negative consequences), there is no way for iMT to account for all possible project permutations. This is particularly true of projects that use non-standard portions of the NetDynamics Spider API, or use this API in an unorthodox or undocumented way. Therefore, some applications will require manual preparation before being migrated by the iMT. In some cases, this preparation may be significant if a particular problematic feature is widespread throughout a project or set of projects.

Of the two automated phases, you are more likely to encounter initial difficulties during project extraction. This is normal, and is simply a consequence of the issues noted above. The good news is that many projects will not encounter any difficulties during extraction, and once an application description has been extracted from a project, it should be translatable with little or no difficulty.

Differences Between the Project Extraction Runtime and NetDynamics Runtime Environments

The iMT uses an embedded NetDynamics Connection Processor (CP) to instantiate and then extract information from a project. From the project's perspective, it is being instantiated inside a normal NetDynamics 5.x server environment. However, the extraction runtime environment differs substantially from that present in a NetDynamics server. Specifically, the JDBC Service, the PE Service, and PACs are not available to applications instantiated within the iMT's embedded runtime, nor are they necessary to extract the necessary information.

We have found that some project objects perform tasks that depend on these runtime features in their constructors, static initializers, initialization events, or non-Spider threads. The iMT automatically suppresses the firing of the NetDynamics 4/5.x-style onBeforeInit and onAfterInit events so that customer code in those events will not execute during the initialization. However, other initialization-time methods, such as static initializers, overridden init() methods, and NetDynamics 3.x-style onBeforeInit and onAfterInit events may still execute. You may need to comment out code in these methods if that code attempts to perform behaviors that cannot complete successfully within the iMT runtime. (You may leave the code in the original location and it will be automatically moved to the correct target location during translation). One can normally identify these problematic cases most easily from error messages and exceptions generated by the Extraction Tool.

Before Running the NetDynamics Extraction Tool

For the reasons given above, we generally advocate running the Extraction Tool on your project with only minimal preparation. Although it is more likely that the extraction will fail with an error, doing so will typically save you time in the overall migration process, it is usually easier and faster to detect and rectify problems using the diagnostic error information than trying to find and fix potential problems preemptively (unless potential problems are well-known).

However, to avoid several other common sources of extraction difficulties, we recommend you perform the following tasks before running the NetDynamics Extraction Tool:

Migrating ToolBox Sample Application

This section describes the automated and manual migration procedures of the ToolBox sample application.

Running the Migration Toolbox

If you don't have the Toolbox application currently running, please follow the instructions given in section Preparing your Working Environment to setup your toolbox.

Create a Toolbox Builder

  1. Start the toolbox and choose "Migrate an application" option in the Welcome dialog and press OK. With the Toolbox running, be sure that you have an empty (New) toolbox. Select the menu option Add-In -> Migration -> NetDynamics Migration Toolbox Builder.

  2. Figure shows how to invoke the NetDynamics Migration Toolbox Builder.

    A modal dialog wizard will appear.


    Figure shows a dialog box with introduction of  NetDynamics Migration Toolbox Builder.

    Select OK to proceed to the first step of the wizard.


    Figure shows a dialog box to enter the Input Application’s Name.

  3. Enter the name of the application you will be migrating in the “Input Application Name” dialog box, for e.g. ‘MigtoolboxSample’. Select OK to proceed to the next step.

  4. Figure shows a dialog box to enter the Output directory for the migrated application.

  5. Enter the directory where all materials generated by the iMT will be stored. The default is usually satisfactory and is used in this example. Select OK to display the next step in the wizard

  6. Figure shows a dialog box to enter the Application Name.

  7. Automated iMT migration will produce some J2EE infrastructure including new Java JATO files. These new files must be assigned a package. Although existing Java source in the original application will retain packaging, we still need to assign a package for these new files. There is no restriction on the package name. The default value is provided for the MigtoolboxSample application.
  8. Enter a package and select OK to display the next step in the wizard.


    Figure shows a dialog box to enter the NetDynamics project name you want to migrate.

  9. Enter the project name you want to migrate. This project should be located in ‘{MIGTBX_HOME}\work\NDProjects\’ folder.

  10. Figure shows a dialog box to enter the directory name where the WAR file is created.

  11. Enter the name of the web application archive (WAR) file into while you want to package to your application. The default value is provided for this application. Select OK to proceed to the next step.

  12. Figure shows Sun ONE Application Server archtiecture.

  13. Enter the output directory name where iMT will generate the WAR file. When you select OK on the dialog box, the toolbox builder will generate a set of tools necessary for the automated portion of the application migration process.

  14. Figure shows a dialog box confirming the generation of the tools necessary for the automated portion of the application migration.

  15. Select OK to exit the NetDynamics Migration Toolbox Builder wizard. The result of the Addin is a complete Toolbox consisting of an Extraction and Translation tool and the optional tools to automatically create the application extract archive and translate the documents. When you select the ‘branch’ for each tool on the left frame, it will display the detailed help for each tool in the right frame. The help explains each property in the tool. Click on each ‘instance’ of the tools to display the bean property panel in the right frame. Both the basic and expert properties may be edited.
  16. The Task Tools simply cause a list of other tools to be executed in order. It is usually more informative to run the tools separately so that you can carefully watch the console output. The extraction tool properties are shown here:


    Figure shows the properties of the NetDynamics Extraction Tool.

    The Translation tool properties are shown here:


    Figure shows the properties of the NetDynamics Application Translation Tool.

  17. Invoke the Migrate MigtoolboxSample Application Task tool. This tool will inturn invoke Extract-MigtoolboxSample, Translate-MigtoolboxSample and MapSpider2JATO-MigtoolboxSample tools one after the other to produce the migrated code and the application description file(MigtoolboxSample.xml).
  18. Invoke the Create MigtoolboxSample War File Task tool. This tool will invoke the following tools to produce a Web Application Archive(WAR) file to enable automatic deployment of the application to a J2EE container. This WAR file will be the only file you will need to deploy your application to the J2EE container.
  19. CopyDeplDesc-MigtoolboxSample, CopyJatoJar-MigtoolboxSample, CopyJatoTLD-MigtoolboxSample, CopyJSP-MigtoolboxSample, CopyClasses-MigtoolboxSample, CopySource-MigtoolboxSample, JarWarFile-MigtoolboxSample

  20. Invoke the Compile-MigtoolboxSample tool to compile the JATO Foundation classes and the new J2EE application components. This tool simply invokes the javac command line tool provided with the JDK.
  21. At this point, automated migration is complete and manual migration if any starts.

    The easiest way to proceed in manual migration is to load the web application into a J2EE IDE. Forte for Java EE (FFJ) is used in this example.

  22. Start FFJ 4.0 and create a new Project called OnlineBank. Make sure there are no existing file systems in the new project. Select [Project] from menu and click [Project Manager].

  23. Figure shows the procedure to create a Project in Forte for Java 4.

  24. On the Project Manager window, click New and put a project name (MigtoolboxSample).

  25. Figure shows a dialog box to enter the project name of the migration application.

  26. Right click [Filesystem] icon and select [Mount Directory] on the Explorer panel. Select ${migtbox_home}\work\output\MigtoolboxSample\war and click OK. Forte should recognize this directory as a standard WAR directory and create a WAR view in the Explorer.

  27. Figure shows how to mount the project from the local directory.

    FFJ uses the term FILESYSTEM to refer to an entry in the CLASSPATH for a project. Upon mounting the WAR directory not only will the ./war/WEB-INF/classes directory be AUTOMATICALLY part of the CLASSPATH because its a 'war' file, but each library under ./war/WEB-INF/lib will also be added (ZIPs and JARs).

    The Java source will need to be compiled. It is very important to enable 'deprecation' flag in the compiler.When you compile your translated application and the 'deprecation' flag is enabled, the compile will produce a report of each line of code which uses a 'non-targeted' API. The intention here is to reach a complete compilation as quickly as possible and produce a report on the tasks required for manual migration.

  28. Edit Project properties (Compiler: External Compiler:) and set deprecation to TRUE. Select [Tools] from menu and click [Options]. Expand the ‘Building’ and then ‘Compiler Types’ nodes and set [deprecation] as True for External Compilation on Options window as shown below:

  29. Figure shows how to set the deprecation flag in Forte for Java 4.

  30. In the project view in the Explorer, select the Classes branch and right click to menu and choose Compile ALL. All the migrated code in
  31. ${migtbox_home}\work\output\MigtoolboxSample\war\WEB-INF\classes\

    and the new generated JATO infrastructure in

    ${migtbox_home}\work\output\MigtoolboxSample\war\WEB-INF\classes\

    Everything should compile immediately.


    Figure shows how to compile the Java Source code in the migrated application.

    The compiler generates some warnings, they are shown here:


    Figure shows Sun ONE Application Server archtiecture.

  32. These warnings should be fixed to complete the manual migration of the application. The final web application may be deployed on any J2EE web container. In FFJ you may export a WAR file and deploy on Sun ONE Application Server 7. You may also run the web application directly in FFJ using the built-in TomCat server.
  33. Add a Server Module Group in FFJ. Right click on WEB-INF branch in Explorer, select [New]->[JSP&Servlet]->[Web Module Group] and add a server group. Accept the default on the wizard screen and simply chose 'Finish'. A new element under WEB-INF in the Explorer appears called 'ServerConfiguration'. Add the current web application by right clicking on [Server Configuration] branch in Explorer and select [Add Web Module]. Provide a servlet context name on [Add Web Module] window. For example "Demo".

  34. Figure shows how to create a Web Module.

  35. Execute in FORTE by right clicking on [Server Configuration] branch in Explorer and select [Execute].



Previous      Contents      Index      Next     


Copyright 2003 Sun Microsystems, Inc. All rights reserved.