================================================================================
                             JavaPart README
================================================================================

Description:

    The JavaPart allows the embedding of Java Applets and Java Beans in OpenDoc.
    It uses IBM's J-Empower (version 1.1) technology which is freely available at:

        http://www.alphaWorks.ibm.com

    The JavaPart also depends on Sun's Java JDK 1.1, which must be setup prior
    to running the part.  (See Usage section for more details).


Setup:

IMPORTANT: Do to a limitation in either J-Empower or the JDK 1.1, JavaPart will
fail to start (trap in WINAWT.DLL) on systems whose display drivers are set to
run in 256 color mode (8 bit color).  Please set your display driver to run in
either 65,536 (16 bit color) or 16,777,216 (24 or 32 bit color) color mode.

    Before running the JavaPart, you will first need to download and
    install Sun's Java JDK 1.1 (or another Java 1.1 compiler).
    Sun's JDK 1.1 may be found at:

        http://www.javasoft.com/products/jdk/1.1/index.html

    After installing the JDK, make the following environment variable
    changes (assuming you installed the JDK in C:\Java):

    o  Set the JAVA_HOME environment variable to point to the JDK 1.1 directory.
       This environment variable is used when compiling the part as well as by
       the J-Empower runtime library when the part is being executed.

        JAVA_HOME=C:\Java

    o  Add the Java DLLs to the PATH

        PATH=%PATH%;%JAVA_HOME%\bin

    o  Create a new variable named CLASSPATH.  If you are running
       Windows 95, you should set this variable in your AUTOEXEC.BAT file,
       after the SETODENV.BAT file is run.

        CLASSPATH=.;%JAVA_HOME%\lib\classses.zip;%ODSRC%\bin\JavaPart.zip

       You may also wish to install Sun's BDK in order to have some beans to test.
       In this case, you must also add the BDK's demo directory (ie, "C:\BDK\demo")
       to your CLASSPATH, and make sure you have compiled any beans you wish to
       run.  For instance, to run the Juggler bean, you would need to go to the
       BDK demo directory, issue "nmake -f juggler.mk", then choose "Embed Bean"
       and enter the juggler's package name and class name, separated by "."s, as
       in "sunw.demo.juggler.Juggler".  You can also embed serialized beans, such
       as the Orange Button from the BDK (be sure to issue "nmake -f buttons.mk"
       from the BDK demo directory first!), again by entering the package name
       followed by the name of the serialized bean, separated by "."s, as in
       "sunw.demo.buttons.OrangeButton".  Note that in each case, the suffix of
       ".class" or ".ser" is omitted.

    After setting up the JDK, install the JavaPart by running:

        odinst iodjava.odz


Running:

    The JavaPart behaves like all other OpenDoc parts.  It may be embedded
    any OpenDoc container (such as BaseContainer), or OLE 2 container.

    The JavaPart has menus for the following:

        "Load Applet"   -  select a Java Applet to embed.

        "Load Bean"     -  select a Java Bean to embed.

        "Show console"  -  show the Java console.

        "Start Applet"  -  start the Java Applet (after it has been stopped).

        "Stop Applet"   -  stop the Java Applet

        "Preferences"   -  specify the applet that is run when a new JavaPart is
                           embedded.  Also allows you to specify whether to use
                           a proxy, and if so, to specify the proxy host and port.


Building:

    The JavaPart may be built with either IBM's VisualAge or Microsoft's
    Visual C++.

    The JavaPart is dependant upon the utilities which is compiler
    specific.  Thus rebuild the following library before attempting to
    build the JavaPart:  $(ODSRC)/src/utils.


Files:

    makefile     --  NMAKE file

    iodjava.idl  --  SOM IDL definitions for the JavaPart SOM class
    iodjava.cpp  --  OpenDoc methods
    iodjava.def  --  Library definitions
    iodjava.h    --  Global constants
    iodjava.rc   --  Resource file

    applet.h     --  Applet class
    applet.cpp

    bean.h       --  Bean class
    bean.cpp

    tag.cpp      --  Applet/Bean tag information/parsing
    tag.h
    jemppars.cpp
    jemppars.h

    dialog.h     --  Dialogs
    dialog.cpp
    help.h
    help.cpp
    prefdlg.cpp
    prefdlg.h
    propdlg.cpp
    propdlg.h

    misc.cpp     --  Misc routines
    misc.h

    javapart.zip --  Java class files for J-Empower and initial applet

    jempn11.dll  --  J-Empower 1.1 runtime library
    jempn11.lib
    jempower.h


Limitations and Known Bugs:

    (1)  Not all Java Applets will run within the JavaPart.  A good way to
         test if a java applet is compatible with your version of the JDK is
         to run "appletviewer" against any .html files containing applets
         you would like JavaPart to load.  For instance, to ensure that
         JavaPart's default applet will load, say "appletviewer JavaPart.htm"
         from the %ODSRC%\include directory.

    (2)  Sometimes a small grey rectangle will appear in the top left
         corner of the JavaPart.  When this problem occurs, reload the
         Applet by activating the JavaPart and using the
         Applet->"Load from File" menu option.

    (3)  The JavaPart can only be selected (for cut, copy, paste,... etc)
         by clicking on the activation border once the part is active.

    (4)  Sometimes JavaPart will not activate on the first mouse click
         inside its window - if this happens, a second click on the JavaPart
         window will be necessary.

    (5)  When run as a root part, the Java Applet may not fill the entire
         window.

    (6)  After a drag/drop operation, you may need to force a repaint in
         order to see the JavaPart.

    (7)  This version of the JavaPart does not provide printing support.

    (8)  JavaPart will not run in 256 color mode - please use 64K or 16M colors.
         New versions of J-Empower or the JDK may remove this limitation

    (9)  A TCP/IP stack is required in order to run JavaPart.

    (10) Due to a J-Empower limitation, beans that are also applets (that are
         loaded via "Load Bean") will not have the applet "Start" method called.
         This means beans such as the Juggler will not start juggling when
         loaded, but rather will just sit there statically, only displaying the
         initial image.  It is recommended that such beans be loaded via the
         "Load applet" menu item, as this will assure the applet is started.

    (11) In order to protect against a loss of data, you should manually save the document.
 

