Developing and deploying HATS Web applications

There are five types of HATS applications; Web, portlet, EJB, rich client, and administrative console. This chapter includes information about HATS Web applications. For information about the other types of applications, see the following chapters:

In addition, a HATS Web application can be linked with a WebFacing application and both packaged together to interoperate with each other in a single enterprise application. For more information, see WebFacing and HATS.

HATS applications are created from HATS projects using the HATS Toolkit. When you create a new HATS project, a set of folders is created to help you organize your HATS application files. An example of a default project is shown below. The highest level folder has the same name as the name you give to your project when you create it. In that folder are other high-level folders that contain objects defined in your HATS project. Some folders do not appear until you create certain objects.

Figure 2. HATS Web project view
HATS Web project view

Depending on how you set up your HATS project, some or all of these folders appear in the HATS Projects view. You can also specify which folders appear in your HATS Projects view as well as hide file extensions. For more information, see Using HATS preferences.

Note:
Different folders appear for different types of HATS projects. For example, the directory tree for a HATS EJB project has no Screen Customizations, Screen Captures or Web Content folders.

You can create subfolders within these high-level folders to help organize your project. For instance, as you create screen captures for your project, you might want to create folders under the Screen Captures folder to organize and group the captured screens. To create a folder, right-click on one of the high-level folders in the tree and click New HATS > Folder. To move a file into a different folder, right-click on the file and select Move, or you can use the drag-and-drop method.

Note:
There is a limitation for subfolders. The transformation and the template files must be in subfolders of the same level. In order to use a transformation that resides at a certain level of subfolders, such as \transformations\Callup\, then the template that will be coupled with this transformation must be at the same level of subfolders, like \templates\Callup\.

HATS projects can be shared in a team environment by going to the Navigator View of your HATS perspective. Right-click the project and select Team > Share Project. Select the repository type from the list and click Next. Rational® SDP supports several repositories. For more information, refer to the Rational SDP documentation and search on repository.

HATS Web projects, created in HATS Toolkit, are extensions of Web projects in the Rational SDP workbench. For more information, click Help > Help contents from the Rational SDP menu bar, expand Developing, and select Developing Web applications.

Organizing HATS Web applications

By default, all HATS Web applications are stored in one enterprise archive file, such as HATS_EAR7. When you export your applications and deploy them on WebSphere® Application Server, the HATS .ear file contains a Web archive (.war) file with the resources to run each application, as well as one copy of the HATS runtime executable code. If you prefer, you can organize your applications differently, either each in its own .ear file, or in some other combination.

Consider the effect of the following on your server when deciding how to arrange your Web applications:

Disk space
If you create each application in its own .ear file, it has its own copy of the HATS runtime code. The runtime code is approximately 25 MB; multiply that by the number of applications you have to see how much disk space is consumed on your runtime system for all of your applications.
Deployment
If you redeploy a HATS .ear file, you are redeploying all the applications in that .ear file, even if some of the applications are unchanged.
Logging and tracing

Logging and tracing are controlled at the level of the .ear file, not at the individual HATS application level. If each HATS application is in its own .ear file, you can control its log and trace settings independently of any other applications. If you have several HATS applications in one .ear file, log and trace settings apply to all HATS applications in the .ear file. Messages for all HATS applications in the .ear file are inserted into the same log file, and trace information for all HATS applications is inserted into the same trace file.

You can add an additional optional keyword, traceLogDirectory, to the runtime.properties file. This enables you to specify a particular directory for the output files. The file is located in the was_dir/installedApps/ear_name directory for a HATS enterprise application.

License tracking
License tracking is also controlled at the level of the .ear file, not at the individual HATS application level. If each HATS application is in its own .ear file, license tracking is done independently of other applications. If you have several HATS applications in one .ear file, license tracking is performed for all HATS applications in the .ear file. Information about license usage is kept for all HATS applications in the .ear file, and is inserted into the same license usage file.

Moving HATS Web projects to a different .ear file

Which .ear file your project files go into is determined when you create the project. After you create the project, you can move it from one .ear to another, using the following steps:

