Using the Loadable Applet Interface

Host Access Beans for Java

Appendix B. Custom Applications with Cache Support

Introduction

The Host On-Demand (HOD) server provides optional support for caching HOD-specific libraries on the client workstation. This mechanism operates for custom applications implementing one of these interfaces:

com.ibm.eNetwork.HOD.common.cached.LoadableAppletInterface com.ibm.eNetwork.HOD.common.cached.WSLoadableAppletInterface com.ibm.eNetwork.HOD.common.cached.LoadableJSAppletInterface

The interface that you choose will depend on the requirements of your custom applet/application. For a cached applet, use LoadableAppletInterface. For a Web Start application, use WSLoadableAppletInterface. And if you need to interact with the host sessions through Java Script, use LoadableJSAppletInterface.

Your application must extend a descendent of java.awt.Component, such as Panel or JPanel, to be visible.

You can develop custom applications of these types using the Host Access Class Library (HACL) and Host Access Beans for Java (HABJ). When served from the HOD server, the libraries for HACL and HABJ will be cached on the client workstation. This facility will not cache or version manage your non-HOD custom libraries. Each time the custom application is started, your custom libraries will be downloaded.

Your custom application libraries should reside in the HOD published directory. Do not combine them into any of the HOD libraries, because that is not permitted by your license agreement. Reconstituted Host On-Demand libraries will be rejected by the caching mechanism.

The caching mechanism does not require that your libraries be digitally signed with a Certificate Authority-derived certificate. That requirement will depend on whether your application code needs Security Manager intervention to invoke privileged execution.

The browsers supported are those that Host On-Demand supports.

Java1 vs Java2

LoadableAppletInterface and LoadableJSAppletInterface are supported in the "java1" and "java2" HOD modes. In the "java1" mode, you may use either loose classes or archived libraries. The "java2" mode requires a JAR archive.

WSLoadableAppletInterface, based on Java Web Start, is a Java 2-only technology. Your custom libraries must be in a JAR archive.

The "java1" mode uses the native jdk1.1 Java virtual machine of the browser. The "java2" mode requires installation and configuration of a Java2 Plug-in.

Version Differences Notice

The LoadableAppletInterface API was introduced into the Toolkit in HACP 3.0 in conjunction with HOD7.0. The procedure for setting up a custom LoadableAppletInterface application has been simplified. An application written and compiled with the HOD7.0 libraries should recompile and run under HOD8.0 without modification.

The Essentials of a `LoadableAppletInterface` Application

An modified HTML page created with Deployment Wizard can launch an application implementing the LoadableAppletInterface interface. First, the browser loads and launches a HOD-proprietary cached applet loader class. Then that class loads and launches your custom LoadableAppletInterface class.

The Deployment Wizard-based "front" HTML page contains the following line:

var hod_AppName='';

You customize it by filling in the name of your custom application that implements the LoadableAppletInterface interface:

var hod_AppName='my_custom_app_name';

During the Deployment Wizard process, you will specify an HTML parameter, "AdditionalArchives", that names the archive file(s) containing your custom code.

What the Browser Does and Does Not Know

The browser Java virtual machine (JVM) loads and launches the proprietary cached applet loader class. The browser is unaware that the loader class then has loaded and launched your custom class.

For this discussion, the cached applet loader instance is referred to as theRealApplet. It is the "real applet" because the browser loaded and launched it. The browser is only aware of theRealApplet.

Your custom application is a child of theRealApplet. The relationship is supported by four interface methods:

public void setApplet(Applet theRealApplet); public void init(); public void start(); public void stop();

Three of these methods, init(), start() and stop() have the same meaning as the analogous methods in java.awt.Applet.

The Method `setApplet(Applet theRealApplet)` Is Called First

When the cached applet loader loads and launches your custom application, the first method called is setApplet(Applet a). The cached applet loader passes in a reference to itself. The following is an example of custom application code:

