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, and
Windows XP/Server 2003/Vista, 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 Java2, Java5, and Java6 for Solaris, Windows, and
Linux from

  http://java.sun.com

Make sure to add javac and java to your PATH.

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 systems with IPv6 enabled, you may experience occasional hangs 
the first time an Ice object adapter is activated within a JVM. A 
work-around is to disable IPv6 support by setting the Java property 
java.net.preferIPv4Stack to true. For example:

  java -Djava.net.preferIPv4Stack=true MyClass ...

For more information on this issue, refer to Sun's bug database:

  http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=6483406


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.5.20.

ZeroC provides Berkeley DB binary distributions (with Java support)
for many platforms: 

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

Alternatively, you can build Berkeley DB yourself; the Berkeley DB 
source distribution is available at

  http://www.oracle.com/database/berkeley-db/index.html

This source distribution, plus a number of patches, is also available
at

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

When you build Berkeley DB, make sure to configure Berkeley DB with
Java support. For Linux, this is done by specifying the --enable-java
option when running the configure script. On Windows, you must select
the project "db_java -- Win32 Release".

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/db45/lib:$LD_LIBRARY_PATH


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 
XP/Vista, you can download a Python distribution from:

  http://www.python.org/download


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

Some of the Ice for Java tests employ applications that are part of the
Ice for C++ distribution. You need to set the ICE_HOME environment
variable to the path where these applications are installed for these
tests to run properly:

  # On Unix.
  $ export ICE_HOME=/opt/Ice-3.2.1

  # On Windows
  > set ICE_HOME=c:\Ice-3.2.1

Python is required to run the test suite:

  http://www.python.org/download

To run the tests, open a command window and change to the top-level
directory. At the command prompt, execute:

  > python allTests.py

You can also run tests individually by changing to the test directory
and running this command:

  > python run.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 using the following command:

$ java -jar IceGridGUI.jar

IceGridGUI.jar is currently built only with a Java2 compiler or
by passing -Djdk=1.4 to ant. 


======================================================================
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.

Ice for Java includes ant tasks for translating Slice to Java. The ant
tasks allow the slice2java and slice2freezej to be efficiently invoked
from the build system. These tasks require one of the following:

 - You correctly install the translators in the standard location,
   /opt/Ice-3.2.1. If you have not created the /opt/Ice-@mmver@ symbolic
   link, you will also need add /opt/Ice-3.2.1/lib to your shared
   library search path. See the READMEs in your Ice for C++ or Ice
   binary installation for more information.

 - If you have installed Ice in a non-standard location, you specify the
   location of the Ice installation containing the translators with the
   ice.home property:

   ant -Dice.home=/home/bill/Ice-3.2.1

 - For non-standard installations, you can also use the ICE_HOME
   environment variable to specify the location of the Ice installation
   containing the translators:

   $ export ICE_HOME=/home/bill/Ice-3.2.1

 - If neither ice.home or ICE_HOME are available, the ant tasks will
   simply invoke the translator without an absolute path, relying on the
   translators being in a directory in your PATH for successful
   execution. If they are not anywhere in the PATH, the build will fail.

Unless you modified the Ice build system to change the embedded library
information, you will also need to add the path containing the Ice
shared libraries to your shared library search path.

   $ export LD_LIBRARY_PATH=/home/bill/Ice-3.2.1/lib:$LD_LIBRARY_PATH
   
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 will 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.