To add the project to an .ear file:

  1. Click the Navigator tab of the HATS Toolkit to display the .ear files.
  2. Expand the .ear file to which you want to add the project. Expand the META-INF folder and locate the application.xml file.
  3. Start the Rational SDP application.xml editor by double-clicking the application.xml file.
  4. In the application.xml editor Design view, in the Overview group, select Application, and click Add.
  5. In the Add Item dialog, select Module and click OK.
  6. Select the project you want to add to the .ear file and click Finish.
  7. Close the Rational SDP application.xml editor.

To remove the project from an .ear file:

  1. Click the Navigator tab of the HATS Toolkit to display the .ear files.
  2. Expand the .ear file from which you want to remove the project. Expand the META-INF folder and locate the application.xml file.
  3. Start the Rational SDP application.xml editor by double-clicking the application.xml file.
  4. In the application.xml editor Design view, in the Overview group, select the project you want to remove from the .ear file, and click Remove.
  5. Close the Rational SDP application.xml editor.

Backing up your HATS projects

As with any software development activity, it is good practice to back up your HATS projects to ensure against data loss or corruption. In addition to creating backups during your own development cycle, you should also create backups prior to installing HATS maintenance. This allows you to revert to the previously installed maintenance level if necessary. To create a backup for your HATS project, use the Rational SDP export project interchange function. For more information, see Exporting a Web project.

To restore a HATS project from a backup, use the import project interchange function. For more information, see Importing a Web project.

Exporting and importing HATS Web projects

Exporting a Web project

You can export your HATS Web projects to save and use as backups or to move to another HATS Toolkit system. To perform the export, use the following method:

Project interchange file

This function has multiple benefits. It allows you to export multiple projects and the associated .ear all at once. In addition, you do not have to create a project on the destination HATS Toolkit before you import the project interchange file. To export the project as a project interchange file perform the following steps:

  1. From the menu bar select File > Export to open the Export wizard.
  2. Select Other > Project Interchange and click Next.
  3. Select both the project and its associated EAR project.
  4. Specify a .zip file name and location for the .zip file in which to save the project.
  5. Click Finish.

Importing a Web project

To import a project in a project interchange file into HATS Toolkit:

  1. From the menu bar click File > Import to open the Import wizard.
  2. Select Other > Project Interchange and click Next.
  3. Specify the .zip file you want to import in the From zip file field.
  4. Specify the workspace into which you want to import the file in the Project location root field.
  5. Select the projects in the Project Interchange file that you want to import into the specified workspace.
  6. Click Finish.

For information about how to migrate a HATS project from a previous release of HATS, see HATS migration.

Deploying HATS Web applications

The terms HATS Web application, WebSphere application, and Java™ EE application can be used interchangeably to refer to a Web application created from a HATS project. It is a HATS Web application because it was developed in the HATS Toolkit. It is a WebSphere application because it will be installed and run on WebSphere Application Server. It is a Java EE application because it conforms to the Java EE standards.

To deploy your HATS Web application in a runtime environment you must:

The following sections describe how to perform each of these tasks.

Enabling the HATS runtime

Regardless of where you obtain the HATS package (HATS CD, Web, or packaged with another product), you install the same version of the HATS Toolkit. This is a limited-use version that you can use to evaluate HATS. To fully enable the runtimes for production in accordance with your licensed proof of entitlement, you must specify your license settings using the License Settings wizard included in the HATS Toolkit. For more information see the sections, Evaluating HATS and Enabling HATS runtime and license settings, in HATS Getting Started.

Exporting your project as a Java EE application

To deploy your HATS Web application to a WebSphere Application Server runtime environment, you must first package it into a Java EE application. To do this, you export your project as an EAR file.

To export the project, follow these steps:

  1. Highlight (single-click) the name of your project in the HATS Projects view.
  2. Click the Export HATS Project icon on the main tool bar, or right-click the project name and select Export Project.
  3. In the Export window, choose an Enterprise Application project from the drop-down list or type the name of an Enterprise Application project in the EAR project field.
  4. Enter a destination location in the Destination field or click the Browse button to select the destination of the exported .ear file.
  5. If you want to export the project's source files along with the executable files, select the Export source files box. If you include the source files, another developer can extract them from your .ear file. This can make collaboration or service easier, but you must decide whether it creates a security risk.
  6. If you have exported this project to this location before, the export process asks whether you want to overwrite the existing files. This is intended to protect you from overwriting files that you might want to keep, perhaps to archive a previous version of your project. If you want to overwrite previous files without being asked for confirmation, select the Overwrite existing file box.
  7. Click Finish. The project is exported as a Java EE application, represented by an Enterprise Archive file with extension .ear, with the directory and file name you specified.

