Web Deployed Fire

Deploying your application in a Web browser allows Fire applications to be deployed across the Web. In a web-deployed scenario there are two components:

Java Application Manager (JAM) - An embedded, signed Xmarc Java applet,
packaged in a JAR file: jam.jar (for Netscape Navigator) or a CAB file,
jam.cab (for Internet Explorer), enabling Fire to run inside a browser.
Fire Engine

Java Application Manager

Functions of JAM include:

Creates a window inside the browser page with a specified width and height.
Checks if the Fire Engine, including executables and supporting files, is installed on the client machine. If not, JAM installs the Fire Engine into an installation directory. Default locations can be configured via the applet parameters: FIREHOME_WIN and FIREHOME_UNIX, although JAM has its own defaults and these applet parameters should typically be omitted.
Checks for the various browser vendor. For example, if the browser is Netscape and JAM is not installed, JAM will automatically be downloaded into Netscape’s download area. For older flavors of Netscape, the user may be asked to restart the browser.
Starts a Fire session if one is not yet started. Next, JAM passes application specific information, APPSESSION, APPVIEW, and APPSTART to the running Fire session. JAM also sends the applet specific display name and window handle so that Fire windows can be embedded in the browser.
Executes Fire commands using either Jamlet.execute() for synchronized execution or Jamlet.AsynExecute() for asynchronized execution.
Receives Fire browser commands sent by the Firebrowser object and evaluates them in the host browser.
If running Fire behind a firewall or proxy server, JAM automatically gathers proxy server information, including proxy server host name and port number from the current browser settings. JAM then passes this information on to the Fire session, which in turn uses this information to correctly download files and connect to the appropriate Fire database or EIM service.

Fire Engine

The Fire Engine contains Fire executables and support files. Among them is the Fire (WAM) Application Manager. The Fire (WAM) Application Manager is a Fire application that manages fire applications, automatically downloading and updating the application, if necessary. The Fire Engine is packaged in a zip file, fire_<arch_os>.zip, where <arch_os> is the platform dependent extension, for example, i386_win32 for windows, sun4_os7 for Sun Solaris, hp_ux11 for HP UX, etc.

Jam Parameters

Use the following applet parameters to customize JAM:

Parameter	Description
FIREBASE	Base URL where JAM (jam.jar) and Fire Engine (fire_<arch_os>.zip) are located. Typically this is a webfire directory somewhere in a web server hierarchy. If this omitted, Jam will derive a URL from the value of the applet CABBASE or ARCHIVE parameter, since the required files are in the same directory on the web-server as jam.cab and jam.jar.
FIREVERSION	Fire runtime version required to run the current application. JAM checks it against the installed Fire Engine version on the client. If it is greater than the installed one, the newer version is downloaded and installed by JAM.
FIREHOME_WIN	The well known directory for Windows where the Fire Engine is to be installed. During the install process the user is given the opportunity to change this. This can be omitted, because JAM has a default.
FIREHOME_UNX	The well known directory for Unix where the Fire Engine is installed. This can be omitted because JAM has a default.
JAMVERSION	JAM version (for Netscape only). JAM checks it against the installed JAM version. If it is greater than the installed one, the newer version is downloaded and installed by Netscape SmartUpdate. This version number must match the version number of the JAM SmartUpdate package, jam_su.jar. The current JAM version number, in the format: <major>.<minor>.<rev>.<build> (for example, jam.6.0.0.4), can be found on the CD-ROM in the deploy/webfire directory, or once Fire is installed, in <install_dir>/deploy/webfire.

The following applet parameters provide JAM with details of the Fire application:

