Appendix B
Sun ONE Migration Toolbox

Sun ONE Migration Toolbox (S1MT) is used primarily to migrate applications built on NetDynamics or Kiva/NAS platforms to Sun™ ONE Application Server or any J2EE compatible containers. The main interface for the Sun ONE Migration Toolbox is what we call the Toolbox application, or the Toolbox GUI. This application can be invoked by running the %MIGTBX_HOME%/bin/toolbox.bat script (provided the setenv.bat file has been customized appropriately, see README.txt for more information).

---

Supported Platforms

Microsoft Windows NT 4.0 and Windows 2000 currently support S1MT. Although it is expected that the application can be run on other Win32 platforms (Windows 95/98/Me), these platforms have not been tested and may require additional configuration beyond that specified in the S1MT installation documentation.

The Toolbox require atleast JavaSoft JDK 1.2.2 (JDK 1.3.1 has been tested) to run successfully.

---

Migration

The toolbox is set of tools which perform different aspects of migration. S1MT 1.2.3 support migration from NetDynamics and Kiva/NAS platforms. Each platform has its own Toolbox Builder which when executed will create a set of tools used to migrate a application. Kiva Migration Toolbox Builder creates tools for Kiva/NAS application migration and similarly NetDynamics Migration Toolbox Builder is used for migrating NetDynamics applications. The following figure shows you how to invoke a toolbox builder.

Toolbox Builder

You will use the same basic set of tools for each migration you perform, but each tool will need to be customized to that particular migration. Creating each of these tools can be a tedious task and prone to inconsistencies in naming conventions and layout of directory structures. Therefore, we've created a toolbox add-in (a pre-configured, ready-to-run tool) to simplify the process of creating these tools and setting their properties appropriately. Many of the tools have similar or even the same properties where consistency is important to the success of your migration.

Kiva Migration Toolbox Builder

The following are the steps for creating a new toolbox using the Kiva Migration Toolbox Builder add-in:

If you don't have the Toolbox application currently running, start the Toolbox and select the menu option Add-In|Migration|Kiva Migration Toolbox Builder.
After a few moments, you will be prompted by a series of dialog boxes that will request some information. This information will be used by the Toolbox Builder to fill property values for the tools it generates. Some of the properties that you are not prompted for will contain defaults that may or may not need to be modified after the tools are created by the Toolbox Builder.
First, you are prompted for the package which the new JATO Application will be placed in. The best way to understand what this means is to run the OnlineBankSample migration and learn how a new package is created under ./war/WEB-INF/classes to contain the JATO material. Although all the existing Java code is left in the same package, there is a need to create some new Java code for the JATO Application infrastructure. The new package is for this code. Please note that ALL Java source from the original application may remain in the same package. It is only the new Java source for the JATO resources which need a new package defined. No matter what package you choose (e.g. com.iplanet.migration.samples.onlinebank), the last name in the package will be used as the default directory name for the migration results. You can override this directory location in the next panel; we recommend taking all the default values.
Next, you are provided the choice of using the Automatic Application Extract Archive Wizard. This wizard will help create tools for creating the application extract archive. If you choose Cancel then you are simply asked for the application extract archive (ZIP/JAR) path name. This is the name of the zip or JAR file which contains all the source for the application. In this case the archive must have been created manually beforehand and the wizard continues with encoding specifications.
If you choose OK for the Automatic Application Extract Archive Wizard then you are asked to enter the root directory to the application source (this is normally the ./nas/APPS directory).
Next, you are asked to provide a list of top level packages in the application source directory pertinent to this migration. If all the source in the directory is included then you can skip specifying a value.
Next, you are asked to provide a list of file extensions which will be included in the Application Extract Archive.
If you choose OK for the Automatic Application Extract Archive Wizard then you will see a Task tool and Copy Directory tool and Java tool added to the toolbox.
There are two (2) panels which ask for the character encodings for Java source and query files. There are many customers who have Java source in an alternate character encoding (not ASCII). For instance, it is common for Asian developers/customers to use double-byte character source files. In a change from the S1MT BETA, only one (1) encoding value is allowed for file type. It is assumed that there is a common encoding standard within an application. If there are varying encodings then the application descriptor XML file may be edited accordingly after Extraction. Please note that S1MT 1.2.3 attempts to automatically discover character encoding of HTML templates by inspecting the <meta> tags in the source files. However, the migrator should carefully review the application descriptor XML file for encoding dispositions to ensure proper translation.
At this point the Kiva Extraction and Translation Tools are added to the toolbox.
Lastly, you are provided the choice of using the Automatic Static Document Translation Wizard. This wizard will help create tools for assembling the static document content and translating appropriate documents fixing the URLs for AppLogic invocation and copying the documents to the result WAR directory structure.
If you choose CANCEL then the builder exits. If you choose OK, you are asked to enter the location of the document root for the application and another Task tool, JAR tool, Document Translation tool and Copy Directory tool are added to the toolbox.
Save the toolbox to disk by selecting the menu option File|Save and give it a name.