... protected Applet theRealApplet = null; ... public void setApplet(Applet a) { this.theRealApplet = a; //remember who my parent, an applet, is }

The following is a typical example of your application's start() method, which is called by the cached applet loader:

public void start() { ... //do some preparation and then... if(this.theRealApplet != null ) { displayThis(<a GUI component that does the real work>); } }



    // show the work component in the browser page to the user

    public void displayThis(Component component) {

       this.theRealApplet.removeAll(); 
// just to be safe

       this.theRealApplet.add(component,null); 
// insert thenew GUI component

   

       //ask my parent for the top level
non-Window Component

       Component topComponent =
getTopComponent(this.theRealApplet);

       //visualize me reliably in the browser page

       topComponent.setVisible(true);

       topComponent.validate();

       topComponent.repaint();

    }

// climb the hierarchy as needed public Component getTopComponent( Component containingThisComponent ) { Component topComponent = containingThisComponent; Component nextComponent = topComponent.getParent(); while( (nextComponent != null) && !(nextComponent instanceof Window) ) { topComponent = nextComponent; nextComponent = topComponent.getParent(); } return topComponent; }

The RealApplet Is the Displayer

The repaint code above is needed to display your custom GUI component. Without it, your custom GUI component may not be visible in the browser page! That implies the requirement that to be visible, your application must extend a descendent of java.awt.Component, such as Panel or JPanel. Notice that there is no requirement that your LoadableAppletInterface application be the visible GUI component. For example, your custom application may be a server that marshals successive GUI components for display in the browser page, only to be removed and replaced by others. Remember to trigger the display of each GUI component after its insertion into "the real applet".

Using the Deployment Wizard

The HOD Deployment Wizard (DW) is an integral part of this process. The terse instructions that follow assume that you have familiarized yourself with the Deployment Wizard. Please first read the documentation and practice using Deployment Wizard to configure customized client HTML pages.

The next items describe only the additional actions needed in the Deployment Wizard process to create a custom HTML file.

On the Configuration Model panel, choose the HTML-based model.
On the Host Sessions panel, create a new session of any type. This step activates the "Next" button.
On the Additional Options panel: Choose Java1, Java2 or Auto Detect, according to the target mode needed.
Choose Cached Client. (A debug mode is available under Cache/Web Start Options.)
Click "Advanced Options" to access "Add html parameters." Set the parameter Name to "AdditionalArchives", and the Value to the name of your custom application archive. Use only the "stem" part of the archive name: DW will fill in ".jar" and ".cab" as needed. Click the "Set" button. Click "OK" to exit back to the Additional Options panel.

The Deployment Wizard creates a primary "front" HTML file (and one or more support HTML files) using the name you chose.

This example assumes that you have written a custom application named: lai0.JavaApp, where lai0 is the package name.

In resulting HTML file look for this line:
var hod_AppName ='';
and change it to :
var hod_AppName ='lai0.JavaApp';

Running the Custom Applet With Caching the First Time

The first time the client browser accesses the HOD server, the caching mechanism will detect that this is "the first time". Therefore the caching operator will download all of the HOD-specific libraries enumerated in the Deployment Wizard step. If this is "java1" mode, a popup dialog will instruct you to close and then relaunch the browser. If this is "java2" mode, the custom application will start immediately. Thereafter any latency in starting the custom application session is due to the need to re-download the non-HOD libraries. The HOD libraries will be downloaded again only if there has been a version upgrade installed on the HOD server.

The Essentials of a `WSLoadableAppletInterface` Application

The code for your hypothetical Web Start application would be identical to the above caching application except that the interface name changes: LoadableAppletInterface becomes WSLoadableAppletInterface. Nothing else changes.

Using the Deployment Wizard

The deployment is a little different in two respects: 1) the specifics of the Deployment Wizard configuration and 2) the file in which you specify the name of the custom application.

The next items describe only the additional actions needed in the Deployment Wizard process to create a custom HTML file.

On the Configuration Model panel, choose the HTML-based model.
On the Host Sessions panel, create a new session of any type. This step activates the "Next" button.
On the Additional Options panel:
Choose Java2.
Choose Web Start Client.
That triggers a "Web Start Setting" dialog. Setting the Code Base value is mandatory. It would be similar to this:
http://<hod server IP address>/HOD/
Click "OK" exit back to the Additional Options panel.
Click "Advanced Options" to access "Add html parameters." Set the parameter Name to "AdditionalArchives", and the Value to the name of your custom application archive. Use only the "stem" part of the archive name: DW will fill in ".jar" as needed. Click the Set button and then "OK" exit back to the Additional Options panel.

The Deployment Wizard creates a primary "front" HTML file and a specialized supporting "jnlp" file using the name you composed. You now specify your custom application by modifying the "jnlp" file. Change this:
<property name="hod.CachedClientSupportedApplet" value="com.ibm.eNetwork.HOD.HostOnDemand"/> to this:
<property name="hod.CachedClientSupportedApplet" value="wslai0.WSJava2App"/> activates the "Next" button.

In this case the package name is "wslai0", and the custom class to be launched is "WSJava2App".

