Migration from KIVA/NAS 4.1 to Sun ONE AS 7

Kiva/NAS 4.1 Java AppLogic applications can be migrated to J2EE web modules using iPlanet Migration Toolkit (iMT 1.2.3). The resulting web modules leverage JATO and a thin KFC (Kiva Foundation Classes) adaption layer to support running the AppLogic code on any J2EE web container.

Introduction

Before starting the migration process, be sure you have read the release notes so that you are aware of the latest information and any issues that might be relevant to you and your environment. Also refer to %MIGTBX_HOME%/bin/readme.txt file. This 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 later sections.

%MIGTBX_HOME% represents the directory in which you installed/unzipped the Sun ONE Migration Toolbox (S1MT).

Migration Preparation

Migration Process Overview

There are two main phases to full migration of a proprietary AppLogics application 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 preparing the AppLogic application source for migration and then using the S1MT to perform automated extraction and translation. The input to this phase is a user provided archive (JAR/ZIP) containing the original application source files (AppLogic files, GXR, query files, templates, static content and regular Java source and properties). This file is called the application extract archive. Using a standard Java archive (JAR/ZIP) to package the existing application and NOT requiring a NAS/iAS runtime environment allows the migration environment to be more flexible; migration may even be performed remote from the customer site since the runtime infrastructure (databases, web servers, app servers) is only needed during manual migration for unit testing. Essentially, this archive is just the targeted contents of the ./nas/APPS directory of the application server and document root of the web server. The Extraction Tool for KIVA AppLogics will read this archive and create the application descriptor. iMT v1.2.3 now supports the automatic creation of the application extract archive (See the Kiva Migration Toolbox Builder 'Addin' from the 'Addin' menu).

The application descriptor (an XML file) is used to guide the Translation Tool on the disposition of each file in the archive. The migrator may need to adjust the application descriptor. See Technote on editing the application descriptor. After running the Translation Tool the result is a partially (or in some cases, fully) migrated application consisting entirely of J2EE-compliant components based on JATO and the KIVA Migration library composed in a web application archive (deployment descriptor, servlets, JSPs, Command, query files).

The output from the translation process entirely transforms HTML templates to JSPs and converts GX tags to new JSP tags used with the KIVA migration library. AppLogic source files are adjusted to use the KIVA migration library (minimal change mostly to import statements). The translation process also creates the web application infrastructure including all the components of the JATO application and direct command invocation module. However, the translation phase does not automatically port code written to proprietary KFC APIs which are "non-targeted" in the KIVA migration library. This porting will be the primary task during the manual migration phase. iMT v1.2.3 now supports the automatic migration of static documents specifically with help in fixing URLs.(See the Kiva Migration Toolbox Builder 'Addin' from the 'Addin' menu) and the new Kiva Document Translation Tool.

Manual Migration Phase

In general, the manual migration phase consists of reviewing the automatically migrated application output and porting non-targeted KFC API code to J2EE-specific code. Understand that this process does not typically require a redesign of the application or its architecture. In many cases, code which needs manual attention is clearly outlined in a deprecated compile using the MIGRATION version of the KIVA Migration library [kivaMIGRATION.jar]

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, it is strongly recommended that you remove all JAR files from your JDK's extension directory (%JAVA_HOME%/jre/lib/ext) while running the Toolbox application. All the classes necessary for running the Toolbox are included with the distribution. Please note that simply renaming the JAR files in the extension directory is not sufficient; you must move them to a different location.
3. Identify the AppLogic based application which is to be migrated.
4. Generate the application extract archive. In the simplest case, it is a ZIP or JAR file containing all files and directories under ./nas/APPS which are related to the application. The iMT for AppLogics DOES NOT actually load or run any Java classes or libraries from your application. All extraction and translation is done at the source level so it is not a problem if the archive does not contain all dependent classes or libraries - these will only be needed while compiling after automated migration.
5. At this point, you may also want to install Sun ONE Application Server 7 (known as S1AS), Forte for Java 4.0 EE 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 AppLogic and the KFC allowed developers immense latitude and practically no prescription, there is no way for the iMT to account for all possible permutations. For this reason, it is strongly recommended that customers engage Sun Professional Services to assist in preparing projects for migration

iMT Kiva BETA customers discovered that during manual migration procedures portions of the existing code caused obstacles in compiling the code in the JDK 1.3.1 an J2EE environment. The following is a list of considerations and activities which should be performed before a migration is attempted.

