                  Golden Code (R) Run Time Environment (RTE)
                      and Software Development Kit (SDK)
            for the Java (TM) 2 Platform Standard Edition 1.4.1_07
                             OJI PLUGIN README

                               June 24, 2004

-----------------------------------------------------------------------------

Contents

   1.  Introduction
   2.  Product Description
   3.  Hardware/Software Requirements
   4.  Performance considerations
   5.  Installation/Configuration
   6.  Known Problems
   7.  Limitations
   8.  Submitting Problem Reports
   9.  Contacting Golden Code
   10. Trademarks

-----------------------------------------------------------------------------

1. Introduction

This document describes the OJI Plugin for the Golden Code Run Time
Environment (RTE) and Software Development Kit (SDK) for the Java (TM) 2
Platform Standard Edition.

Please review the COPYRIGHT and LICENSE files in this same directory. They
have important information regarding your rights and responsibilities with
this software. Also, it will be very helpful to read README.TXT file
before reading text below as it contains important information about RTE.

-----------------------------------------------------------------------------

2. Product description

The OJI Plugin is an intermediate layer which enables the use of Java applets
in a Web browser such as Mozilla or IBM IWB.

The OJI Plugin consists of three parts: browser plugin, applet viewer and
a Java Native Interface (JNI) module.

The browser plugin interacts with the browser and implements a standard
plugin interface from the browser's point of view.

The applet viewer performs the actual loading and execution of the applet.

The JNI module is used by Java code for interaction with the browser.

-----------------------------------------------------------------------------

3. Hardware/Software Requirements

The plugin has no specific hardware requirements and any hardware, which
is capable of running the browser and Java application simultaneously with
reasonable speed, should be capable of running the plugin as well. The
consumption of resources (memory and CPU) of the plugin components is
negligible in comparison to the browser and JVM.

The plugin is supported for Mozilla version 1.4 or above or the IBM Web 
Browser 2.0.2 or above. Both the VAC++ (e.g. Mozilla 1.4.1 or IBM Web Browser
2.0.2) and GCC builds (e.g. Mozilla 1.5 and above) are supported.

Note that some GCC builds may not support OJI plugins, depending on the 
packaging, regardless of the plugin vendor. Usually for support of such 
plugins, Mozilla requires the ipluginw.dll file to be present in the 
components subdirectory. In particular there are several Mozilla 1.6 packages
with and without this DLL.  More information about OJI plugin support, its
dependencies and packaging can be obtained by contacting the Warpzilla Team
at http://www.mozilla.org/ports/os2/.

Mozilla versions prior to 1.4 are NOT SUPPORTED and WILL NOT WORK PROPERLY.

The plugin does not work with any of the Netscape Navigator versions (4.61,
4.04 or 2.02).

Support for other browser versions can be provided for a fee. If you require
support to be added for a specific browser, please contact GCD using the
instructions in section 9 below.

-----------------------------------------------------------------------------

4. Performance considerations

When the browser starts an applet for the first time, there is a time gap
necessary to launch JVM. All consequent applet startups do not experience
this delay. Once the applet is started its speed is completely determined by
the JVM.

-----------------------------------------------------------------------------

5. Installation/Configuration

The JVM should be installed before installation of the plugin. Please, refer
to README.TXT for details of the installation of the JVM.

Once the JVM is installed, installation of the plugin consist of five simple
steps:

1) Copy NPGCD.DLL file located in the <JVMPATH>\JRE\BIN to browser PLUGINS
   subdirectory. For example:

   If the JVM is installed in c:\java141 and the browser is installed in
   d:\apps\mozilla, then the following command would perform this copy:

   copy c:\java141\jre\bin\npgcd.dll d:\apps\mozilla\plugins

