DEVELOPMENT ENVIRONMENT for Sun's Java(tm) Programming Environment
------------------------------------------------------------------

This is an OS/2 port of Sun's Java version 1.0.1 programming
environment.

Installation
------------

The Java development toolkit requires the Java runtime environment
to be installed. The development toolkit should be installed on top
of the runtime environment and requires a HPFS partition.

Contents
--------

The development environment contains:

  - javac compiler
  - prototype alpha quality command line debugger
  - C header files & libraries for building native methods
  - debug versions of all executables

The APPLET Tag
--------------

The applet tag is used to imbed a Java applet in an html page.

    '<' 'APPLET'
        ['CODEBASE' '=' codebaseURL]
        'CODE' '=' appletFile
        ['ALT' '=' alternateText]
        ['NAME' '=' appletInstanceName]
        'WIDTH' '=' pixels 'HEIGHT' '=' pixels
        ['ALIGN' '=' alignment]
        ['VSPACE' '=' pixels] ['HSPACE' '=' pixels]
    '>'

    ['<' 'PARAM' 'NAME' '=' appletAttribute1 'VALUE' '=' value '>']
    ['<' 'PARAM' 'NAME' '=' appletAttribute2 'VALUE' '=' value '>']
    . . .
    [alternateHTML]

    '</APPLET>'

'CODEBASE' '=' codebaseURL
    This optional attribute specifies the base URL of the applet --
    the directory that contains the applet's code.  If this attribute
    is not specified, then the document's URL is used.

'CODE' '=' appletFile
    This required attribute gives the name of the file that contains
    the applet's compiled Applet subclass.  This file is relative to
    the base URL of the applet.  It cannot be absolute.

'ALT' '=' alternateText
    This optional attribute specifies any text that should be
    displayed if the browser understands the APPLET tag but can't
    run Java applets.

'NAME' '=' appletInstanceName
    This optional attribute specifies a name for the applet instance,
    which makes it possible for applets on the same page to find (and
    communicate with) each other.

'WIDTH' '=' pixels 'HEIGHT' '=' pixels
    These required attributes give the initial width and height (in
    pixels) of the applet display area, not counting any windows or
    dialogs that the applet brings up.

'ALIGN' '=' alignment
    This required attribute specifies the alignment of the applet.
    The possible values of this attribute are the same as those for
    the IMG tag: left, right, top, texttop, middle, absmiddle,
    baseline, bottom, absbottom.

'VSPACE' '=' pixels 'HSPACE' '=' pixels
    These option attributes specify the number of pixels above and
    below the applet (VSPACE) and on each side of the applet (HSPACE).
    They're treated the same way as the IMG tag's VSPACE and HSPACE
    attributes.

'<' 'PARAM' 'NAME' '=' appletAttribute1 'VALUE' '=' value '>' . . .
    This tag is the only way to specify an applet-specific attribute.
    Applets access their attributes with the getParameter() method.

Building native methods
-----------------------

To use platform specific native methods in C on OS/2 the following steps
should be followed:

1. Create a java class source file which will wrap the native methods

   eg. class MyNativeClass
       {
         String x;
         ...
         public native demo(String x);
         ...
         static { System.loadLibrary("MyLib"); }
       }

   Note: the System.loadLibrary will be executed the first time the
         class is called and will load a DLL called MyLib which must
         contain the native methods.

2. Generate a .h file for your class file by using the javah utility

   eg. javah MyNativeClass

3. Generate a .c stub file for your class by using the javah utility

   eg. javah -stubs MyNativeClass

4. Write your native methods in C using entry points of the form
   <class name>_<method name>

   Note:

   The java virtual machine modifies the floating point unit control
   word to suppress some floating point exceptions. Native methods that
   wish to modify the floating point control word should save the
   control word content on entry and restore it on exit from the native
   method.

   The java virtual machine currently implements a voluntary suspend
   mechanism for garbage collection. This mechanism requires that all
   java threads periodically check for a suspend request. This
   mechanism will fail and garbage collection will not be possible
   if a native method enters a hard suspend of any duration. It is
   planned to replace this mechanism with a more robust none intrusive
   mechanism in the future but for the present it is recommended that
   native methods not enter into a hard wait of any length (that is
   a wait exceeding 1-2 seconds).

   eg. void MyNativeClass_demo(struct Hjava_lang_String * x)

5. Compile your C files. Your INCLUDE search path should include:

   eg. x:\javaos2\include;x:\javaos2\include\os2;

6. Link your C files containing the native methods with the C stub
   file produced in step 3 to produce a DLL with the name used in
   the System.loadLibrary statement in step 1. You will need to link
   with the supplied library x:\javaos2\lib\javai.lib (or the debug
   version) if you have used any Java runtime helper functions.

   The Java runtime uses IBM VisualAge C _Optlink calling convention
   to call native methods in DLL's.

To avoid possible dll name conflicts in the future it is recommended that
dll names not begin with the string "java".

JAVAC Compiler
--------------

If the javac compiler exhausts the default heap allocation of 6 megabytes,
then the compile can be attempted with a larger heap by using the -mx option
of the java interpreter.  For example to compile class LargeClass.java with
a heap of 10 megabytes, the following command could be entered

        java -mx10m sun.tools.javac.Main LargeClass.java

JDB debugger
------------

An prototype command line alpha quality Java Debugger is included
for helping to debug Java classes.

Files written through a PrintStream
-----------------------------------

Records written to a file using println method from the PrintStream class
are terminated with a single newline character (x'0a'), in line with the
standard Unix conventions. This differs from the OS/2 convention where
records are terminated with a pair (x'0d0a').

Java runtime will read files where records are terminated in either
convention.

Known problems
--------------

The Just In Time (JIT) compiler optimises out method tracing (-tm option)
and profiling. To obtain full method tracing and profiling rename the JIT
dll's to some other name, eg, rename javax*.dll to javax*.dl@