Parameter	Description
APPSESSION	A name given to the Fire session in which the application will run. This should be a unique name for the deployment of the application. If required, multiple applets can share the same Fire session, enabling an application to have multiple browser-resident windows. In this case the multiple applets would share the same APPSESSION parameter, but would have different APPVIEW parameters.
APPVIEW	A name to identify the applet container window to Fire. This value is passed to the Fire application when something needs to be done on the window, e.g. creation, destruction, resizing. It is a parameter to the appview.cmd macro within the application.
APPSTART	The URL of the Fire application control file (.fsc or .xml). This in turn provides details of the application library (.fsa) which Fire should execute to run the application. The location of this file can be on a different web server from the one hosting FIREBASE.
HEIGHT WIDTH	Standard HTML applet parameters. They provide the dimensions of the applet window and are passed to the Fire application (appview.cmd) for it to size window contents appropriately. Some browsers enable applets to have variable (percentage) dimensions. In such cases, any change of applet size is passed to the Fire application (again appview.cmd) to enable the application to re-size the contents if necessary.

Jam Methods

JAM has the following public methods that can be called from a scripting language, such as JavaScript.

Method	Description
execute(command)	Sends the specified command to Fire and waits for a result string.
executeAsync(command)	Sends the specified command to Fire and returns immediately without waiting for any result.

Example index.html file

The following example shows JAM parameters being used to customize a site. Notice the use of the JAM methods used to implement some functions on buttons:

  <HTML>
     <HEAD>
     <TITLE>Hello World</TITLE>
     <SCRIPT LANGUAGE="JavaScript">
     <!--
     function newWindow()
     {
       document.HW.execute("wgraphic -emb='HelloWorld'");
     }
     function drawCircle()
     {
       document.HW.execute("circle -r=10;box;plan");
     }
     function killAll()
     {
       document.HW.execute("kill all");
     }
     function quit()
     {
       document.HW.executeAsync("end");
     }
     function exec()
     {
       document.HW.execute(document.MX.Command.value);
       return false;
     } //-->
     </SCRIPT>
     </HEAD>
     <BODY>
       <CENTER>
       <H2>Hello World</H2>
       <APPLET ARCHIVE="jam.jar" NAME="HW"
           CODE="com/xmarc/jam/Jamlet.class"
           WIDTH=900 HEIGHT=560 MAYSCRIPT>
           <PARAM name="CABBASE" value="jam.cab">
           <PARAM name="APPSESSION" value="xmarc_helloworld">
 	       <PARAM name="APPVIEW" value="HelloWorld">
           <PARAM name="APPSTART" value=
             "http://www.xmarc.com/fire/example/helloworld.fsc">
           <PARAM name="FIREBASE" value= "http://www.xmarc.com/webfire">
           <PARAM name="FIREVERSION" value="6.0.0">
           <PARAM name="JAMVERSION" value="6.0.0.4">
       </APPLET>
       </CENTER>
       <P>
       <FORM NAME="MX" onSubmit="return exec()">
          <INPUT TYPE="button" VALUE="Window" onClick="newWindow()">
          <INPUT TYPE="button" VALUE="Draw Circle" onClick="drawCircle()">
          <INPUT TYPE="button" VALUE="Kill" onClick="killAll()">
          <INPUT TYPE="button" VALUE="Quit" onClick="quit()">
          <P>
          Command(s) :
          <INPUT TYPE="text" SIZE="50" NAME="Command">
       </FORM>
    </BODY>
  </HTML>

Proxy Considerations

Fire applications deployed over the Web are also designed to run behind firewalls and proxy servers. To enable JAM to query proxy server information from a browser, JavaScript must be enabled by specifying the MAYSCRIPT attribute (only for Netscape) in the JAM applet tag. For example:

  ...
  <APPLET ARCHIVE="jam.jar" NAME="HW" CODE="com/xmarc/jam/Jamlet.class" 
         WIDTH=900 HEIGHT=560 MAYSCRIPT>
    <PARAM name="CABBASE" value="jam.cab">
    <PARAM name="APPSESSION" value="xmarc_helloworld">
  ...

JAM also automatically adds the following line to Netscape Navigator’s preferences. i.e. preferences.js for Unix and prefs.js for Windows:

