Permalink
Browse files

updating tutorial to 3.0

  • Loading branch information...
1 parent 2d30dba commit 5cae3166874e4b1c9468d329b4c262089ee7be9a Bela Ban committed Jul 21, 2011
Deleted file not rendered
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
@@ -8,8 +8,8 @@
<book>
<bookinfo>
- <title>JGroups tutorial</title>
- <pubdate>2009</pubdate>
+ <title>JGroups 3.x tutorial</title>
+ <pubdate>2011</pubdate>
<authorgroup>
<author>
<firstname>Bela</firstname>
@@ -29,7 +29,7 @@
<holder>Bela Ban</holder>
</copyright>
<copyright>
- <year>2006-2011</year>
+ <year>2006-2012</year>
<holder>Red Hat Inc</holder>
</copyright>
<legalnotice>
@@ -49,7 +49,7 @@
configure JGroups and how to write a simple application showing the major methods of the API.
</para>
- <para>Bela Ban, Kreuzlingen Switzerland August 2007</para>
+ <para>Bela Ban, Kreuzlingen, Switzerland August 2011</para>
</preface>
@@ -4,65 +4,23 @@
<section>
<title>Download</title>
<para>
- JGroups can be downloaded <ulink url="http://sourceforge.net/project/showfiles.php?group_id=6081">here</ulink>.
- For this tutorial, I'm using the binary version of JGroups 2.5, so the ZIP file to download is
- JGroups-2.5.0.bin.zip. <emphasis>Note that JGroups 2.5 requires JDK 1.5 or higher</emphasis>.
+ JGroups can be downloaded <ulink url="http://sourceforge.net/projects/javagroups/files/JGroups/">here</ulink>.
+ For this tutorial, I'm using the binary version of JGroups 3.0, so download one of the jgroups-3.x.y.jar
+ files (e.g. jgroups-3.0.0.Final.jar).
+ <emphasis>Note that JGroups 3.0 requires JDK 6</emphasis>.
</para>
<para>
- Unzip JGroups-2.5.0.bin.zip into a directory JGroups-2.5.0.bin. The contents of the directory are
- <figure id="BinaryContents">
- <title>Screenshot of the JGroups binary distribution</title>
- <graphic fileref="images/BinaryContents.png" format="PNG" align="center"/>
- </figure>
- </para>
-
- <para>
- The most important files are:
+ This JAR file contains:
<itemizedlist>
<listitem>
- jgroups.bat and jgroups.sh: scripts to run a JGroups application (including the correct JARs and
- XML files)
+ JGroups core, demo and (selected) test classes
</listitem>
<listitem>
INSTALL.html: detailed configuration instructions plus trouble shooting
</listitem>
<listitem>
- jgroups-all.jar (<emphasis>required</emphasis>): JGroups functionality, including demo and junit
- apps. If a smaller JAR is required, this can be done by downloading the source distribution and
- invoking the "jar" target, which creates a jgroups-core.jar file (ca 1MB).
- </listitem>
- <listitem>
- log4j.jar (optional): commons-logging can also use JDK logging
- </listitem>
- <listitem>
- Various XML file: different JGroups configurations, e.g.
- <itemizedlist>
- <listitem>
- mping.xml: TCP based stack with dynamic discovery
- </listitem>
- <listitem>
- sfc.xml: UDP (using IP multicasting) based stack with simple flow control
- </listitem>
- <listitem>
- tcp-nio.xml: TCP based stack with fixed configuration (list of nodes) using NIO (thread
- pool for all TCP connections)
- </listitem>
- <listitem>
- tcp-nio.xml: TCP based stack with fixed configuration (list of nodes) using plain TCP
- (1 thread / TCP connection)
- </listitem>
- <listitem>
- tcpgossip.xml: tunnel based configuration which routes messages to a remote
- GossipRouter, used to tunnel firewalls
- </listitem>
- <listitem>
- udp.xml: default IP multicast based configuration
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- config.txt: configuration file for performance tests
+ Sample configuration files, e.g. udp.xml or tcp.xml
</listitem>
</itemizedlist>
</para>
@@ -72,13 +30,9 @@
<section>
<title>Configuration</title>
<para>
- Add jgroups-all.jar to your CLASSPATH. If you use the log4j logging system, you also
+ Add jgroups-3.x.y.jar to your classpath. If you use the log4j logging system, you also
have to add log4j.jar (this is not necessary if you use the JDK logging system).
</para>
- <para>
- As an alternative, you can also use jgroups.bat. Note that jgroups.sh requires work, as it uses backslashes
- (developed under Cygwin/Windows), so it is currently not usable under UNIX as is.
- </para>
</section>
<section>
@@ -93,18 +47,16 @@
<para>or</para>
<screen>
- java -jar jgroups-all.jar
+ java -jar jgroups-3.x.y.jar
</screen>
<para>You should see the following output (more or less) if the
class is found:</para>
<screen>
- $ java -jar jgroups-all.jar
+ $ java org.jgroups.Version
- Version: 2.5.0
- CVS: $Id: installation.xml,v 1.4 2009/05/13 13:22:09 belaban Exp $
- History: (see doc/history.txt for details)
+ Version: 3.0.0.Beta1
</screen>
</section>
@@ -116,7 +68,7 @@
</para>
<screen>
- java org.jgroups.demos.Draw
+ java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw
</screen>
<para>2 whiteboard windows should appear as shown in <xref linkend="DrawScreenshotFig"/>.
@@ -127,13 +79,12 @@
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 group.</para>
+ each other and formed a cluster.</para>
- <para>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 sample won't work.
+ <para>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.
</para>
<para>
@@ -150,12 +101,11 @@
(You may skip this section if the 2 instances found each other correctly in the previous section).
</para>
- <para>Sometimes there isn't a network connection (e.g. DSL modem
- is down), or we want to multicast only on the local machine. To do
- this, we can use the loopback device (127.0.0.1):
+ <para>Sometimes there isn't a network connection (e.g. DSL modem is down), or we want to multicast only on the
+ local machine. To do this, we can use the loopback device (127.0.0.1):
</para>
<screen>
- java -Djgroups.bind_addr=127.0.0.1 org.jgroups.demos.Draw
+ java -Djgroups.bind_addr=127.0.0.1 -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw
</screen>
<para>
@@ -167,21 +117,16 @@
route add -net 224.0.0.0 netmask 240.0.0.0 dev lo
</screen>
- <para>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.
+ <para>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.
</para>
- <para>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).
+ <para>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).
</para>
</section>
@@ -200,9 +145,13 @@
<listitem>
Use of IPv6. JGroups does work with IPv6, but some JDK implementations still have issues with it, so
you can turn IPv6 off by passing the "-Djava.net.preferIPv4Stack=true" system property to the JVM.
+ You can force use of IPv6 addresses by using setting system property
+ -Djava.net.preferIPv6Addresses=true. If you use IPv6 addresses, you should also define IPv6 addresses
+ in your configuration; e.g. if you set bind_addr="192.168.1.5" in UDP, JGroups will try to pick
+ IPv4 addresses if an IPv4 stack is available, or you're running a dual stack.
</listitem>
<listitem>
- You don't use the right network interface (NIC): define the NIC with the jgroups.bind_addr system
+ You don't use the right network interface (NIC): define the NIC with the -Djgroups.bind_addr system
property:
<screen>
java -Djgroups.bind_addr=192.168.5.2 java.org.jgroups.demos.Draw

0 comments on commit 5cae316

Please sign in to comment.