Installing your application in a runtime environment

After exporting the HATS project as a Java EE application and transferring the application's .ear file to the production system, install it by launching the WebSphere administrative console and browse to the location of the .ear file. For more information about installing applications on WebSphere Application Server refer to the WebSphere Application Server library at http://www.ibm.com/software/webservers/appserv/was/library/ and select the link to the information center for your version of WebSphere Application Server. In the contents under your WebSphere Application Server product, refer to the chapter about deploying applications.

After the application has been installed, test it by bringing up the URL in a Web browser on another system. Then you can publish the URL to your users. As an example, the URL might look like http://hostname/hatsappname/ where hostname is the IP host name and domain where WebSphere Application Server is installed and hatsappname is the name of your HATS application.

Notes:
  1. For more information about installing HATS applications on specific platforms, see the HATS Information Center at http://publib.boulder.ibm.com/infocenter/hatshelp/v75/index.jsp.
  2. If your HATS applications are deployed on WebSphere Application Server with Java 2 security enabled, and they do not start, see Java 2 security for more information.
  3. HATS supports multiple browser instances from the same workstation accessing the same HATS application. However, these multiple browser instances must not share the same HTTP session id.

    The session between the browser accessing the HATS application and the WebSphere Application Server is assigned an HTTP session ID. The HTTP session ID enables subsequent requests from the same browser to return to the same HATS application. Subsequent requests use the same Telnet (3270 or 5250) session that exists between the HATS application on the server and the host.

    Different browsers implement the HTTP session ID differently. Microsoft® Internet Explorer expects all browser sessions in the same process to share the same HTTP session ID. When you launch a new browser window using the same shortcut, a new browser session starts and shares the same process and the same HTTP session ID.

    One way to open a new Internet Explorer process with a unique HTTP session ID, in Windows® XP for example, if Internet Explorer is in your start list, is to select Start > Internet Explorer. Selecting Start > All Programs > Internet Explorer also starts a new Internet Explorer process with a unique HTTP session ID.

    Notes:
    1. The Ctrl-N function of Internet Explorer does not start a new process, because it opens a new window that has the same process ID and the same HTTP session ID as the window from which it originated.
    2. For Internet Explorer 8, you can use File > New Session to open a new browser with a unique session ID.
    Note:

    In Internet Explorer, you can find the HTTP session ID for a browser window by selecting View > Source from the menu bar, or right-clicking in the Internet Explorer browser window and selecting View Source to view the source tagging for the page. Scroll down to the HATS Form tag in the source window, which is similar to the following:

    <FORM NAME="HATSform" dir="" METHOD="POST"
    ACTION="/YourHATSAppName/entry">.

    Within that Form tag, find the SESSIONID parameter, which is similar to the following:

    <INPUT TYPE="HIDDEN" NAME="SESSIONID"
    VALUE="PIOncS1GehNWxWo_49VCBzC" />
    Note:
    When you access a HATS application that only displays a default transformation of the screen and doesn't run macros when it starts, the SESSIONID has a value of "INVALID." The SESSIONID value is assigned when you send something to the host, such as pressing the Enter key, and you get a response.

    You can verify whether a new process is being started by using Task Manager in Windows. Start Task Manager, and click the 'Image Name' column heading on the Processes tab to sort the information by image name. Scroll down to see how many 'iexplore.exe' processes are in the list. Try starting some new Internet Explorer windows using the Start > Internet Explorer shortcut. If a new process is started, a new iexplore.exe process is added to the display. Otherwise, an existing process is in control of the new browser window.

  4. HATS requires the application's display-name, as defined in the application's web.xml file, to match the Web application's context path used in the browser URL. If the display-name value is changed to be different than the context path of the application, you might encounter a java.lang.nullPointerException error or a javax.servlet.ServletException error when running the HATS application. For example, a HATS project named MyHatsProject defaults to a display-name of MyHatsProject. This project, when deployed as a Web application, must be reached with a URL similar to http://myServer/MyHatsProject/ to operate properly. Changing the display-name to something other than MyHatsProject causes the application to be inoperable.

Changes necessary in the runtime environment

