Java Applet plugin for RISC OS                                  0.74 (01-Jun-98)
==============================

This is the Java Applet Environment (JAE) 1.0.2 plugin for RISC OS browsers.
It will run the vast majority of Java applets currently found on the web.

Requirements
============
You will require a minimum of 8M RAM, and a RISC OS 3.5 or greater machine. A
StrongARM is recommended for more complicated applets.

Sound support is only provided on machines with 16bit sound hardware (this
includes all STBs, NCs, A7000s, and newer RiscPCs).

Memory usage
============
The Java heap is statically allocated at startup - it cannot be changed when
running. The size can be controlled by setting the system variable
<Java$MaxHeap> (as done in !Java.SetVars). The following examples are
reasonable for various memory sized machines:

        Total memory            <Java$MaxHeap>
        8M                      2500K
        16M                     5M
        32M                     10M
        64M                     20M

The larger the maxheap, the more applets you will be able to run. Large
applets, such as JQuake or Corel Office require a max heap of somewhere
around 20M.

Memory display
==============
The 'Memory usage...' iconbar menu option allows you to view the amount
of free space in your Java heap. A 'Garbage collect' button is provided to
give a hint to the virtual machine that you would like to free up some
heap space - if this doesn't work at first, it does not necessarily mean
that free space cannot be recovered.

Speed of the desktop
====================
When the Java virtual machine is under a high load, the machine can slow down
more than desired. The system variable <Java$PollDelay> can be set to control
the maximum delay (in milli-seconds) between wimp polls - the higher the
value, the more time the virtual machine has to execute, but the less
responsive the desktop will be. The lower the value, the less time the
virtual machine has, but the desktop will appear quicker. A setting of around
200 is a reasonable compromise.

The Priority option from the iconbar menu allows you to change these settings
while Java is running.

Console
=======
A console option has been added to the Java iconbar menu. Any errors or
textual output which occurs before you have opened the console do not get shown.

The Java console displays all text that an applet outputs to System.out
and System.err, including any backtraces from an exception. It is often
useful for debugging applets, or to discover if an applet cannot run due
to running out of memory, etc.

Just-In-Time Compiler (JIT)
===========================
This release contains a beta of Acorn's JIT. This currently gives around a
four-times speed increase on benchmark applets. By default, it is disabled
in the file !Java.!SetVars, since it is not yet fully stable. To enable it,
set the system variable <Java$JIT> On.

In the beta JIT, you must turn applet security off - edit the file
!Java.lib.plugin.properties, and set the property 'security.mode' to
'unrestricted'.

Proxy
=====
Java 1.0.2 fetches its own classes, rather than using the Browser. Because of
this, it can not detect whether you have configured an HTTP proxy. To
configure Java to use a proxy, the file !Java.lib.plugin.properties needs
modifying.

If you are running WebServe, the following settings should work:
        # Proxies
        proxySet=true
        proxyHost=localhost
        proxyPort=80

To disable all proxying, and to fetch all classes directly, only the proxySet
line need be set to 'false'.

Font Blending
=============
The RISC OS AWT uses anti-aliased fonts, blended to the background. However,
several applets on the web suffer a slightly corrupted display with blending
because they erase the text by plotting over it in the background colour.
The property "awt.blendfonts" in !Java.lib.plugin.properties lets you
turn these off if required by setting the value to "false".

Timeout
=======
The system variable <Java$Timeout> set in !Java.!SetVars allows you to specify,
in seconds, the time before Java automatically quits, assuming it is not
displaying any applets. A value of zero means never timeout.

Bootup Thread
=============
The parameter 'bootClass' in the !Java.lib.plugin.properties file allows you
to specify a class which is run when the plugin starts. The specified class
will have full access to the JVM - it will not go via any security
manager. It must lie in the given classpath and must implement
java.lang.Runnable.

Some applet sites
=================
The following sites contain collections of applets, and are probably worth
visiting:
        http://www.javasoft.com/        The home of JavaSoft
        http://www.gamelan.com/         Probably the biggest Java collection
        http://www.javaboutique.com/    A smaller, but nicer, collection

There are a few links to Java enabled sites on:
        http://www.acorn.co.uk/browser/links.html

Problems
========
If no applets appear, please try the following before requesting help:

  o Ensure that if you are using a proxy, you have set the details correctly
    in the !Java.lib.plugin.properties file. (See above)

  o Set the system variables <Java$Err> and <Java$Out> to (for example):
        Set Java$Err adfs::4.$.stderr
        Set Java$Out adfs::4.$.stdout
    Then re-run Java, and after about 10 seconds, quit it. The output should
    help locate the problem. If the files are empty, re-run !Java and wait
    longer.

Feedback
========
Please report bugs to us via the following URL:
        http://www.acorn.com/browser/bugform.html

These will then be entered directly into our faults database.
