Installation Instructions for JavaGroups 2.0.1

Requirements

• JavaGroups 2.0.2 requires JDK 1.3 (or higher). There is no JNI code present so it should run on all platforms. JDK 1.4 is fine too.
• An XML parser is required for configuration of JavaGroups if you want the ability to use XML configuration files for class mapping, and to read protocol stack specifications in XML format. Not using an XML parser will result in slower serialization and limit you to use only plain protocol stack configuration strings.
  Note that there is an XML parser shipped with JavaGroups in the lib directory. Add the JAR files xercesimpl-2.1.0.jar and xercesxmlapi-2.1.0.jar to your CLASSPATH. Note that any other JAXP compliant XML parser can be used.
• If you want to generate HTML-based test reports from the unittests, then xalan.jar needs to be in the CLASSPATH (also available in the lib directory)
  

Installing the binary distribution

1. javagroups-all.jar: the JavaGroups library including the demos
2. CREDITS: list of contributors
3. INSTALL.html: this file
4. xercesimpl-2.1.0.jar: the Xerces parser implementation (see http://xml.apache.org )
5. xercesxmlapi-2.1.0.jar: the Xerces parser APIs
6. jms.jar: JMS library
   

Installing the source distribution

1. conf: configuration files needed by JavaGroups, plus default protocol stack definitions
2. doc: documentation
3. lib: various JARs needed to build and run JavaGroups:
1. Ant JARs: used to build JavaGroups. If you already have Ant installed, you won't need these files
2. jms.jar: JMS library. Needed if you intend to run the org.javagroups.protocols.JMS protocol
3. junit.jar: to run the JUnit test cases
4. xalan.jar : to format the output of the JUnit tests using an XSLT converter to HTML
5. xercesimpl-2.1.0.jar: the Xerces parser implementation (see http://xml.apache.org )
6. xercesxmlapi-2.1.0.jar: the Xerces parser APIs

Building JavaGroups with the ANT build system (source distribution only)

1. Unzip the source distribution, e.g. unzip JavaGroups-2.0.2.src.zip. This will create the JavaGroups-2.0.2 directory (root directory) under the current directory.
   
2. cd to the root directory
3. Modify build.properties if you want to use a Java compiler other than javac (e.g. jikes)
   
4. On UNIX systems use build.sh, on Windows build.bat: $> ./build.sh compile
5. This will compile all Java files (into the classes directory). Note that if you want to compile all JDK 1.4-only classes use ./build.sh compile-1.4 instead. 
6. To generate the JARs: $> ./build.sh jar
7. This will generate the following JAR files in the dist directory:
   
   • javagroups-core.jar - the core javagroups libraries
   • javagroups-all.jar - the complete javagroups libraries including demos and unit tests
   • javagroups-test.jar - the javagroups test libraries
   • javagroups-demo.jar - the javagroups demo libraries
8. The CLASSPATH now has to be set accordingly: the following directories and/or JARs have to be included:
1. <JavaGroups rootdir>/classes
2. <JavaGroups rootdir>/conf
3. All needed JAR files in <JavaGroups rootdir>/lib. To simple run JavaGroups, the Xerces JARs are sufficient. To build from sources, the two Ant JARs are required. To run unit tests, the JUnit (and possibly the Xalan) JARs are needed.
   
9. To generate JavaDocs simple run $>  ./build.sh javadoc and the Javadoc documentation will be generated in the  dist/javadoc directory
10. Note that - if you already have Ant installed on your system - you do not need to use build.sh or build.bat, simply invoke ant on the build.xml file. To be able to invoked ant from any directory below the root directory, place ANT_ARGS="-find build.xml -emacs" into the .antrc file in yourhome directory.
    
11. For more details on Ant see http://jakarta.apache.org/ant/ .

Testing your Setup

java org.javagroups.Version

Version:        2.0.2
CVS:            $Id: INSTALL.html,v 1.14 2002/08/31 23:05:18 belaban Exp $
History:        (see doc/history.txt for details)

Running a Demo Program

java org.javagroups.demos.Draw

When drawing in one window, the second instance should also be updated. As the default group transport uses IP multicast, make sure that - if you want to 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.

You can change the properties of the demo to for example use a different transport if multicast doesn't work (it should always work on the same machine). Please consult the documentation to see how to do this.
 

Using IP Multicasting without a network connection

route add -net 224.0.0.0 netmask 224.0.0.0 dev lo

Typical home networks have a gateway/firewall with 2 NICs: the first (eth0) is connected to the outside world (Internet Service Provider), the second (eth1) to the internal network, with the gateway firewalling/masquerading traffic between the internal and external networks. If no route for multicast traffic is added, the default will be to use the fdefault gateway, which will typically direct the multicast traffic towards the ISP. To prevent this (e.g. ISP drops multicast traffic, or latency is too high), we recommend to add a route for multicast traffic which goes to the internal network (e.g. eth1).
 

It doesn't work !

java org.javagroups.tests.McastReceiverTest -mcast_addr 224.10.10.10 -port 5555

java org.javagroups.tests.McastSenderTest -mcast_addr 224.10.10.10 -port 5555

Other means of getting help: there is a public forum on javagroups.sf.net for questions. Also consider subscribing to the javagroups-users mailing list to discuss such and other problems. 

The instances still don't find each other ! 

In this case we have to use a sledgehammer (running only under JDK 1.4. and higher): we can enable the above sender and receiver test to use all available interfaces for sending and receiving. One of them will certainly be the right one... Start the receiver as follows:

java org.javagroups.tests.McastReceiverTest1_4 -mcast_addr 228.8.8.8 -use_all_interfaces

The multicast receiver uses the 1.4 functionality to list all available network interfaces and bind to all of them (including the loopback interface). This means that whichever interface a packet comes in on, we will receive it.
Now start the sender:

java org.javagroups.tests.McastSenderTest1_4 -mcast_addr 228.8.8.8 -use_all_interfaces

The sender will also determine the available network interfaces and send each packet over all interfaces.

This test can be used to find out which network interface to bind to when previously no packets were received. E.g. when you see the following output in the receiver:

bash-2.03$ java org.javagroups.tests.McastReceiverTest1_4 -mcast_addr 228.8.8.8 -bind_addr 192.168.168.4
Socket=0.0.0.0/0.0.0.0:5555, bind interface=/192.168.168.4
dd [sender=192.168.168.4:5555]
dd [sender=192.168.168.1:5555]
dd [sender=192.168.168.2:5555]

you know that you can bind to any of the 192.168.168.{1,2,4} interfaces to receive your multicast packets. In this case you would need to modify your protocol spec to include bind_addr=192.168.168.2 in UDP, e.g. "UDP(mcast_addr=228.8.8.8;bind_addr=192.168.168.2):..." .

Alternatively you can use McastDiscovery1_4 (runs only on JDK 1.4). Start this program simultaneously on multiple machines. Binding to all available interfaces, this program tries to discover what other members are available in a network and determines which interfaces should be used by UDP. After some time (e.g. 30 seconds), press <enter> on each program. The program will then list the interfaces which can be used to bind to. There may be one or multiple interfaces. When there are multiple interfaces listed, take the one with the highest number of responses (at the top of the list). The UDP protocol spec can then be changed to explicitly bind to that interface, e.g.

"UDP(bind_addr=<interface>;...)"

I have discovered a bug !

• Version of JavaGroups (java org.javagroups.Version)
• Platform (e.g. Solaris 8)
• Version of JDK (e.g. JDK 1.3.1)
• Stack trace. Use kill -3 PID on UNIX systems or CTRL-BREAK on windows machines
• Small program that reproduces the bug