Tools generated by Kiva Toolbox Builder are shown here:

Invoking the Tools

You are now ready to migrate your application by invoking the generated tools; extraction first and then translation. Before invoking each tool, inspect its properties first and make adjustments as needed. In general, if you've provided desirable initial values to the Toolbox Builder, none of the properties will need to be adjusted.

Note	The Toolbox Builder created one Task Tool in your toolbox which you can use to invoke all of the other generated tools at once. However, we recommend invoking each tool individually until you have migrated one or two applications and become familiar with each tool's output.

Tools Created by Kiva Migration Toolbox Builder

KIVA Application Extraction Tool

This tool reads a zip or JAR file called the application extract archive containing Kiva application files and creates an XML document called an application description file. The application description file contains high level information describing the application including disposition of each file found in the application extract archive.

This tool assumes, as input, the pre-existence of a zip file containing all of the original NAS/KIVA application source (i.e. templates, applogic java files, other application specific resources). The zip file need not contain the actual original class files since the migration effort will be altering the source files.

Creation of the application description file is the first step in the automated migration process. Although this file may be useful for other purposes, its main use is as input to the application translation process using the Kiva Application Translation Tool (com.iplanet.moko.nas.tools.KivaTranslateTool).

KIVA Application Translation Tool

This tool reads both a zip or JAR file called the application extract archive containing Kiva application files and also an XML document called an application description file. This tool takes as input an application description file and uses it to generate a set of equivalent J2EE components and files. The application description file (an XML document) is produced as the result of using the Kiva Extraction Tool (com.iplanet.moko.nas.tools.KivaExtractTool) to extract information from a set of source Kiva projects. Use of the translation tool is the second step in performing the automated migration of a Kiva application.

Copy Directory Tool

Copies the contents of a source directory to a target directory

JAR Tool

JARs all files in the source directory and all subdirectories

NetDynamics Migration Toolbox Builder

The following are the steps for creating a new toolbox using the NetDynamics Migration Toolbox Builder add-in:

If you don't have the Toolbox application currently running, start the Toolbox and choose the "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.
After a few moments, you will be prompted by a series of dialog boxes that will request some information. This information will be used by the Toolbox Builder to fill property values for the tools it generates. Some of the properties that you are not prompted for will contain defaults that may or may not need to be modified after the tools are created by the Toolbox Builder.
First prompt: Enter the logical application name. This is the name of the entire application, which may include more than one NetDynamics project. If the application is only one project, then it is not recommended to use the project name as the application name. For example, if your project is called foo, then call your application fooapp rather than just plain foo. This will prevent confusion with other similar properties and avoid difficulties later during deployment.
After you've entered an application name, the Toolbox Builder will prompt you for more information, providing default values when possible. We recommend taking all the default values.
Once you have finished entering information, The Toolbox Builder will create several tools in your current toolbox. Save the toolbox to disk by selecting the menu option File|Save and give it a name. Using the application name (the value from the first promptófooapp in our example here) as the name of the toolbox is recommended.

Tools generated by NetDynamics Toolbox Builder are shown here:

Invoking the Tools

You are now ready to migrate your NetDynamics application by invoking several of the generated tools. Before invoking each tool, inspect its properties first and make adjustments as needed. In general, if you've provided desirable initial values to the Toolbox Builder, none of the properties will need to be adjusted. (NOTE: The Toolbox Builder created one or more Task Tools in your toolbox which you can use to invoke several of the other generated tools at once. However, we recommend invoking each tool individually until you have migrated one or two applications and become familiar with each tool's output.)

Tools Created by Kiva Migration Toolbox Builder

NetDynamics Extraction Tool

This tool gathers as much information as possible from the source NetDynamics project or projects and then writes this information to an XML file called the application description file. This application description will serve as the input to the Application Translation Tool.

Before invoking this tool, check the following properties for accuracy:

ProjectsDirectory is the path to the NetDynamics projects directory used during extraction. The default value is %MIGTBX_HOME%/work/NDProjects. We recommend placing all the NetDynamics projects you intend to migrate in this directory.