2) Provide information about location of the JVM executable files to the
   plugin.

   There are three possible options to do this:

   a) setup GCD_JAVA_HOME environment variable
   b) setup JAVA_HOME environment variable
   c) make JVM executables available via PATH

   The first approach is convenient in the case when several versions of the
   JVM should co-exist on the same system. The environment variable can be
   defined in CONFIG.SYS or in a .CMD file used to launch MOZILLA.EXE.

   For example (assume the JVM is installed in c:\java141 and the browser
   is installed in d:\apps\mozilla):

   In CONFIG.SYS:

      ...
      SET GCD_JAVA_HOME=c:\java141\jre
      ...

   In separate .CMD file:

      @echo off
      SET GCD_JAVA_HOME=c:\java141\jre
      d:\apps\mozilla\mozilla.exe

   The second approach is very similar to first one except the JAVA_HOME
   variable is used instead of GCD_JAVA_HOME. This approach should be used
   with care when several different versions of the JVM are installed,
   because the variable JAVA_HOME may interfere with other JVMs.

   The third approach can be used if the path to the JVM binaries is present
   in the PATH environment variable. In this case no additional setup is
   required.

3) Disable any other OJI Plugin that exists in the browser's plugin directory
   (see step 1 above).  At a minimum, the following files should be removed:

   npoji6.dll  - this is the IBM 1.3.1 OJI Plugin
   npj2*.dll   - this is the Innotek 1.4.2 OJI Plugin

   If you do not delete these files from the plugin directory, the actual
   plugin that is in use to run applets will not be known.  The browser
   will choose one of the plugins to run and the other plugins will never
   be invoked.  In this situation, the results will be indeterminate. DO
   NOT SUBMIT PROBLEM REPORTS IF YOU HAVE ANY OJI PLUGIN INSTALLED OTHER
   THAN THE GCD OJI PLUGIN.

4) Ensure that Java is enabled in the Mozilla Preferences.  Use the following
   menu item:

   Edit -> Preferences

   This will invoke the "Preferences" dialog window.  In the "Category"
   section on the left, select "Advanced".  On the right side of the window
   in the "Features that help interpret web pages" box, make sure that the
   "Enable Java" check box is selected.  Otherwise the OJI plugin will
   not be operational.

5) Make sure CLASSPATH does not have the standard IBM JVM 1.1.x entries. An
   effective way to do this is to "NULL" this environment variable as follows:

   SET CLASSPATH=

   If you encounter an error message such as "could not find main class" or
   if a NoClassDefFoundError is thrown when the JVM tries to load the main 
   class for the Java applet, you may be experiencing this issue.

-----------------------------------------------------------------------------

6. Known Problems

These are issues that are currently being resolved, however the resolution
for these problems was not available in time for this release.

- Clicking on an applet-owned portion of the browser window does not always
  bring the browser to the top of the Z-order.  This only happens in cases
  where the mouse click is in a Swing component.

- Under very stressful conditions (running 50-100 applets simultaneously
  including many large Swing applets), a SYS3175 trap has been observed in
  FONT.DLL.  This particular problem has not been recreated and any user
  that can recreate this issue is encouraged to submit a problem report to
  GCD. When this trap occurs there will be a hotspot log file in the current
  directory for Mozilla. Since the browser itself continues to run without
  problem, it can sometimes be difficult to know when this problem has
  occurred.  Note that no applets will be running nor will any applets be
  able to be started until the browser is closed and then restarted.

-----------------------------------------------------------------------------

7. Limitations

- No more than 1000 applets can be run simultaneously in a single system.
  Launching additional applets in excess of this amount may result in
  undefined behavior. There is no plan to resolve this unless required by
  a customer.  Please contact Golden Code Development if this is a
  requirement (see section 9 below).

- As of the GCD 1.4.1_07 release, the JSound implementation has been 
  completely rewritten.  This now provides a shared sound implementation
  which allows a Java applet to be a better citizen with the rest of the
  system in regards to its usage of the sound device.  On some sound cards,
  particularly those cards where only one sound device instance is available,
  the old exclusive approach caused problems because it would lock the device
  and never release it.  This problem has been eliminated however the nature
  of the OS/2 sound architecture is that only one OS/2 application may use
  a sound device at a time, even in "shared" mode.  This means that when an
  applet uses sound, the sound device will be owned by the applet as long as
  that applet is actively using the sound device.  In addition, some applets
  can be written to hold onto the sound device (even if not actively playing)
  until the applet is disposed.  Switching the active browser "tab" away from
  the applet or closing the applet will release the sound device in these 
  cases.
  
