- 2.1. Requirements
- 2.2. Structure of the source version
- 2.3. Building JGroups (source distribution only)
- 2.4. Logging
- 2.5. Testing your Setup
- 2.6. Running a Demo Program
- 2.7. Using IP Multicasting without a network connection
- 2.8. It doesn't work !
- 2.9. Problems with IPv6
- 2.10. Wiki
- 2.11. I have discovered a bug !
- 2.12. Supported classes
The installation refers to version 3.x of JGroups. Refer to the installation instructions (INSTALL.html) that are shipped with the JGroups version you downloaded for details.
The JGroups JAR can be downloaded from SourceForge. It is named jgroups-x.y.z, where x=major, y=minor and z=patch version, for example jgroups-3.0.0.Final.jar. The JAR is all that's needed to get started using JGroups; it contains all core, demo and (selected) test classes, the sample XML configuration files and the schema.
The source code is hosted on GitHub. To build JGroups, ANT is currently used. In Section 2.3, “Building JGroups (source distribution only)” we'll show how to build JGroups from source.
- JGroups 3.x requires JDK 6 or higher.
- There is no JNI code present so JGroups should run on all platforms.
- 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)
- Logging: by default, JGroups tries to use log4j2. If the classes are not found on the classpath, it resorts to log4j, and if still not found, it falls back to the java.util.logging logger. See Section 2.4, “Logging” for details on log configuration.
The source version consists of the following directories and files:
src: the sources
tests: unit and stress tests
lib: JARs needed to either run the unit tests, or build the manual etc. No JARs from here are required at runtime !
conf: configuration files needed by JGroups, plus default protocol stack definitions
doc: documentation
Download the sources from GitHub, either via 'git clone', or the download link into a directory "JGroups", e.g. /home/bela/JGroups.
Change to the JGroups directory
On UNIX systems use
build.sh, on Windowsbuild.bat:$> ./build.shThis will compile all Java files (into the
classesdirectory).To generate the JARs:
$> ./build.sh jarThis will generate the following JAR files in the
distdirectory:jgroups-3.x.y.jar- the JGroups JARjgroups-sources.jar- the source code for the core classes and demos.
Now add the following directories to the classpath:
JGroups/classesJGroups/confAll needed JAR files in
JGroups/lib. To build from sources, the two Ant JARs are required. To run unit tests, the JUnit (and possibly Xalan) JARs are needed.
To generate JavaDocs simple run
$> ./build.sh javadocand the Javadoc documentation will be generated in thedist/javadocdirectoryNote 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.antrcfile in your home directory.For more details on Ant see http://jakarta.apache.org/ant/.
JGroups has no runtime dependencies; all that's need to use it is to have jgroups.jar on the classpath. However, for logging, this means the JVM's logging (java.util.logging) is used.
However, JGroups can use any other logging framework. By default, log4j and log4j2 are supported if the corresponding JARs are found on the classpath.
To use (log4j2), the API and CORE JARs have to be found on the classpath. There's an XML configuration for log4j2 in the conf dir, which can be used e.g. via -Dlog4j.configurationFile=$JGROUPS/conf/log4j2.xml.
log4j2 is currently the preferred logging library used by JGroups, and will be used even if the log4j JAR is also present on the classpath.
To use (log4j), the log4j JAR has to be found on the classpath. Note though that if the log4j2 API and CORA JARs are found, then log4j2 will be used, so those JARs will have to be removed if log4j is to be used. There's an XML configuration for log4j in the conf dir, which can be used e.g. via -Dlog4j.configuration=file:$JGROUPS/conf/log4j.properties.
To force use of JDK logging, even if the log4j(2) JARs are present, -Djgroups.use.jdk_logger=true can be used.
JGroups allows custom loggers to be used instead of the ones supported by default. To do this, interface CustomLogFactory has to be implemented:
public interface CustomLogFactory {
Log getLog(Class clazz);
Log getLog(String category);
}
The implementation needs to return an implementation of org.jgroups.logging.Log.
To force using the custom log implementation, the fully qualified classname of the custom log factory has to be provided via -Djgroups.logging.log_factory_class=com.foo.MyCustomLogger.
To see whether your system can find the JGroups classes, execute the following command:
java org.jgroups.Version
or
java -jar jgroups-all.jar
You should see the following output (more or less) if the class is found:
$ java org.jgroups.Version
Version: 3.0.0.Beta1
To test whether JGroups works okay on your machine, run the following command twice:
java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw
2 whiteboard windows should appear as shown in Figure 2.1, “Screenshot of 2 Draw instances”.
If you started them simultaneously, they could initially show a membership of 1 in
their title bars. After some time, both windows should show 2. This means that the two instances found
each other and formed a cluster.
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 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 example 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.
State transfer (see the section in the API later) can also be tested by passing the -state flag to Draw.
If the 2 instances find each other and form a cluster, you can skip ahead to the next chapter ("Writing a simple application").
Sometimes there isn't a network connection (e.g. DSL modem is down), or we want to multicast only on the local machine. For this the loopback interface (typically lo) can be configured, e.g.
route add -net 224.0.0.0 netmask 240.0.0.0 dev lo
This means that all traffic directed to the 224.0.0.0
network will be sent to the loopback interface, which means it
doesn't need any network to be running. Note that the 224.0.0.0
network is a placeholder for all multicast addresses in most UNIX
implementations: it will catch
all multicast
traffic. This is an undocumented feature of
/sbin/route
and may not work across all UNIX
flavors. The above instructions may also work for Windows systems,
but this hasn't been tested. Note that not all systems allow
multicast traffic to use the loopback interface.
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).
Make sure your machine is set up correctly for IP multicast. There are 2 test programs that can be used to detect this: McastReceiverTest and McastSenderTest. Start McastReceiverTest, e.g.
java org.jgroups.tests.McastReceiverTest
Then start McastSenderTest:
java org.jgroups.tests.McastSenderTest
If you want to bind to a specific network interface card (NIC), use -bind_addr 192.168.0.2, where 192.168.0.2 is the IP address of the NIC to which you want to bind. Use this parameter in both sender and receiver.
You should be able to type in the McastSenderTest window and see the output in the McastReceiverTest. If not, try to use -ttl 32 in the sender. If this still fails, consult a system administrator to help you setup IP multicast correctly. If you are the system administrator, look for another job :-)
Other means of getting help: there is a public forum on JIRA for questions. Also consider subscribing to the javagroups-users mailing list to discuss such and other problems.
Another source of problems might be the use of IPv6, and/or misconfiguration of
/etc/hosts. If you
communicate between an IPv4 and an IPv6 host, and they are not
able to find each other, try the
-Djava.net.preferIP4Stack=true
property,
e.g.
java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw -props /home/bela/udp.xml
The JDK uses IPv6 by default, although is has a dual stack, that is, it also supports IPv4. Here's more details on the subject.
There is a wiki which lists FAQs and their solutions at http://www.jboss.org/wiki/Wiki.jsp?page=JGroups. It is frequently updated and a useful companion to this user's guide.
If you think that you discovered a bug, submit a bug report on JIRA or send email to the jgroups-users mailing list if you're unsure about it. Please include the following information:
Version of JGroups (java org.jgroups.Version)
Platform (e.g. Solaris 8)
Version of JDK (e.g. JDK 1.4.2_07)
Stack trace. Use kill -3 PID on UNIX systems or CTRL-BREAK on windows machines
Small program that reproduces the bug
JGroups project has been around since 1998. Over this time, some of the JGroups classes have been used in experimental phases and have never been matured enough to be used in today's production releases. However, they were not removed since some people used them in their products.
The following tables list unsupported and experimental classes. These classes are not actively maintained, and we will not work to resolve potential issues you might find. Their final faith is not yet determined; they might even be removed altogether in the next major release. Weight your risks if you decide to use them anyway.
Table 2.1. Experimental
| Package | Class |
|---|---|
| org.jgroups.util | HashedTimingWheel |
| org.jgroups.blocks | GridOutputStream |
| org.jgroups.blocks | GridInputStream |
| org.jgroups.blocks | GridFile |
| org.jgroups.blocks | ReplCache |
| org.jgroups.blocks | PartitionedHashMap |
| org.jgroups.blocks | Cache |
| org.jgroups.blocks | GridFilesystem |
| org.jgroups.client | StompConnection |
| org.jgroups.protocols | COUNTER |
| org.jgroups.protocols | STOMP |
| org.jgroups.protocols | TUNNEL |
| org.jgroups.protocols | BPING |
| org.jgroups.protocols | SHUFFLE |
| org.jgroups.protocols | SWIFT_PING |
| org.jgroups.protocols | TCP_NIO |
| org.jgroups.protocols | DAISYCHAIN |
| org.jgroups.protocols | PRIO |
| org.jgroups.protocols.tom | TOA |
| org.jgroups.protocols | RATE_LIMITER |
| org.jgroups.protocols | RSVP |
Table 2.2. Unsupported
| Package | Class |
|---|---|
| org.jgroups.util | HashedTimingWheel |
| org.jgroups.blocks | ReplicatedHashMap |
| org.jgroups.blocks | ReplCache |
| org.jgroups.blocks | ReplicatedTree |
| org.jgroups.blocks | PartitionedHashMap |
| org.jgroups.blocks | Cache |
| org.jgroups.protocols | DISCARD |
| org.jgroups.protocols | EXAMPLE |
| org.jgroups.protocols | HDRS |
| org.jgroups.protocols | FD_PING |
| org.jgroups.protocols | TCP_NIO |
| org.jgroups.protocols | DISCARD_PAYLOAD |