This distribution contains the Ice for Java source code, class files,
and HTML reference material. The following sections describe the
requirements for using Ice for Java and provide instructions for
installing it.


======================================================================
Requirements
======================================================================


Operating systems
-----------------

Ice for Java has been tested under Linux, Solaris, HP-UX, MacOS X, AIX
and Windows 2000/XP, but due to the portability of Java, it is very
likely that it will also work on other platforms for which a suitable
Java implementation is available.

Note, however, that you will need the Slice to Java translator (see
below). ZeroC provides translator binaries for supported platforms.
For other platforms, you will have to either port Ice for C++ (which
contains the Slice to Java translator), or you will have to translate
Slice to Java on a supported platform, and copy the resulting Java
files to your target platform.


Java version
------------

Ice for Java requires Java version 1.4.2 or later. Older versions are
not supported, because Ice makes use of the new java.nio packages.
(java.nio was introduced in version 1.4.0, but was broken on Windows.)

You can download the Java 2 Platform, Standard Edition from
http://java.sun.com/j2se/.

Make sure to add javac and java to your PATH.

On HP-UX 11, we recommend using JDK 1.4.2.06 along with patch
PHNE_29887 to avoid the potential for hangs during shutdown. See the
link below for more information:

http://www.hp.com/products1/unix/java/java2/sdkrte14/downloads/index_pa-risc.html

On Linux x86_64, we recommend using JRE 1.5.0_07 or an ealier version. 
JRE 1.5.0_08 and JRE 1.5.0_09 introduced a bug that affects Freeze maps.

When using the Ice for Java SSL plugin (IceSSL), you may experience
occasional hangs. The most likely reason is that your system's entropy
pool is empty. If you have sufficient system privileges, you can solve
this issue by editing the following file

<java.home>/jre/lib/security/java.security

and changing it to use /dev/urandom instead of /dev/random. If you do
not have permission to modify the security file, you can also use the
command line option shown below:

java -Djava.security.egd=file:/dev/urandom MyClass ...

On AIX, IceSSL requires that you use IBMJSSE2 as your security
provider for Java 2. (Java 5 uses IBMJSSE2 by default.) You must edit
the java.security file shown above and modify the value of the
security.provider.1 property as follows:

security.provider.1=com.ibm.jsse2.IBMJSSEProvider2


Slice to Java translator
------------------------

You will need the Slice to Java translator and supporting executables
and libraries. You can download a binary distribution from the ZeroC
web site, or you can build Ice for C++ yourself.

Binary distributions for the supported platforms are available at

http://www.zeroc.com/download.html


Berkeley DB
-----------

Freeze for Java uses Berkeley DB as its underlying database. It
requires Berkeley DB 4.3.

Even though Berkeley DB is included with many Linux distributions, the
Java files for Berkeley DB are usually not available, which requires
you to build Berkeley DB manually.

You can download the Berkeley DB source distribution from:

http://www.sleepycat.com/download

When you build Berkeley DB, make sure to configure Berkeley DB with
Java support. For Linux, this is done by specifying --enable-java with
"configure". For Windows 2000/XP, you must select the "db_java --
Win32 Release" project. For details, please see:

http://www.sleepycat.com/docs/index.html

On Fedora Core 4, it is necessary to change the compiler's default
optimization level when building Berkeley DB in order to avoid a bug
in the packaged GCC compiler. We recommend you use the following
syntax when you run configure:

$ CFLAGS="-O1" ../dist/configure <your configure options>

Make sure to add db.jar to your CLASSPATH, and verify that the
Berkeley DB shared libraries are in your java.library.path. On Linux,
this can be achieved by adding <Berkeley DB home>/lib to your
LD_LIBRARY_PATH, for example:

$ export LD_LIBRARY_PATH=/opt/db4/lib:$LD_LIBRARY_PATH

Note that the Ice for Java distribution is compiled against Berkeley
DB 4.3.29.


bzip2
-----

Ice for Java supports protocol compression using the bzip2 classes
included with Apache Ant (see "Compiling the Source" below).

Compression is automatically enabled if the classes are present in the
CLASSPATH. You can either add ant.jar to your CLASSPATH, or download
only the bzip2 classes from

http://www.kohsuke.org/bzip2/

Note that these classes are a pure Java implementation of the bzip2
algorithm and therefore add significant latency to Ice requests.


JGoodies
--------

The graphical IceGrid administrative tool (see below) uses
JGoodies Looks and JGoodies Forms. You do not need to download
these libraries unless you intend to recompile the Ice for Java
source code.

The libraries are available here:

http://www.jgoodies.com/downloads/libraries.html


ProGuard
--------

ProGuard is used to create the JAR file for the IceGrid graphical
application. You do not need to download ProGuard unless you intend
to recompile the Ice for Java source code. See "Compiling the Source"
below for more information.

ProGuard is available here:

http://proguard.sourceforge.net


Python
------

To run the automated test suite, you will need Python 2.2 or later. 
If you have no interest in running the test scripts, Python is not 
required. Linux distributions usually include Python. For Windows 
2000/XP, you can download a Python distribution from:

http://www.python.org/download


======================================================================
Tests and Demos
======================================================================

You can run the Ice for Java test suite, provided that you have
installed Python:

python allTests.py

If everything worked out, you should see lots of "ok" messages. In
case of a failure, the tests abort with "failed".

If you want to try out any of the demos, make sure to add lib/Ice.jar
and "classes" to your CLASSPATH. Then change to the desired demo
directory and follow the instructions in the README file. If no README
file is present, the demo can be run by entering the following command
to start the server:

$ java Server

Then in a separate window enter the following command to start the
client:

$ java Client


======================================================================
IceGrid Administrative Console
======================================================================

A graphical administrative tool for IceGrid is provided in the file

lib/IceGridGUI.jar

This archive is completely self-contained. You can start the
application with the following command:

$ java -jar IceGridGUI.jar


======================================================================
Compiling the Source
======================================================================

There is generally no need to compile Ice for Java because this
distribution already contains the class files for the Ice core, Ice
services, examples and tests.

If you want to rebuild the source code, you will need to obtain the
'ant' utility from

http://ant.apache.org/

Ice requires ant 1.6.3 or later, but we recommend using the most
recent release.

The third-party dependencies that Ice requires must be in your
CLASSPATH.

If you want to create a standalone JAR file for the IceGrid
administrative console, you must have ProGuard in your CLASSPATH,
and you should review config/build.properties to ensure the pathnames
are correct. If ProGuard's JAR file is not present in your CLASSPATH
during the build, the resulting IceGridGUI.jar file will not be a
standalone JAR file but instead depend on Ice.jar and the JGoodies
libraries.

After installing ant, run the following commands to completely rebuild
the Ice for Java source code:

$ ant clean
$ ant


======================================================================
Installation
======================================================================

No automatic installation for Ice for Java is supported. Simply copy
the Ice.jar file from the lib directory to the directory of your
choice, and then add Ice.jar to your CLASSPATH.


======================================================================
MacOS X Notes
======================================================================

On MacOS X, an Ice server may not correctly detect the closure of
client connections, which can lead to a hang during server shutdown.
This appears to be caused by a problem in the JVM implementation, but
we are still looking into this issue. Until we resolve this matter, We
recommend the use of timeouts in object adapter endpoints.