All other properties should be fine with their current values unless you made an error during the prompting stages of the Toolbox Builder add-in. The other properties will be discussed in detail later in this document.

Save the toolbox if you made any changes and invoke the tool. The XML output file (the application description) will be written to the location specified by the OutputDirectory property.

You may open and browse the application description file if you wish to understand the details of the project extraction. Using an XML browser like XML Spy is recommended. We highly discourage editing this file as mistakes introduced here may significantly affect the translation phase, causing it to fail completely or generate faulty output

Application Translation Tool

This tool uses the application description file generated by the NetDynamics Extraction Tool to output a set of J2EE-compliant components that accurately reflect the structure of the behavior of the original NetDynamics application.

All other properties should be fine with the current values unless you made an error during the prompting stages of the Toolbox Builder add-in. The other properties will be discussed in detail later in this document.

Save the toolbox if you made any changes and invoke the tool. The new J2EE components will be written to the location specified by the OutputDirectory property.

Additionally, this tool places a migration log file (MigrationLog.csv) in the translation output directory. This file indicates various items that were identified during translation as requiring additional or special migration attention. Our reason for generating this file is to alert migration developers to those items that were not automatically handled by the translation, and to record information that was otherwise not carried forward during translation. This file generally serves as a minimal task list for the manual portion of the migration (there will likely be other tasks as well not related directly to the translation).

Regular Expression Mapping Tool

This tool, also known as the Regexp Tool, uses a set of XML-specified match and replace specifications to effect changes within files (note, this tool uses the Perl 5 regular expression syntax). The Toolbox Builder generates a Regexp Tool that is preconfigured to replace common Spider API Java constructs with equivalent JATO constructs in your migrated Java source files.

Before invoking this tool, check the following properties for accuracy:

SourceDirectory is the location of your migrated application code. Please make sure that this directory does not also contain the JATO source files, as the processing of those files may cause unexpected problems.All other properties should be fine with the current values unless you made an error during the prompting stages of the Toolbox Builder add-in.

Save the toolbox if you made any changes and invoke the tool. The migrated source files will be processed and any changes that occur will be written to the console. Before any file is modified, the tool will backup the original file in its original location with a .orig file extension.

IMPORTANT: At this point, you have completed the automated migration phase, and must now port the Java code in the migrated application to use the J2EE/JATO API instead of the NetDynamics Spider API. The remaining tools described below will be useful for packaging and deploying your application once manual migration has been completed, with one exception: the migrated application should compile successfully at this point and minimally run if deployed (pages can be invoked); however, the application may not be functional if you've used any of the NetDynamics Spider API. Therefore, unless you want to simply make a sanity check or check the migration of non-Spider dependent features, we recommend porting at least part of the migrated application before continuing.

Java Compiler Tool

This tool is a convenient way to compile the JATO Foundation Classes and the new J2EE application components with one click. This tool simply invokes the javac command line tool provided with the JDK.

There should be no properties that need adjusting in this tool unless changes were made to the output directory properties of the previous tools. All of the properties will be discussed in detail later in this document.

Save the toolbox if you made any changes and invoke the tool. All of the java class source files (.java) under the directory specified by the SourceDirectory will be compiled.

Copy Directory Tools (Create WAR File Directory Structure)

This tool copies directories/files from one location to another with a file filter capability. The goal of the generated tools of this type is to create a "WAR file ready" directory structure. Running the first four Copy Directory Tools will copy the deployment descriptor, tag lib definition, JSPs, and Java classes into the appropriate directories so that the Jar Tool can be used to create a WAR file to be deployed in your J2EE container.

The instance of the Copy Directory Tool labeled CopySource is optional. The source files are not needed in your production WAR file, but you may find it helpful to keep a copy of the source files with your deployed application to ensure proper version control (these may also come in handy if a quick fix is necessary at the deployment site). These source files will not be visible to any application clients, and will therefore remain safe on your deployment server.

All of the properties should be fine with the current values unless you made changes to the output directory properties of the previous tools. All of the properties will be discussed in detail later in this document.

Save the toolbox if you made any changes and invoke the first four copy directory tools (CopyDeplDesc, CopyTLD, CopyJSP, CopyClasses). Invoke the fifth copy directory tool (CopySource) if this makes sense for your environment. Once these tools have been invoked, the appropriatly filtered files will be written to the directory specified by each of the tools' respective OutputDirectory property. The application is now ready to be "WAR'ed".

Jar Tool