The client browser addresses the designated HTML and the standard Web Start establishment process is followed. Because your custom library must be downloaded each time the application is started from the desktop via the Web Start launch icon, the HOD published directory must be available via its HTTP server.

The Essentials of a `LoadableJSAppletInterface` Application

The steps for LoadableJSAppletInterface are:

create a custom application-launching HTML using Deployment Wizard, being sure to enable the Session Manager API
write a controlling HTML with your JavaScript logic for accessing the custom application in the other HTML
create a "front" HTML specifying a FRAMESET relationship between the custom HTML and the controlling HTML

Although this Interface does not extend LoadableAppletInterface formally, in practice these methods serve the same purpose:

    public void setApplet(Applet theRealApplet);
    public void init();
    public void start();
    public void stop();

Using the Deployment Wizard

Therefore the custom application programming details described for a LoadableAppletInterface application all apply here.

The next items describe only the additional actions needed in the Deployment Wizard process to create a custom HTML file.

On the Configuration Model panel, choose the HTML-based model.
On the Host Sessions panel, create a new session of any type. This step activates the "Next" button.
On the Additional Options panel:

Choose Java1, Java2 or Auto Detect, according to the target mode needed.
Choose Cached Client. (A debug mode is available under Cache/Web Start Options.)
Click "Advanced Options" to access "Add html parameters". Set the parameter Name to "AdditionalArchives", and the Value to the name of your custom application archive. Use only the "stem" part of the archive name: DW will fill in ".jar" and ".cab" as needed. Click the Set button.
On this same menu tree, click on "Other" to expand the subtree. Highlight "Session Manager API" and then check the box to enable the Session Manager API. This is the configuration step which specifically arranges JavaScript access. Click "OK" to exit back to the Additional Options panel.

The Deployment Wizard creates a primary "front" HTML file (and one or more support HTML files) using the name you chose. This example assumes that you have written a custom application is named: jslai0.JSJavaApp, where jslai0 is the package name.

In resulting HTML file look for this line:
var hod_AppName ='com.ibm.eNetwork.HOD.JSHostOnDemand';
Change it to:
var hod_AppName ='jslai0.JSJavaApp';
The JavaScript-accessible version of Host On-Demand is being removed and you are substituting your JavaScript-accessible custom applet.

Using `callCustomerFunction(...)`

The LoadableJSAppletInterface specifies the entire Session Manager API plus one more method:


public java.lang.String callCustomerFunction(
java.lang.String fncName, java.lang.String parms) 

Method which can be used to extend the API to provide additional functionality.
A function name can be passed in (e.g., "showColorRemap") and then a
list of parameters that can be parsed by the receiving function. Customers can
use this API to implement their own custom   Java Script API calls.

Your custom application will implement whatever classes and methods that are needed for its functionality. In the case of a Terminal bean-based application, many of the Session Manager APIs might be easily mapped to manipulating your Terminal-based functionality.

However, the callCustomerFunction(java.lang.String fncName, java.lang.String parms) method might be the only JavaScript access you need so that the FRAMESET JavaScript widgets can interact with your cached custom application.

Using the `FRAMESET` Tag

The FRAMESET HTML file might look something like this:


   <HTML>
   <HEAD>
   </HEAD>
   <FRAMESET rows="85%,15%">
      <FRAME src="JSCustomApplication.html" name="upperFrame">
      <FRAME src="JavaScriptLogic.html" name="lowerFrame">
   </FRAMESET>
   </HTML>

And JavaScriptLogic.html should contains a JavaScript function similar to this:


   function getJsCustomApplication() {
      return parent.upperFrame.getHODFrame();
   }

The Deployment Wizard-generated HTML, JSCustomApplication.html, already contains this JavaScript function in "java1" mode:


   function getHODFrame() {
      return self;
   }

Or this JavaScript function in "java2" mode:


   function getHODFrame() {
      return HODFrame;
   }

JavaScript widgets and interaction logic will reside in one FRAME (HTML). They will use that global reference (above) to the other FRAME (HTML) that is running your custom LoadableJSAppletInterface application. LoadableJSAppletInterface-specific JavaScript calls will be received by your custom application and a value will be returned to the JavaScript caller.

Compatibility of the Java 1 and Java 2 Versions

Remember that JDK 1.1-based custom classes run compatibly in a Java 2 environment. Likewise, JDK 1.1-based HOD classes will run compatibly in a Java 2 environment. However, the reverse is not true: Java 2-based HOD classes will fail when run in a JDK 1.1 browser environment.

[ Top of Page | Previous Page | Next Page | Table of Contents ]