You have to prepare the application code for J2EE environment before using the iMT. The code should be compiled against JDK 1.3 (or at least JDK 1.2.2) and the J2EE APIs. For instance, the iMT comes with the kfcjdk11.jar library for the KFC. This is provided so that customers may compile their existing application in an advanced J2EE capable IDE like Forte for Java (FFJ). A standard AppLogic application should be able to compile in FFJ by simply adding the kfcjdk11.jar to the classpath (FileSystems). Prior to compiling, the deprecate flag should be set (TRUE) to expose deprecated code.

When customers are already using JDBC it is highly recommended that the database services be re-factored for the latest third party drivers (JDBC, Oracle, and Sybase) as recommended by the vendors for the new JDK.

In order for exact migration tasks to be identified and sourced, all special considerations would need to be assessed first. In simpler terms, we need to identify anything "out of the ordinary" which may be in the code. This includes code patterns or use of Java services which conflict with a concurrent server pattern of the J2EE container contract with the developer. For instance, if the code used java.lang.Thread directly or shared resources, this code will need to be inspected for suitability in J2EE.

Some customers use other third party Java services which may themselves may not be ready for J2EE even though the customers code is. For instance, an old version of CORBA (e.g. Visibroker for Java, or Iona) may need to be upgraded.

J2EE has the requirement that logical applications shall be deployed into separate web applications as WARs. It is easier to isolate logical applications and common libraries before migration proceeds.

Customers need to prepare for the change of external URLs. No matter what technique is used to migrate to J2EE, URLs will change and therefore a strategy is required for bookmarks and previously published URLs. The iMT v1.2.3 release provides some support for automated migration of static documents URLs. Nevertheless, customers will need to survey the existing system to account for all the changes which will need to be managed.

Preparing the GXR file

In order for the extraction phase to perform accurately when generating the application descriptor, a GXR file is needed to identify the AppLogic files and the AppLogic names used during NameTrans and URLs. Most applications use at least one GXR file or at least one for each package in the application. The extraction phase requires one (1) single GXR file in the application extract archive. If you have more than one GXR file, combine them. If you do not have a GXR file you will need to compose one using proper GXR syntax; the source data can be acquired by dumping the KIVA registry (./nas/bin/kreg -save temp.out SOFTWARE). In short, the extraction tool uses the GXR file to determine which files in the application extract archive are AppLogic source files and also develops a mapping of GUID to AppLogic name to AppLogic class name.

Before Running the Extraction Tool

If your AppLogic application is entirely based on app server side Java and material (query files, HTML templates, AppLogic source, support Java source, etc.) then you can usually create the application extract archive by zipping up the relevant contents of the ./nas/APPS directory. However, if the application also contains static content then you have some additional work to do. It is common and more efficient to have static content located on the Netscape Enterprise web server and leave the dynamic content on the application server side (AppLogics and templates). Depending upon your J2EE server vendor, you may benefit from this separation or it may be helpful to combine the static content and dynamic application resources. The static content may be added to the WAR during or after automated migration - this is usually the easiest.

