Installation instructions for JavaGroups

Source and Binary Distribution

The binary distribution (bin.zip) contains all class files in JAR format (JavaGroups.jar), plus the Javadoc documentation (doc.zip) and demo programs (Tests.zip). If you are not interested in the source code, download these 3 files. Read the next section on how to install the binary distribution.

The source distribution consists of file JavaGroups.zip. If you want all of the above, plus source code, download this file. Skip the next section and read the section about how to install the source distribution.

Installing the binary distribution

Unzip doc.zip. This will create a directory doc containing the Javadoc documentation
Unzip Tests.zip. This creates a directory Tests containing source and class files for the demo applications.
Add JavaGroups.jar to your CLASSPATH, e.g.:
```
        export CLASSPATH=$CLASSPATH:/home/mydir/JavaGroups.jar
       
```
Note that it is probably advisable to add a period (.:) to your CLASSPATH so that class files in the current directory are found correctly (e.g. for the demo programs).

Installing and compiling the source distribution

Unzip JavaGroups.zip. This will create a directory JavaGroups.
Add this directory to your CLASSPATH, e.g.:
```
	   export CLASSPATH=$CLASSPATH:/home/mydir
       
```
(JavaGroups would be in /home/mydir/JavaGroups). Note that it is probably advisable to add a period (.:) to your CLASSPATH so that class files in the current directory are found correctly (e.g. for the demo programs).
Recreating the class files:
1. All the class files are already available in the source distribution, so you only need to recompile if you have modified some files !
2. You need to have make available on your system.
3. Type make all in the JavaGroups directory. If you also want to create the iBus adapter (class IbusChannel), type make ibus. (You need to have the iBus classes if you want to do this). If you want to create JavaGroups.jar, type make JavaGroups.jar. This will create the JAR file in the parent directory.
4. To create the demo applications, type make all in the Tests subdirectory.

Setting up JavaGroups for Normal Use

There are no special steps to be taken when using JavaGroups over the default transport. The default transport is a protocol stack called JChannel which is a pure Java implementation of a reliable protocol stack. Currently, the default transport does not offer any reliability guarantees (contrary to Ensemble), but the interface for applications is the same, regardless of the underlying group transport used.

See the documentation for more information on JChannel.

Setting up JavaGroups for Use over Ensemble

To use JavaGroups on top of Ensemble, Ensemble has to be installed. Refer to Ensemble's installation instructions for details. The following steps have to be taken to use JavaGroups over Ensemble:

Set the environment variables required for Ensemble (ENS_PORT, ENS_GOSSIP_HOSTS and ENS_GOSSIP_PORT etc).
Put the outboard executable somewhere in your PATH. JavaGroups will spawn this executable in a separate process and therefore needs to find it.
Start a gossip daemon before using JavaGroups in case Ensemble is not enabled to use IP multicast (see the Ensemble documentation on how to enable/disable Ensemble for IP multicast).

Setting up JavaGroups for Use over iBus

Download iBus from SoftWired.

Put the ibus_xx.jar file in your CLASSPATH:

export CLASSPATH=$CLASSPATH:/mydirectory/ibus_xx.jar

Testing your Setup

To see whether your system can find the JavaGroups classes, execute the following command:

javap JavaGroups.Channel

You should see the following output if the class is found:

Compiled from Channel.java
public abstract synchronized class JavaGroups.Channel extends java.lang.Object implements JavaGroups.Transportable 
    /* ACC_SUPER bit set */
{
    public abstract void Connect(long);
    public abstract void Disconnect();
    public abstract void Destroy();
    public abstract void Cast(byte[]);
    public abstract void Send(java.lang.Object, byte[]);
    public abstract void Send(java.util.Vector, byte[]);
    public abstract void Send(JavaGroups.Message);
    public abstract JavaGroups.Message Receive(long);
    public abstract java.util.Vector GetMembers();
    public abstract int GetNumMembers();
    public abstract void SetMembershipListener(JavaGroups.MembershipListener);
    public abstract java.lang.Object GetAddress();
    public abstract java.lang.String GetName();
    public JavaGroups.Channel();
}

Javap lists the variables and methods of class Channel. If this does not work, the JavaGroups classes have not been aded correctly to your CLASSPATH. Go back to the installation instructions to correct this problem.

Running a Demo Program

Change to the ./Tests directory.

Testing for Normal Use

Run the Draw program:

java Draw

A drawing window should appear. Start a second instance. Both instances should change their membership (shown in the title bar) to 2. When drawing the mouse in one window, the second instance should also be updated. As the default group transport uses IP multicast, make sure that - if you want start the 2 instances in different subnets - IP multicast is enabled. If this is not the case, the 2 instances won't 'find' each other and the sample won't work. (See the documentation how to use gossip to solve this problem. Note that the CLASSPATH needs to contain a period (.: to find the local Draw class !. If this is not the case, the JVM will complain that it cannot find class Draw !

Testing for Use over Ensemble

The Draw program can be run over Ensemble using the -type option when starting it:

java Draw -type ens

JavaGroups tries to start the outboard executable and waits 2.5 seconds until outboard is running. Then JavaGroups connects to outboard via a socket. There are several problems that might occur when trying to run JavaGroups over outboard:

The outboard executable is not found. It is probably not in your PATH.
2.5 seconds are too short to start up outboard before connecting to it. This might be the case when the machine is heavily loaded. Either decrease the load or increae the timeout value. In the latter case, look for Thread.sleep in file ./Ensemble/HotEnsemble.java and increase its timeout.
The instances don't 'find' each other. The problem might be that IP multicast is not enabled for Ensemble and the gossip daemon is not running. Start gossip before running the program:
```
gossip&
       
```

Testing for Use over iBus

Make sure that you have compiled the iBus adapter (class IbusChannel). Also ensure that you have the iBus JAR file in your CLASSPATH:

javap iBus.Stack

You should see the contents of this class printed. Run the Draw program using the -type option:

java Draw -type ibus

The behavior of the samples should be the same as before.