Monday, April 18, 2011

Converting your Legacy JAM Application into a Panther Web Application

Converting a legacy JAM/Panther 2-tier application into a Panther Web Application offers a significant advantage: a conversion allows reusing a significant portion of the existing code as most JPL and C functions continue to be fully functional.

Although straightforward, the conversion process is not trivial or automatic. The conversion process does present some challenges and involves making changes and additions to the existing code.

In this document, I start by quickly describing some key differences between a JAM/Panther 2-tier application running on a GUI environment and a Panther application running on the web. Then, I proceed to discuss aspects of the application that are reviewed during the process of converting a GUI application to the web.

Key differences between a GUI application and a Web application
In a GUI environment, when a JAM/Panther application is executed, it runs on a dedicated process that performs several tasks for the application: this one process makes the calls required to display the screens and widgets to the user, handles the screen event cycle and maintains the application state. In this same process, all the screens and JPL code are loaded and executed. This process, also, connects to the backend, which is typically a database that is accessed through the Panther DBi.

When an application is executed on the web, the architecture is quite different. For starters, instead of having one process perform virtually all the tasks required for the application to work, several processes (residing in different hosts) are involved in performing the tasks required for an application to run on the web.

On the web, the browser is the only program running on the client computer. It allows the user to interact with the web pages dynamically generated on the server. Once a given page is displayed to the user, there is no interaction with the server until the user performs an action that results in submitting a request to the server. More specifically, as the user interacts with a page in the browser, several events are generated and they can be divided into two groups: events that are handled locally by the browser alone (for example, when the user tabs between the fields in the page) and events that require server processing (for example, when the user clicks on a push button to perform a search in the database).

When an event in this second group occurs, the browser submits a request to the HTTP server. The request is then passed along to an available Panther Web Application process, which executes the appropriate Panther code and replies with a new rendition of the screen in the form of a new HTML page. This HTML code is then transmitted back to the browser and displayed to the user.

This is perhaps the root cause of most of the changes required for converting an application to the web: whereas in a GUI environment, a single process continually handles the screen event cycle, executes the appropriate Panther code and displays the application screens using the platform’s native API. On the web, these operations are split between the browser (which renders the HTML code it receives and maintains its own event cycle as the user interacts with it) and the Panther Web Application processes residing on the server (which receive requests from the clients, execute the appropriate Panther code, and reply with HTML code that is sent back to the browser).

The Panther Web Application processes that actually execute the Panther code are a pool of processes called Jservers. Each of these Jserver processes handles one request at a time, and generates a response. Being stateless processes, the Jservers retain no memory of previous transmissions: as soon as a Jserver process has produced the reply for a request, it again becomes available to process more requests, which may come from the same user session or, in most cases, from an altogether different user session. Using stateless processes is a common practice for web applications because they allow excellent scalability: a small number of stateless processes can handle requests coming from a large number of users.

Maintaining the Application state
So, if the Jservers are stateless processes: how is the application state maintained for each user session on the web? The short answer is: by caching data.

Panther Web automatically caches application state data, such as the values of hidden widgets, scroll state of widgets, and bundles.

Two modes of caching data are supported: embedding the cached data in the generated HTML code, or keeping the cached data on the server and embedding just a reference to the cached data in the generated HTML code.

Panther Web also provides functions to define and use context global variables from JPL code. Such variables are set by a specific user session and remain private to that user session.

Functions to store and retrieve data in HTTP cookies are also provided.

HTML Generation
As described previously, the application screens are dynamically rendered as HTML code to be presented on the browser. Panther automatically generates the HTML code for the screens and the widgets in them.

The HTML generated by Panther may need to be customized, mainly for 2 reasons: to fine-tune the visual appearance of the screen on the web and to integrate JavaScript code.

Using the Panther editor, the name of a pre-existing HTML document can be specified in the HTML-template property of a screen thereby providing the structure of the HTML generated for the screen. This allows you the flexibility to determine how the HTML for the screen is generated. The provided HTML template is tied to the Panther backend by embedding Panther-provided tags into it, thus specifying the exact location where the HTML code for the dynamic elements are to be included in the resulting HTML page.

Custom HTML properties can also be set for the individual widgets on a screen. These properties allow making additions or changes to the HTML attributes within the INPUT element that Panther generates for a widget.

These properties can also be used to hook in JavaScript functions and JavaScript libraries such as Dojo and jQuery.

To give you an example of the kind of things that can be done by customizing the HTML generation, see the screen shot of an application screen in the Panther editor.

By including the code shown below in the screen JPL, the attribute property of the Single Line Text widget called “i_odate” is modified before Panther generates the HTML for the screen:

When the screen is displayed in the browser, see how the widget is no longer displayed just as an input field, but as a Dojox calendar widget.

GUI applications typically have menu bars that allow the user to navigate between screens. On the web, there is no natural replacement for menu bars and many alternatives are available for providing navigation controls on the web. During the conversion, it is necessary to select the one that better suits your needs.

Web Event Handling
You can provide JPL procedures with the names listed below, and those procedures get executed as events occur in a web application:
web_startup – This procedure is called when a Jserver process is started. The code to open the connection to the database is typically invoked from this JPL function and the database connection is maintained through the whole life of the Jserver process. This procedure can also be used to load public procedures and data used through the application, specify database error handlers, and define global variables.
web_enter – Each screen can have its own implementation of this procedure. It gets called after the screen entry event and before the web browser data is loaded into the Panther screen structure. This is only called once on each request submitted.
web_exit – Each screen can also have its own implementation of this procedure. This is invoked after all other events have been processed and immediately before Panther dynamically generates the HTML output for the request being processed.
web_shutdown – This procedure is invoked when the Jserver process is shutting down. This is where any required application clean up is typically invoked, including the code to close database connections.

Several approaches need to be evaluated when facing the prospect of making an existing Panther GUI application available on the Internet or an intranet.
This document has provided you with a glimpse of the differences between the two environments and has presented aspects of the application that need to be addressed during a conversion. Hopefully this information has piqued your interest about converting GUI applications to the web in general and the Panther Web product in particular.

Eduardo Ramos is a Project Manager at Prolifics. He has over 16 years of experience in the IT field, specializing in the development and migration of multi-tier applications using various technologies including Panther and the IBM WebSphere family of products.