Configuring class loader policy

When you deploy your HATS Web applications, or when running the applications in the local test environment, the WAR class loader policy must be configured on a per Java EE application basis for either of the following situations:

HATS automatically configures the class loader policy for these applications.

Configuring HATS applications in a clustered environment

If you deploy HATS Web applications in a vertically clustered environment, each application server instance will create its own files for logging, tracing, and license tracking. This is accomplished by decorating the names of the output files with the fully qualified name of the application server instance. For example, the default pattern for the logging file is messages.txt, but the actual file name will be something like messages_myCell_myNode_myAppServerInstance_1.txt.

By default, all of the server instances read the same runtime.properties file for their settings. To properly control runtime settings you must configure each instance to have its own runtime properties file. This enables you to control tracing for each instance independently, and prevents runtime settings from changing spontaneously.

Follow these steps to configure each of your vertically clustered HATS application instances to have its own runtime.properties file:

  1. Make a copy of the runtime.properties file for each application server instance in the vertical cluster.
    1. Locate the runtime.properties file for your HATS application. This file should reside in the installedApps\app_name.ear directory under the directory where you installed WebSphere Application Server.
    2. For each instance, make a copy of the runtime.properties file, with a unique name, in the same directory. For example, you might name the files Clone1runtime.properties, Clone2runtime.properties, and so on. You can use any valid file name, but the name should help the administrator identify the application server instance with which this file is associated.
    3. At this point, for n server instances you have n unique runtime properties files.
    4. If you have more than one HATS .ear file in your vertically clustered environment, repeat this step in each .ear file directory.
  2. Add a new configuration setting to identify the runtime.properties file that is used by each instance. For example, for WebSphere Application Server V6.x:
    1. Select Application Servers in the Servers item in the left navigation pane of the WebSphere Application Server administrative console.
    2. Select the server instance from the list of application servers.
    3. Select Java and Process Management from the Configuration tab for the server.
    4. Select Process Definition > Java Virtual Machine > Custom Properties.
    5. In the Custom Properties window, click New.
    6. In the Name field, enter hats.runtime.properties.
    7. In the Value field, enter the name of the properties file that you created for this server, for example, Clone2runtime.properties. Do not specify directory names or slashes in this value.
    8. The Description field does not require a value.
    9. Click Apply.
    10. Repeat this procedure for each server instance.

After adding the new custom property and ensuring that each server instance has its own, uniquely named, copy of the runtime.properties file, you must restart each application to begin using the new files.

The HATS administrative console can be used to control the settings of the cluster members. Use the Getting Started folder in the Navigation panel of the Administration Web page to select the Management Scope. After you have chosen the cluster, choosing to view the Trace Settings will prompt you for the particular cluster member you want to control.

Note:
There are special considerations for the use of clustering and user lists. For more information, see Clustering and user lists

Developing HATS applications for mobile devices

You can develop HATS Web applications that can be accessed by mobile devices such as cellular phones, data collection terminals, and personal digital assistants (PDAs). The process is the same as developing any HATS Web application with some considerations due to the capabilities of the mobile device and its Web browser, for example screen size and interaction limitations.

To create a project for your application for mobile devices, launch the Create a Project wizard using one of the following actions:

In the Create a Project wizard, on the HATS Project panel:

  1. Enter a name for the mobile device project.
  2. Optionally, enter a description.
  3. Accept the default location.
  4. Select Web to indicate this is a Web project.
    Note:
    If the Web deployment option is disabled, this indicates that no server runtimes are defined. To define server runtimes, go to Window > Preferences > Server > Installed Runtimes and add at least one runtime definition.
  5. For the Target server field, select one of the supported WebSphere Application Servers.
  6. For the Enterprise application project field, enter the name of the EAR project to use for testing in the local test environment.
  7. Select Optimize options for mobile devices.
  8. Click Next and continue creating your project as normal.

Considerations and limitations for mobile devices

When you create a HATS project and select Optimize options for mobile devices, HATS initializes the project with options that work best for mobile devices. Some options, for example, printing, keyboard, asynchronous update, and other options, are not supported and therefore disabled. Keep in mind the following considerations and limitations as you develop your application for mobile devices.

In addition to options that HATS automatically disables, the following functions are not supported and should not be implemented in HATS applications for mobile devices: