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, 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 Plugin, including executables and supporting files, are installed on the client machine. If not, JAM installs the Fire Engine into an installation directory. On Windows this directory is Xmarc/FirePluginn.n, where n.n is the major.minor sequence of the Fire version, e.g. Xmarc/FirePlugin7.0. This directory is created in a shared "Common Documents" directory, e.g. C:\Document and Settings\All Users\Documents (on Windows).
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.executeAsync() 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 Plugin package 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_i386_win32.zip.

Jam Parameters

Use the following applet parameters to customize JAM:

Parameter	Description
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.
FORCEINSTALL	By default Jam will only download and install a Fire Engine version if it is newer than that already installed. By setting FORCEINSTALL=1, JAM will download and install regardless.

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 CODEBASE.
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. Note: the executed Fire command must never make calls to the browser because the browser will be waiting for an answer before continuing. If this is attempted, Fire will Timeout without successfully contacting the browser.
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(Command.value);
     } //-->
     </SCRIPT>
     </HEAD>
     <BODY>
       <CENTER>
       <H2>Hello World</H2>
       <APPLET NAME="HW"
           ARCHIVE="jam.jar"
           CODEBASE="webfire"
           CODE="com/xmarc/jam/Jamlet.class"
           WIDTH=900 HEIGHT=560 MAYSCRIPT>
           <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="FIREVERSION" value="7.01.43">
       </APPLET>
       </CENTER>
       <P>
       <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>
       <P>Command(s) :
       <INPUT TYPE="text" SIZE="50" ID="Command">
       <INPUT TYPE="button" VALUE="Run" onClick="exec()"></P>
    </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 NAME="HW" ARCHIVE="jam.jar"
         CODEBASE="webfire"
         CODE="com/xmarc/jam/Jamlet.class" 
         WIDTH=900 HEIGHT=560 MAYSCRIPT>
    <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 CODEBASE. They are all supplied with the CD-ROM distribution in the <install_dir>/deploy/webfire directory.

File	Description
jam.jar	Signed JAR file containing JAM classes for Sun Java.
JamReg.dll	Support library used by Sun's Java Plugin to provide access to the Windows registry.
error_access_refused.html	Contains error messages when the user refuses to accept plugin installation.
error_classloader.html	Contains error messages after failing to install the Fire Engine because of Java class loader restrictions.
error_fire_installation_failed.html	Contains error messages for failing to install the Fire Engine.
error_jam_not_installed.html	Contains error messages after failing to properly install JAM Java classes.
error_no_fire_session.html	Contains error messages after failing to create a Fire session.
error_unsupported_browser.html	Contains error messages for unsupported browsers.
error_unsupported_machine.html	Contains error messages for unsupported machine architectures.
fire_i386_win32.zip	Fire Engine for Microsoft Windows.

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:

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 CODEBASE. They differ depending on the client machine architecture and browser.

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 Firefox 3 or later, equipped with the Sun Java plugin.

Microsoft Windows (with Sun Java plugin)

Jam looks for the existence of the directory Xmarc/FirePluginn.n/fire in the "Common Documents" directory. The location of "Common Documents" is derived from the registry entry HKEY_LOCAL_MACHINE/Software/Microsoft/Windows/CurrentVersion/Explorer/Shell Folders/Common Documents.

If the directory was not found, Jam downloads the plugin package and runs it.

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 a replacement plugin package is downloaded, installed and run.

Prev Chapter Next Chapter