This tool uses the JAR command line tool from the JDK to create a WAR file using the directory structure created by the previous copy directory tools. This WAR file will be the only file you will need to deploy your application to the J2EE container. (The iAS deployment procedure is discussed in the JATO Deployment Guide). Each container generally has its own deployment procedure; please follow the instructions for your container.

All of the properties should be fine with the current values unless you made changes to the output directory properties of the previous tools. All of the properties will be discussed in detail later in this document.

Save the toolbox if you made any changes and invoke the tool. The WAR file will be created and written to the location specified by the OutputDirectory property. The application is ready to be deployed.

---

Tools and Toolboxes

Toolboxes are persisted to disk in the format of a toolbox file (.toolbox). Individual tools of the toolbox are contained in the toolbox file in a serialized object format. These individual tools can exist outside of the toolbox file as a tools file (.tools) in a similar format. There are several menu commands that allow you to create, copy, delete, and merge two toolboxes together, as well as import and export individual or groups of tools.

Creating New Tools

To create a new instance of any tool, use the Tool|New menu option and select the type of tool you would like to create (Extraction, Translation, Compilation, etc.). You will notice the new tool will be added to currently opened toolbox in the toolbox tree. It will be grouped with other tools of its type and will have a default name of the form <ToolType><##>, like CopyDirectoryTool7. You can triple-click the tool name or press F2 to rename it as you wish. Spaces are allowed in tool names.

Cloning Tools

To create a copy of a current tool, use the Tool|Clone menu option and a new tool of the same type will be created with the same properties as the original. Rename and adjust properties as needed.

Deleting Tools

To delete a tool, use the Tool|Delete menu option and the tool will be removed from the toolbox. You will be prompted verify your delete tool command, but there is no undo action. You may select several tools to delete at once by holding down the Ctrl or Shift keys while selecting additional tools.

Importing & Exporting Tools

You may have many different toolboxes (.toolbox files) that are focused on different NetDynamics application migrations. With the import and export commands, you can export a tool to a .tools file and then import it into another toolbox (.toolbox file).

To export a tool, open the toolbox with the tool you wish to export, select the tool or tools in the toolbox tree, then use the File|Export menu option and name the .tools file to export the tool. The tool will not be removed from the current toolbox.

To import the tool into another toolbox, open the toolbox you wish to be imported, then use the File|Import menu option, browse to the location of the .tools file you wish to import, then save the toolbox.

Toolbox Merging

If you have two separate toolboxes and would like to merge them into single toolbox you use the merge toolbox feature of the Open Toolbox menu option. To merge two toolboxes into one toolbox, open one of the toolboxes, and while it is open, open the other toolbox. You will be prompted to replace the existing toolbox, merge the new toolbox with the already-open toolbox, or cancel the operation.

---

Troubleshooting

IMPORTANT: Before continuing, make sure you have the latest S1MT patches available from the Sun ONE Migration Website. We will be releasing patches regularly as we discover and diagnose difficulties. We will release most of these patches to address problems found by users of the S1MT. Please submit any problems you encounter to the S1MT team so that we can diagnose the problem and issue a patch if necessary.

Toolbox Installation & Configuration

If you have difficulty running the Toolbox application, consult the following:

Ensure that all the %MIGTBX_HOME%/bin/setenv.bat script is customized for your environment. Because of limitations of the JDK, you may not install the S1MT in a path containing directory names with spaces. For example, do not unpack the archive in your C:\Program Files directory. We recommend unpacking the archive either in c:\iPlanet or c:\.
There are known problems using older versions of WinZip to unpack archives created with the JDK's zip/jar tools. Doing so will cause files to be truncated during unpacking, resulting in file lengths of zero bytes. Therefore, please ensure that you are using the latest version of WinZip when unpacking the S1MT archive (http://www.winzip.com).
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.
Because many development machines have several installed copies and/or versions of the JDK, be sure you know which copy of the JDK you are using. Set the JAVA_HOME environment variable in the %MIGTBX_HOME%/bin/setenv.bat file to ensure you are running the preferred copy with the Toolbox application.

Extraction

For the most part, as we've mentioned above, extraction of an application description is the most likely step in which you will encounter errors or difficulties. Also as we've already mentioned, this is frequently a normal part of the migration process and shouldn't discourage you if you are following the steps in previous sections. If you are having difficulties not covered above, consult the following tips.

General Issues