user_pref("security.lower_java_network_security_by_trusting_proxies", true);

This enables JAM to download the Fire Engine through a proxy server.

Web Deployed Files

When deploying applications via a web browser, the files in the following table are used. They must be present on the web server, in the directory specified by FIREBASE. They are all supplied with the CD-ROM distribution in the <install_dir>/deploy/webfire directory.

File	Description
jam.cab	Signed CAB file containing JAM classes for Internet Explorer.
jam.jar	Signed JAR file containing JAM classes for Netscape Navigator.
jam_su.jar	Signed JAR file containing jam.jar, for Netscape SmartUpdate to install jam.jar into Netscape’s download area.
jam.<n>.<n>.<n>.<n>	A JAM version number (for example, jam.6.0.0.4) checked by Netscape's SmartUpdate system.
error_unsupported_browser.html	Contains error messages for unsupported browsers.
error_fire_installation_failed.html	Contains error messages for failing to install the Fire Engine.
error_jam_not_installed.html	Contains error messages for failing to properly install JAM Java classes.
error_no_fire_session.html	Contains error messages for failing to create a Fire session.
fire_i386_linux.zip	Fire Engine for Linux i386.
fire_i386_win32.zip	Fire Engine for Microsoft Windows.
fire_sun4_os8.zip	Fire Engine for Sun Solaris.
jamregjri.dll	Support library used by Netscape's Native JVM to provide access to the Windows registry.
jamregjni.dll	Support library used by Sun's Java Plugin to provide access to the Windows registry.

Common Jam Configuration Problems

JAM is configured using a set of applet parameters as previously described. This section describes common problems in configuring those parameters:

Dangling FIREBASE: FIREBASE should point to the location where the Fire Engine zip files and error message files are resident, waiting to be downloaded by a client. A dangling FIREBASE will cause the Fire installation to fail.
Missing or outdated JAMVERSION: :JAMVERSION should reflect the latest JAM version number. A missing or wrong JAMVERSION value will prevent the latest jam.jar from being downloaded and installed. This applies only to Netscape.
Missing Applet Attribute MAYSCRIPT: The applet attribute MAYSCRIPT (only for Netscape) allows JAM to collect proxy server information and pass it to the Fire session. A missing MAYSCRIPT attribute will prevent JAM from collecting the necessary information, and prevent Fire from downloading any files and making socket connections, if a proxy server is used on a client machine.

Downloading Rules

The Jam applet goes through the following procedures when deciding whether the Fire plugin zip needs to be downloaded from FIREBASE. They differ depending on the client machine architecture and browser.

On Microsoft Windows, the registry is used with entries relative to the HKEY_LOCAL_MACHINE/Software/Xmarc key if the user has administrative privileges, or relative to HKEY_CURRENT_USER/Software/Xmarc key otherwise.

When a download is made over an existing installation, files in the web_config directory are not overwritten. This is because users may want to tailor the default behavior of the plugin.

Although we have attempted to cater for most flavors of Internet Explorer and Netscape, best results are achieved with Internet Explore 6, and Netscape 6 or later, equipped with the Sun Java plugin.

Microsoft Windows (Internet Explorer and Netscape with Sun Java plugin)

Jam looks for the registry entries Fire6/PluginRoot and Fire6/PluginVersion.
If it finds both, then Fire is already installed on the system and Jam then compares the value of Fire6/PluginVersion to the "required" version (specified by FIREVERSION).
If the installed version of Fire (Fire6/PluginVersion) is later than the required version, then Jam runs the installed version, otherwise it downloads the required version from the server, installs it into the path specified by Fire6/PluginRoot, and runs it updating the registry value of Fire6/PluginVersion accordingly. The download procedure is now complete.

Jam looks for the registry entries Fire6/Root and Fire6/Version. These are set when installing full Enterprise Spatial systems.
If it finds both, then Fire is already installed on the system and Jam then compares the value of Fire6/Version to the "required" version (specified by FIREVERSION).
If the installed version of Fire (Fire6/Version) is later than the required version, then Jam runs the installed version, otherwise it downloads the required version from the server, installs it into the path specified by Fire6/Root, and runs it updating the value of Fire6/PluginVersion in the registry accordingly. Note the Fire plugin is only a subset of a full Enterprise Spatial installation, so such a download will onyl update the components necessary to run the Fire plugin. The download procedure is now complete.

If the above steps were not executed, due to missing Fire6/PluginVersion and/or Fire6/Version registry entires, Jam continues to establish a destination for the Fire plugin download.

If Fire6/PluginRoot is defined, then an attempt is made to download into this folder (whether or not the folder exists).

If Fire6/Root is defined, the following prompt is displayed, with the value of Fire/Root as the default destination:

You have a full but out-of-date Fire installation.
The latest Fire plugin will be downloaded there.
If you wish the plugin to reside elsewhere, change the destination.

Otherwise the following prompt is displayed, with the default destination set to the value of FIREHOME_WIN from the html page, or c:/Xmarc/es6/fire if not present:

The latest Fire plugin will be downloaded and installed.
Please indicate a destination directory.

The destination of the download may be changed in the prompt. Once the prompt has been accepted, Jam will download the latest Fire plugin and run it, updating the registry values of Fire6/PluginRoot and Fire6/PluginVersion accordingly.

Microsoft Windows (Netscape with native Java)

With this combination of machine architecture and browser (pre Netscape 6), Jam does not have direct access to the registry, so it must make some intuitive guesses relating to any Fire installation already present.

Jam looks for the existence of the FIREHOME_WIN directory, or c:/Xmarc/es6/fire if FIREHOME_WIN was not supplied.

If the directory was found, Jam looks for a file version within it. If found, the contents of this file are compared to the "required" version (specified by FIREVERSION). If the installed version of Fire (the contents of version) is later than the required version, then Jam runs the installed version, otherwise the following prompt is displayed, with the default destination set to the value of FIREHOME_WIN:

You have an out-of-date Fire installation.
The latest Fire plugin will be downloaded there.
If you wish the plugin to reside elsewhere, change the destination.

If neither FIREHOME_WIN nor version can be found, you are presented with the following prompt:

No Fire installation has been detected on your machine.
The latest Fire plugin will be downloaded and installed.
Please indicate a destination directory (with write permission), or
if you already have a Fire installation, give its location.

The destination of the download may be changed in the prompt. Once the prompt has been accepted, Jam will download the latest Fire plugin and run it. Although Jam does not have access to the windows registry, Fire does, so the registry values of Fire6/PluginRoot and Fire6/PluginVersion are updated appropriately during Fire start-up.

Unix (Netscape)

With this combination of machine architecture and browser, there are no registry facilities, so Jam must make some intuitive guesses relating to any Fire installation already present.

Jam looks for the existence of the FIREHOME_UNX directory, or /opt/Xmarc/es6/fire if FIREHOME_UNX was not supplied.

You have an out-of-date Fire installation.
The latest Fire plugin will be downloaded there.
If you wish the plugin to reside elsewhere, change the destination.

If neither FIREHOME_UNX nor version can be found, you are presented with the following prompt:

No Fire installation has been detected on your machine.
The latest Fire plugin will be downloaded and installed.
Please indicate a destination directory (with write permission), or
if you already have a Fire installation, give its location.

The destination of the download may be changed in the prompt. Once the prompt has been accepted, Jam will download the latest Fire plugin and run it.

There is currently a problem with Linux, where some attempts to run a second Fire applet within the same Netscape session hangs Netscape. This is a known problem with multiple calls to the getRuntime().exec method in the Linux/Java 1.3.1 JVM. Hopefully, later JVM versions will not have the problem. The only workaround is to stop Netscape and restart it. Yeah - we know.

Prev Chapter Next Chapter