- The plugin architecture is designed such that a single JVM is used for all
  applets that are running in any Mozilla browser window.  This means that
  a single JAVAW.EXE process is running an arbitrary range of Java code from
  many potential sources.  Using a single JVM is the way all Sun plugins 
  work. On the Windows platform, this single JVM process is actually loaded
  in the same process address space as the browser itself. However, on OS/2
  (with the GCD OJI plugin) and on Linux/Unix (with Sun's plugins) the JVM
  process is a separate process which communicates with the plugin and 
  services all applets for the browser. If for some reason this JAVAW.EXE 
  process is killed or otherwise abnormally terminated, all applet usage for
  the browser will be disabled until the browser is restarted completely.
  This means that all instances of the browser must be closed before any new
  browser window can be started and before any applet will work.

-----------------------------------------------------------------------------

8. Submitting Problem Reports

To submit a problem report, please send an e-mail to:

  techsupport@goldencode.com

The following information should always be included in a problem submission:

  * Your name.
  * Your organization's name (if applicable).
  * Your reply-to e-mail address.
  * A detailed description of the problem, including steps on how to
    recreate the error condition.
  * If it is possible to isolate the problem with a small test case, the
    test case should be attached to the e-mail, or instructions on how to
    download the test case.
  * The plugin log files that was created when the problem was encountered,
    if the problem ended in a crash of the product. See below for the
    instruction

In order to create plugin log file do the following:

1) Make sure that all browser instances are closed. Replace NPGCD.DLL in 
   the browser PLUGINS subdirectory with NPGCD_G.DLL (it is present in the
   same place as NPGCD.DLL, see section 5 in this file for more details).

2) Open OS/2 Command Line window and perform following steps in the
   directory where browser binaries are placed:

   [d:\apps\mozilla]set java_plugin_trace=1
   [d:\apps\mozilla]mozilla >plugin_std.log 2>plugin_err.log

   Note names of the log files - plugin_std.log and plugin_std.log.
   You can choose other names if desired.

3) Perform the test case which exposes the problem and close browser
   window.

4) Replace NPGCD_G.DLL with NPGCD.DLL in the browser PLUGINS subdirectory.

Some problems may be caused by underlying defects in the OS/2 operating
system or other related IBM software. If a defect is found to be so caused,
Golden Code has an arrangement with IBM in which the two companies can
effectively work together to resolve such issues. The customer must open an
IBM PMR and authorize the IBM personnel to work with Golden Code on this
issue.

PLEASE NOTE THAT UNLESS YOU MAKE ARRANGEMENTS TO EXCHANGE ENCRYPTED E-MAIL
WITH GOLDEN CODE DEVELOPMENT, ANY E-MAIL YOU SEND IS NOT SECURE AND MAY BE
VIEWED IN TRANSIT. A secure, web-based defect reporting system for the use of
service clients is currently under development. We hope to have it available
shortly.

-----------------------------------------------------------------------------

9. Contacting Golden Code

E-mail   : info@goldencode.com (general), techsupport@goldencode.com
           (support)
Address  : 1455 Old Alabama Rd., Suite 135, Roswell, Georgia, U.S.A.
Phone    : +1 678-352-2301
Fax      : +1 678-352-2305

-----------------------------------------------------------------------------

10. Trademarks

'Golden Code' is a registered trademark of Golden Code Development
Corporation.

'IBM' and 'OS/2' are registered trademarks of International Business Machines
Corporation. 'WorkSpace On-Demand' is a trademark of International Business
Machines Corporations.

'Java', 'J2SE', and 'Java Compatible' are trademarks of Sun Microsystems,
Inc.

Other names referenced in this document are the property of their respective
owners.

-----------------------------------------------------------------------------
       Copyright (c) 2002-2004, Golden Code Development Corporation.
                            ALL RIGHTS RESERVED.
-----------------------------------------------------------------------------