During extraction, ensure that all external classes (non-NetDynamics project classes) are present on the Toolbox's classpath. The easiest way to make these classes available is to place JAR files or unpackaged classes in the %MIGTBX_HOME%/lib/ext directory. Classes and JARs in this directory will automatically be added to the Toolbox classpath upon startup. If this solution is unsatisfactory, you may either add the classes to your classpath or edit the %MIGTBX_HOME%/bin/setclasspath.bat file.
Note the summary at the end of the output from the extraction and translation tools to determine if any project objects failed the automated process.
Because of a limitation inherent in using the embedded NetDynamics runtime, exceptions thrown during extraction may not impact the reported tool status, and therefore the tool may report success when in fact the extraction failed. Therefore, we caution users to note and investigate all exceptions thrown during extraction. In some cases, we have seen seemingly innocuous exceptions cause side effects which significantly impacted the fidelity of extracted project information. For example, during one extraction, we encountered a ClassNotFoundException from the NetDynamics runtime looking for a (seemingly) non-critical class. This exception later prevented certain DataObject properties from being extracted, resulting in a non-functional migrated application. Therefore, to ensure the best possible migration, always be sure to eliminate all sources of exceptions during the extraction phase before continuing.
Note that because of a feature of the embedded NetDynamics CP, two copies of a project are instantiated during project extraction, one before extraction and one after. This is generally harmless, but if the project throws exceptions during instantiation, you will see two sets of stack traces in the Toolbox's console log.

Non-Fatal Error During Extraction

If only part of the automated migration succeeds (or fails), we recommend the following:

Find and correct the cause of the failure using the tips in the above Sections and re-run the extraction or translation
If a problem occurs with NetDynamics migration, create a new project in the NetDynamics Studio and import the problematic objects. Simplify them until you can get this project to run through the appropriate tool(s). Introduce these files back into the original, now-migrated project.
Migrate the failed objects by hand. This is not as hard as it may sound. The JATO framework was also designed for manual application authoring. Using the templates in the application package, follow the example of a migrated object of the same type. Documentation has been created to assist in creating new JATO objects manually. Check the "Files" location of the JATO eGroups forum.
Diagnose the problem as thoroughly as possible and consult the discussion forums or the S1MT team.

Fatal Error During Extraction

Ensure the following items are not factors in the failure (in approximate order of likelihood):

Incorrect environment settings. Check the settings of your %MIGTBX_HOME%/bin/setenv.bat file and ensure they are appropriate for your machine.
Missing external classes
Incorrect tool property settings. Ensure that the Extraction Tool has valid property settings
Use of non-existent runtime feature in a critical location (such as a class initializer or initialization of non-Spider threads to perform background tasks)
Non-present links directory or corrupted class files
Use of incorrect JDK version or platform
Conflicting class file versions in boot classpath (such as those present in the JDK's extension directory)

If none of the above items are discernable factors in the problem, you may have encountered a bug in the S1MT. We reiterate that because of the latitude NetDynamics allowed during project development, Sun ONE cannot anticipate all possibilities and thus ensure a trouble-free migration for all customers. However, the S1MT is committed to making the migration process as painless as possible. Please report any problems to the S1MT team and/or the discussion forums so that we may address them and issue patches as necessary.

Translation

If you encounter an error during application translation, do the following first:

Ensure that your application description file looks complete and is valid XML. Use a tool like XMLSpy or Internet Explorer to open the document and view it.
Ensure that the Translation Tool settings are correct
Verify your environment settings in the %MIGTBX_HOME%/bin/setenv.bat file and ensure they are appropriate for your machine
Ensure that you have a complete Toolbox installation

If none of the above items are discernable factors in the problem, you may have encountered a bug in the S1MT. We reiterate that because of the latitude NetDynamics allowed during project development, Sun ONE cannot anticipate all possibilities and thus ensure a trouble-free migration for all customers. However, the S1MT is committed to making the migration process as painless as possible. Please report any problems to the S1MT team and/or the discussion forums so that we may address them and issue patches as necessary.

Post-Migration

Some problems may arise after migration or during testing. In general, such problems will need to be posted to the discussion forums or discussed with the S1MT team. However, before contacting others, note the following:

The module URLs for each servlet and display URLs for each view bean are set to certain defaults during project translation. These defaults will likely be correct for your deployment environment, but may not be in some cases. Please consult the JATO Deployment Guide or the discussion forums for information on how to configure these URLs differently for deployment.
There are inconsistencies in the way JDBC drivers treat certain column types. JATO contains a number of options that may need to be modified in order for your application to work against your specific database. If you are having difficulty running the migrated application against your target database, please consult the Sun ONE Migration website and discussion forums for information on specific database-related tweaks.

Previous      Contents      Index      Next

---

Copyright 2003 Sun Microsystems, Inc. All rights reserved.