There is one important consideration when migrating from original AppLogics application to J2EE JATO using the iMT. URLs which invoke AppLogics (POST/GET) are absolute URLs (e.g. http://host/cgi-bin/gx.cgi/AppLogic+HelloWorld) After migration, the URLs become relative to a context defined by the ServletContext and therefore absolute URLs should be avoided. The transformation of URLs is different for static content and dynamic content (HTML templates). The iMT maps all AppLogics to JATO Command implementations in a special JATO module called the direct command invocation module. Since all translated AppLogics are invoked from the same path within the ServletContext, the intra-AppLogic invocations (URLs) in the resulting HTML markup are the most predictable. Therefore, all AppLogic invocation URLs are translated as if intra-AppLogic is in order. When there is static content among the HTML templates in the application extract archive, the AppLogic URLs will need to be adjusted since the context of the static content will most likely NOT match the path in the ServletContext for the direct command invocation module (ModuleServlet). The OnlineBankSample application migration demonstrates the need to make this adjustment and utilizes the automatic translation of static documents using the Kiva Document Translation Tool.

Migrating OnlineBankSample

This section describes the automated and manual migration procedures of the onlineBankSample to J2EE.

Running the Migration Toolbox

Install iMT 1.2.3, if you have not installed it already and refer to "Migration Preparation" section for details on installing and starting iMT. Make sure that you edit the %MIGTBX_HOME%\bin\setenv.bat to account for the installation location of the iMT and the JDK home dir.

Create a Toolbox

1. Select the Kiva Migration Toolbox Builder from the Addin:Migration menu.





A modal dialog wizard will appear.

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

2. 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 OnlineBankSample application.

Enter a package and select OK to display the next step in the wizard.

3. 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.

4. The Automatic Application Extract Archive wizard will help create tools to automatically build the archive. If you choose OK then proceed to Step (5) otherwise Cancel will show the Extract Archive selection dialog (see below)

which allows you to specify the manually created archive. This is useful if you already have invested time in the extract archive and you are just building a new Toolbox.

If you choose OK to the Automatic Application Extract Archive wizard you will see the following dialog:

5. Select OK to accept the default and display the next step.





6. Select OK to accept the default BLANK list and display the next step in the wizard.

7. Select OK to accept the default, generate three new tools for the toolbox and display the next step in the wizard.

8. The OnlineBankSample only contains Java source which is ASCII encoded so accept the default. When you are migrating your own application, if you have Java source using another character encoding (e.g. Japanese Shift_JIS) then be sure to specify the encoding used. Select OK to display the next step in the wizard.

9. The OnlineBankSample only contains Query files which are ASCII encoded so accept the default. When you are migrating your own application, if you have Query files using another character encoding (e.g. Japanese Shift_JIS) then be sure to specify the encoding used. Select OK to create the Kiva Extraction and Translation tools in the toolbox and display the next step in the wizard.

10. iMT v1.2.3 now provides assistance automatically translating static HTML documents and combining them with the WAR file. If you choose the skip this feature the wizard exits and the toolbox is complete. For the OnlineBankSample, we will Select OK and use the automated feature.

11. Select OK to accept the default location of the document directory for the OnlineBankSample and proceed to add four (4) new tools to the toolbox and exit the wizard.

Click `OK' to complete the generation of the necessary tools. 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. Please remember to select the 'branch' for each tool to 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.

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:

The Translation tool properties are shown here:

12. Invoke the CreateAppExtractArchive-onlinebank Task tool. This tool runs the CopySrcAll-onlinebank and JarExtract-onlinebank tools one after the other to produce the application extract archive

%MIGTBX_HOME%\work\onlinebank\archive\onlinebankApps.jar

13. Invoke the Extract-onlinebank. This tool runs very quickly. The trace of the tool execution is shown in the Console frame. It will introspect the application extract archive, concentrating on GXR files to produce the application descriptor XML file. You must review the application descriptor and sometimes edit it so that the files are organized properly so that the Translation tool clearly understand the disposition of each file (including the proper encoding) in the archive. For iMT 1.2.3 the Extraction tool will automatically discern the encoding of the HTML templates. Please review the application descriptor to ensure that the proper encoding was selected for each template. The location of the application descriptor is

%MIGTBX_HOME%\work\onlinebank\appdesc\onlinebank.xml

and it is helpful to use an XML editor to navigate and edit this file carefully. Here is a view of a portion of this file in XML Spy.

14. Invoke the Translate-onlinebank tool. It takes a little longer than extraction and the time will depend on the number of AppLogic source files, Java files and Html templates you have in the archive. ALWAYS review the Console output when Translating to see if errors are reached. The Translation tool will usually skip past errors and continue to translate the rest of the application. It is easy to miss a WARNING or ERROR in the large trace output. You may change the expert properties to enable debugging and verbose tracing to see the real detail of the translation including use of the internal calls to Regular Expression mapping rules and element processing. The results of translation are placed in the 'migrated' directory under output directory

A complete J2EE JATO Web Application is created under 'migrated/war'.

15. Invoke the FixStaticDocs-onlinebank Task tool. This task will call in order the JarDocs-onlinebank, TranslateDocs-onlinebank and CopyDocs2War-onlinebank so that the static content URLs for AppLogics are fixed and the content is copied to the document root of the WAR.

At this point, automated migration is complete and manual migration 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.

16. 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].

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

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

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). See the Filesystems for the OnlineBank project below

Here is the document root of the new web application (see below). Notice that some static content has been translated to JSPs and the HTML templates have been translated to JSPs.

Here is the new layout of Java classes in the web application (see below). Notice that the original Java source retains original packaging. The AppLogics are translated to JATO commands and very little code is affected. The new JATO source files are placed in the new package specified as a property in the Translation tool.

The Java source will need to be compiled. It is very important to enable 'deprecation' flag in the compiler. The Translation tool automatically placed the debug or 'migration' version of the KFC adaption library in the WAR. When you compile your translated application using this library 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. Even if the application uses 'non-targeted' APIs, as long as it compiles it will run; although it may not function properly since non-targeted API are non-functional (e.g. return null or GXE.FAILURE). This is valuable because the migrator may incrementally migrate portions of the application and test these portions without being burdened with having to totally migrate the application. In other words, the migrated AppLogic JATO Commands may be tested one at a time. Another value proposition is that the deprecation report is a nice way to determine how much work there is to do.

19. 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:

20. In the project view in the Explorer, select the Classes branch and right click to menu and choose Compile ALL. All the migrated code (AppLogics, etc.) in

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

and the new generated JATO infrastructure in

${migtbox_home}\work\output\onlinebank\migrated\war\WEB-INF\classes\com

Everything should compile immediately.

There are six uses of NON-TARGETED SESSION KFC API's in the OnlineBankSample and three uses of the NON-TARGETED "commit" method of ITrans in the version of the iMT.

The 'session' APIs are the most commonly found non-targeted APIs. In the KIVA Application Server and KFC, developers could optionally supply an ISessionIDGen reference to any of the 'session' APIs. This interface allowed the developer to control the Session ID and related behavior. There is no such capability in J2EE. Applications which used ISessionIDGen will need to manually redesign that portion of the application. Most developers chose not to use this feature by providing a 'null' object reference to the APIs. Nevertheless, since ALL the KFC 'session' APIs required this parameter and the ISessionIDGen type is non-targeted, ALL the KFC 'session' APIs are non-targeted too. There are alternative APIs provided for most of the non-targeted methods which do NOT require the ISessionIDGen parameter. The migrator will need to revise each case of non-targeted 'session' APIs so that the alternative APIs are used instead. Usually, these 'session' APIs are located in one or few places in the application so it should not be a costly manual change. Please note that there are two special cases in the 'session' APIs. The IAppLogic.saveSession(ISessionIDGen) does not provide an alternative method because there is no concept of 'saving or flushing' HttpSession in J2EE. This API is eliminated. The IAppLogic.createSession(int, int, String, String, ISessionIDGen) API provides an alternative API which takes zero parameters. Again, in J2EE, the Servlet API does not provide any control for the developer like the KFC API did; although the container vendor may provide value-added configuration or the HttpSession via deployment descriptor and app server configuration.

The single argument to the ITrans.commit method was never used by KIVA. We have eliminated this API for an Adapted API which takes zero arguments. You will need to remove the '0' value in the three commit methods in CreateCust.java Transfer.java and UpdateCust.java

21. In the OnlineBankSample application the 'session' APIs are used in BaseAppLogic.java, OBLogin.java, and OBLogout.java. The changes are shown below and are required to proceed.

BaseAppLogic.java LINE 38

ISession2 currentSession = getSession(); // getSession(0, appName, null);

BaseAppLogic.java LINE 44

currentSession = createSession(); //createSession(GXSESSION.GXSESSION_DISTRIB, 0, appName, null, null);

OBSession.java LINE 52

// result = m_logic.saveSession(null);

OBLogin.java LINE 123

int rc = GXE.SUCCESS; // saveSession(null);

OBLogout.java LINE 27

destroySession(); // destroySession(null);

There will usually be manual modifications needed on the HTML source or even the HTML Template source (now JSPs). The modifications will be different for every application. The iMT alleviates most of the manual work for systematic tasks. Customers may find repeatable patterns and leverage the Regular Expression mapping tool to help automate their efforts. In most cases, the maintenance on the markup is in the area of URL paths. Links to static content from the dynamics content may suffer from invalid absolute paths caused by the addition of the web application context.

22. edit both parallel versions of the ExitMessage.jsp. The absolute reference to static content from the dynamic content are broken because we have moved the static content into the WAR file. These references would be correct if the content was deployed outside of the WAR file. Notice the [..] characters added to the beginning of the absolute URL. Because the ExitMessage.jsp is rendered from the context of the [/cmd] servlet mapping within the servlet context, we can get back to the document root of the servlet context by just moving one segment up in the path.

/GXApp/OnlineBankSample/templates/en/ExitMessage.jsp

/GXApp/OnlineBankSample/templates/ja/ExitMessage.jsp

LINE 15 (html -> jsp links and path) (see snippet below for English version)

href="../GXApp/OnlineBankSample/en/OBLogin.html"> Back to Login Page </a><br>

23. Optional edit /WEB-INF/web.xml to allow for automatic startup when the root context is requested (see snippet below) You need to add welcome file elements between the servlet mappings and the taglib elements

</servlet-mapping>
<welcome-file-list>
<welcome-file>
GXApp/OnlineBankSample/index.html
</welcome-file>
</welcome-file-list>
<taglib>

A major effort required during manual migration will be to verify URLs within the application. Links between static and dynamic content will usually need to be updated for the relative paths required for portable J2EE deployment. Also, JavaScript may need to be revised.

The manual migration effort is completed and the final web application may be deployed on any J2EE web container. In FFJ you may export a WAR file and deploy on iAS 6.5. You may also run the web application directly in FFJ using the built-in TomCat server.

24. 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".

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