libjgroups-java-2.12.2.Final.orig/ 0000755 0001750 0001750 00000000000 11647260573 016557 5 ustar moeller moeller libjgroups-java-2.12.2.Final.orig/.classpath 0000644 0001750 0001750 00000002003 11647260573 020535 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/.gitignore 0000644 0001750 0001750 00000000172 11647260573 020547 0 ustar moeller moeller *~
*.iws
*.ipr
*.iml
.project
.classpath
.idea/
.idea
classes/
build.properties
dist/
atlassian*
keystore/
tmp/
bla*.java
libjgroups-java-2.12.2.Final.orig/.project 0000644 0001750 0001750 00000000577 11647260573 020237 0 ustar moeller moeller
JGroupsorg.eclipse.jdt.core.javabuilderorg.eclipse.jdt.core.javanature
libjgroups-java-2.12.2.Final.orig/CREDITS 0000644 0001750 0001750 00000002415 11647260573 017601 0 ustar moeller moeller
Credits
-------
These are the people who contributed to JGroups (in chronological
order of contribution):
Bela Ban (bela@yahoo.com)
- Original author. Responsible for core, pbcast protocols
Gianluca Collot (gianluca@tin.it)
- Extended virtual synchrony, partitions and merging
John Georgiadis (i.georgiadis@doc.ic.ac.uk)
- Total order protocol (TOTAL)
Jim Menard (jimm@io.com)
- Trace module and makefiles
Filip Hanik (filip@filip.net)
- ANT based build system (./build)
- XML-based protocol stack configuration
- Class marshalling and magic number mapping (XML)
Vladimir Blagojevic (vladimir@cs.yorku.ca)
- Causal order protocol (CAUSAL)
- Token based total order protocol (TOTAL_TOKEN)
- FLUSH
- Streaming state transfer
Roman Rokytskyy (roman@gate5.de)
- JMS protocol
- JGroups Services (org.javagroups.service): locking/leasing
Ananda Bollu (akbollu@users.sf.net)
- FLOW_CONTROL protocol
Mandar Shinde (whizkid_bay@users.sf.net)
- Persistence manager (org.javagroups.persistence)
- Port to J2ME
Ovidiu Feodorov (ovidiuf@users.sourceforge.net)
- WAN capabilities, TUNNEL and Router
Robert Schaffar-Taurok (robert@fusion.at)
- Distributed lock manager
Chris Lott (chrislott@spamcop.net)
- Javadocs
Chris Mills (chris.mills@jboss.com)
- AUTH libjgroups-java-2.12.2.Final.orig/INSTALL.html 0000644 0001750 0001750 00000033776 11647260573 020573 0 ustar moeller moeller
JGroups 2.8.x Installation
Installation Instructions for JGroups
JGroups comes in a binary and a source version: the binary version
is JGroups-2.x.x.bin.zip, the source version is JGroups-2.x.x.src.zip
. The binary version contains the JGroups JAR file, plus a number of
JARs needed by JGroups. The source version contains all
source
files, plus several JAR files needed by JGroups, e.g. ANT to build
JGroups from source.
Requirements
JGroups 2.2.8 has a version that runs on JDK 1.3, and one that
requires 1.4 or higher.
From JGroups 2.2.9 on, the required JDK is 1.4 or higher. There
is no JNI code present so it should run on all platforms.
JGroups 2.5 requires JDK 5 or higher
An XML parser is required for configuration of JGroups 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 any other JAXP
compliant XML parser can
be used. This is only relevant for JDK 1.3; higher JDKs come with an
XML parser.
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
The binary version contains
jgroups-all.jar: the JGroups library including the demos
jgroups.bat/jgroups.sh: convenience script to start demo programs
(set the CLASSPATH etc) - see below
Some sample configuration files, udp.xml, mping.xml etc
CREDITS: list of contributors
INSTALL.html: this file
We no longer ship the Xerces JARs. To run JGroups you have to have an
XML parser installed on your system. If you use JDK 1.4, you can use
the parser that is shipped with it.
Place the JAR files somewhere in your CLASSPATH, and you're
ready to start using JGroups. If you already have Xerces installed, or
if you have another XML parser, the Xerces JARs can be omitted.
If you want to use the JGroups JMS protocol
(org.jgroups.protocols.JMS), then you will also need to place jms.jar
somewhere in your CLASSPATH.
Installing the source distribution
The source version consists of the following directories:
src: the sources
test: unit and stress tests
conf: configuration files needed by JGroups, plus default
protocol stack definitions
doc: documentation
lib: various JARs needed to build and run JGroups:
Ant JARs: used to
build JGroups. If you already have Ant installed, you won't need these
files
jms.jar: JMS library. Needed if you intend to run the
org.jgroups.protocols.JMS protocol
xalan.jar : to format the
output of the JUnit tests using an XSLT converter to HTML
log4j.jar
etc
Building JGroups (source distribution
only)
Unzip the source distribution, e.g. unzip JGroups-2.x.x.src.zip.
This will create the JGroups-2.x.x directory (root directory) under the
current directory.
cd to the root directory
Modify build.properties if you want to use a Java compiler other
than
javac (e.g. jikes)
On UNIX systems use build.sh, on Windows build.bat:
$> ./build.sh compile
This will compile all Java files (into the classes
directory).
To generate the JARs: $> ./build.sh jar
This will generate the following JAR files in the dist
directory:
jgroups-core.jar - the core JGroups libraries
jgroups-all.jar - the complete JGroups libraries
including demos and unit tests
The CLASSPATH now has to be set accordingly: the
following directories and/or JARs have to be included:
<JGroups rootdir>/classes
<JGroups rootdir>/conf
All needed JAR files in <JGroups rootdir>/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
javadoc and the Javadoc documentation will be generated in
the dist/javadoc directory
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.
combined: 5333.33 msgs/sec averaged over all receivers (throughput=5.33MB/sec)
Running a Demo Program
To test whether JGroups works okay on your machine, run
./jgroups.sh demos.Draw
twice (use jgroups.bat on Windows). 2 whiteboard windows should appear.
If you started them
simultaneously, they should 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.
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). For example, to use udp.xml, execute:
./jgroups.sh demos.Draw -props ./udp.xml
Using IP Multicasting without a network connection
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 224.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).
It doesn't work !
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.
You should be able to type in the McastSenderTest window and see the
output in the McastReceiverWindow. 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.
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:
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:
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:
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>;...)"
Problems with IPv6
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 java.net.preferIP4Stack=true
property, e.g.
JDK 1.4.1 uses IPv6 by default, although is has a dual stack, that
is,
it also supports IPv4. Here's more
details on the subject.
I have discovered a bug !
If you think that you discovered a bug, submit a bug report on JIRA or send email
to javagroups-developers 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
libjgroups-java-2.12.2.Final.orig/LICENSE 0000644 0001750 0001750 00000063476 11647260573 017604 0 ustar moeller moeller GNU LESSER GENERAL PUBLIC LICENSE
Version 2.1, February 1999
Copyright (C) 1991, 1999 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
[This is the first released version of the Lesser GPL. It also counts
as the successor of the GNU Library Public License, version 2, hence
the version number 2.1.]
Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software--to make sure the software is free for all its users.
This license, the Lesser General Public License, applies to some
specially designated software packages--typically libraries--of the
Free Software Foundation and other authors who decide to use it. You
can use it too, but we suggest you first think carefully about whether
this license or the ordinary General Public License is the better
strategy to use in any particular case, based on the explanations below.
When we speak of free software, we are referring to freedom of use,
not price. Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of
it in new free programs; and that you are informed that you can do
these things.
To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights. These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.
For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you. You must make sure that they, too, receive or can get the source
code. If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it. And you must show them these terms so they know their rights.
We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.
To protect each distributor, we want to make it very clear that
there is no warranty for the free library. Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.
Finally, software patents pose a constant threat to the existence of
any free program. We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder. Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.
Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License. This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License. We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.
When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library. The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom. The Lesser General
Public License permits more lax criteria for linking other code with
the library.
We call this license the "Lesser" General Public License because it
does Less to protect the user's freedom than the ordinary General
Public License. It also provides other free software developers Less
of an advantage over competing non-free programs. These disadvantages
are the reason we use the ordinary General Public License for many
libraries. However, the Lesser license provides advantages in certain
special circumstances.
For example, on rare occasions, there may be a special need to
encourage the widest possible use of a certain library, so that it becomes
a de-facto standard. To achieve this, non-free programs must be
allowed to use the library. A more frequent case is that a free
library does the same job as widely used non-free libraries. In this
case, there is little to gain by limiting the free library to free
software only, so we use the Lesser General Public License.
In other cases, permission to use a particular library in non-free
programs enables a greater number of people to use a large body of
free software. For example, permission to use the GNU C Library in
non-free programs enables many more people to use the whole GNU
operating system, as well as its variant, the GNU/Linux operating
system.
Although the Lesser General Public License is Less protective of the
users' freedom, it does ensure that the user of a program that is
linked with the Library has the freedom and the wherewithal to run
that program using a modified version of the Library.
The precise terms and conditions for copying, distribution and
modification follow. Pay close attention to the difference between a
"work based on the library" and a "work that uses the library". The
former contains code derived from the library, whereas the latter must
be combined with the library in order to run.
GNU LESSER GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
0. This License Agreement applies to any software library or other
program which contains a notice placed by the copyright holder or
other authorized party saying it may be distributed under the terms of
this Lesser General Public License (also called "this License").
Each licensee is addressed as "you".
A "library" means a collection of software functions and/or data
prepared so as to be conveniently linked with application programs
(which use some of those functions and data) to form executables.
The "Library", below, refers to any such software library or work
which has been distributed under these terms. A "work based on the
Library" means either the Library or any derivative work under
copyright law: that is to say, a work containing the Library or a
portion of it, either verbatim or with modifications and/or translated
straightforwardly into another language. (Hereinafter, translation is
included without limitation in the term "modification".)
"Source code" for a work means the preferred form of the work for
making modifications to it. For a library, complete source code means
all the source code for all modules it contains, plus any associated
interface definition files, plus the scripts used to control compilation
and installation of the library.
Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope. The act of
running a program using the Library is not restricted, and output from
such a program is covered only if its contents constitute a work based
on the Library (independent of the use of the Library in a tool for
writing it). Whether that is true depends on what the Library does
and what the program that uses the Library does.
1. You may copy and distribute verbatim copies of the Library's
complete source code as you receive it, in any medium, provided that
you conspicuously and appropriately publish on each copy an
appropriate copyright notice and disclaimer of warranty; keep intact
all the notices that refer to this License and to the absence of any
warranty; and distribute a copy of this License along with the
Library.
You may charge a fee for the physical act of transferring a copy,
and you may at your option offer warranty protection in exchange for a
fee.
2. You may modify your copy or copies of the Library or any portion
of it, thus forming a work based on the Library, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:
a) The modified work must itself be a software library.
b) You must cause the files modified to carry prominent notices
stating that you changed the files and the date of any change.
c) You must cause the whole of the work to be licensed at no
charge to all third parties under the terms of this License.
d) If a facility in the modified Library refers to a function or a
table of data to be supplied by an application program that uses
the facility, other than as an argument passed when the facility
is invoked, then you must make a good faith effort to ensure that,
in the event an application does not supply such function or
table, the facility still operates, and performs whatever part of
its purpose remains meaningful.
(For example, a function in a library to compute square roots has
a purpose that is entirely well-defined independent of the
application. Therefore, Subsection 2d requires that any
application-supplied function or table used by this function must
be optional: if the application does not supply it, the square
root function must still compute square roots.)
These requirements apply to the modified work as a whole. If
identifiable sections of that work are not derived from the Library,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works. But when you
distribute the same sections as part of a whole which is a work based
on the Library, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote
it.
Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Library.
In addition, mere aggregation of another work not based on the Library
with the Library (or with a work based on the Library) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public
License instead of this License to a given copy of the Library. To do
this, you must alter all the notices that refer to this License, so
that they refer to the ordinary GNU General Public License, version 2,
instead of to this License. (If a newer version than version 2 of the
ordinary GNU General Public License has appeared, then you can specify
that version instead if you wish.) Do not make any other change in
these notices.
Once this change is made in a given copy, it is irreversible for
that copy, so the ordinary GNU General Public License applies to all
subsequent copies and derivative works made from that copy.
This option is useful when you wish to copy part of the code of
the Library into a program that is not a library.
4. You may copy and distribute the Library (or a portion or
derivative of it, under Section 2) in object code or executable form
under the terms of Sections 1 and 2 above provided that you accompany
it with the complete corresponding machine-readable source code, which
must be distributed under the terms of Sections 1 and 2 above on a
medium customarily used for software interchange.
If distribution of object code is made by offering access to copy
from a designated place, then offering equivalent access to copy the
source code from the same place satisfies the requirement to
distribute the source code, even though third parties are not
compelled to copy the source along with the object code.
5. A program that contains no derivative of any portion of the
Library, but is designed to work with the Library by being compiled or
linked with it, is called a "work that uses the Library". Such a
work, in isolation, is not a derivative work of the Library, and
therefore falls outside the scope of this License.
However, linking a "work that uses the Library" with the Library
creates an executable that is a derivative of the Library (because it
contains portions of the Library), rather than a "work that uses the
library". The executable is therefore covered by this License.
Section 6 states terms for distribution of such executables.
When a "work that uses the Library" uses material from a header file
that is part of the Library, the object code for the work may be a
derivative work of the Library even though the source code is not.
Whether this is true is especially significant if the work can be
linked without the Library, or if the work is itself a library. The
threshold for this to be true is not precisely defined by law.
If such an object file uses only numerical parameters, data
structure layouts and accessors, and small macros and small inline
functions (ten lines or less in length), then the use of the object
file is unrestricted, regardless of whether it is legally a derivative
work. (Executables containing this object code plus portions of the
Library will still fall under Section 6.)
Otherwise, if the work is a derivative of the Library, you may
distribute the object code for the work under the terms of Section 6.
Any executables containing that work also fall under Section 6,
whether or not they are linked directly with the Library itself.
6. As an exception to the Sections above, you may also combine or
link a "work that uses the Library" with the Library to produce a
work containing portions of the Library, and distribute that work
under terms of your choice, provided that the terms permit
modification of the work for the customer's own use and reverse
engineering for debugging such modifications.
You must give prominent notice with each copy of the work that the
Library is used in it and that the Library and its use are covered by
this License. You must supply a copy of this License. If the work
during execution displays copyright notices, you must include the
copyright notice for the Library among them, as well as a reference
directing the user to the copy of this License. Also, you must do one
of these things:
a) Accompany the work with the complete corresponding
machine-readable source code for the Library including whatever
changes were used in the work (which must be distributed under
Sections 1 and 2 above); and, if the work is an executable linked
with the Library, with the complete machine-readable "work that
uses the Library", as object code and/or source code, so that the
user can modify the Library and then relink to produce a modified
executable containing the modified Library. (It is understood
that the user who changes the contents of definitions files in the
Library will not necessarily be able to recompile the application
to use the modified definitions.)
b) Use a suitable shared library mechanism for linking with the
Library. A suitable mechanism is one that (1) uses at run time a
copy of the library already present on the user's computer system,
rather than copying library functions into the executable, and (2)
will operate properly with a modified version of the library, if
the user installs one, as long as the modified version is
interface-compatible with the version that the work was made with.
c) Accompany the work with a written offer, valid for at
least three years, to give the same user the materials
specified in Subsection 6a, above, for a charge no more
than the cost of performing this distribution.
d) If distribution of the work is made by offering access to copy
from a designated place, offer equivalent access to copy the above
specified materials from the same place.
e) Verify that the user has already received a copy of these
materials or that you have already sent this user a copy.
For an executable, the required form of the "work that uses the
Library" must include any data and utility programs needed for
reproducing the executable from it. However, as a special exception,
the materials to be distributed need not include anything that is
normally distributed (in either source or binary form) with the major
components (compiler, kernel, and so on) of the operating system on
which the executable runs, unless that component itself accompanies
the executable.
It may happen that this requirement contradicts the license
restrictions of other proprietary libraries that do not normally
accompany the operating system. Such a contradiction means you cannot
use both them and the Library together in an executable that you
distribute.
7. You may place library facilities that are a work based on the
Library side-by-side in a single library together with other library
facilities not covered by this License, and distribute such a combined
library, provided that the separate distribution of the work based on
the Library and of the other library facilities is otherwise
permitted, and provided that you do these two things:
a) Accompany the combined library with a copy of the same work
based on the Library, uncombined with any other library
facilities. This must be distributed under the terms of the
Sections above.
b) Give prominent notice with the combined library of the fact
that part of it is a work based on the Library, and explaining
where to find the accompanying uncombined form of the same work.
8. You may not copy, modify, sublicense, link with, or distribute
the Library except as expressly provided under this License. Any
attempt otherwise to copy, modify, sublicense, link with, or
distribute the Library is void, and will automatically terminate your
rights under this License. However, parties who have received copies,
or rights, from you under this License will not have their licenses
terminated so long as such parties remain in full compliance.
9. You are not required to accept this License, since you have not
signed it. However, nothing else grants you permission to modify or
distribute the Library or its derivative works. These actions are
prohibited by law if you do not accept this License. Therefore, by
modifying or distributing the Library (or any work based on the
Library), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Library or works based on it.
10. Each time you redistribute the Library (or any work based on the
Library), the recipient automatically receives a license from the
original licensor to copy, distribute, link with or modify the Library
subject to these terms and conditions. You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties with
this License.
11. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Library at all. For example, if a patent
license would not permit royalty-free redistribution of the Library by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Library.
If any portion of this section is held invalid or unenforceable under any
particular circumstance, the balance of the section is intended to apply,
and the section as a whole is intended to apply in other circumstances.
It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system which is
implemented by public license practices. Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.
This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.
12. If the distribution and/or use of the Library is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Library under this License may add
an explicit geographical distribution limitation excluding those countries,
so that distribution is permitted only in or among countries not thus
excluded. In such case, this License incorporates the limitation as if
written in the body of this License.
13. The Free Software Foundation may publish revised and/or new
versions of the Lesser General Public License from time to time.
Such new versions will be similar in spirit to the present version,
but may differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Library
specifies a version number of this License which applies to it and
"any later version", you have the option of following the terms and
conditions either of that version or of any later version published by
the Free Software Foundation. If the Library does not specify a
license version number, you may choose any version ever published by
the Free Software Foundation.
14. If you wish to incorporate parts of the Library into other free
programs whose distribution conditions are incompatible with these,
write to the author to ask for permission. For software which is
copyrighted by the Free Software Foundation, write to the Free
Software Foundation; we sometimes make exceptions for this. Our
decision will be guided by the two goals of preserving the free status
of all derivatives of our free software and of promoting the sharing
and reuse of software generally.
NO WARRANTY
15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE LIBRARY "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE
LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Libraries
If you develop a new library, and you want it to be of the greatest
possible use to the public, we recommend making it free software that
everyone can redistribute and change. You can do so by permitting
redistribution under these terms (or, alternatively, under the terms of the
ordinary General Public License).
To apply these terms, attach the following notices to the library. It is
safest to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.
Copyright (C)
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Also add information on how to contact you by electronic and paper mail.
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the library, if
necessary. Here is a sample; alter the names:
Yoyodyne, Inc., hereby disclaims all copyright interest in the
library `Frob' (a library for tweaking knobs) written by James Random Hacker.
, 1 April 1990
Ty Coon, President of Vice
That's all there is to it!
libjgroups-java-2.12.2.Final.orig/README 0000755 0001750 0001750 00000005346 11647260573 017452 0 ustar moeller moeller
JGroups - A Framework for Group Communication in Java
========================================================
March 3, 1998
Bela Ban
4114 Upson Hall
Cornell University
Ithaca, NY 14853
bba@cs.cornell.edu
belaban@yahoo.com
JGroups is a Java library for reliable group communication. It
consists of 3 parts: (1) a socket-like API for application
development, (2) a protocol stack, which implements reliable
communication, and (3) a set of building blocks, which give the
developer high-level abstractions (e.g. ReplicatedHashMap, an
implementation of java.util.Map.
The API (a channel) looks like a socket: there are methods for joining
and leaving groups, sending and receiving messages,
getting the shared group state, and registering for notifications when
a member joins, or an existing member leaves or crashes.
The protocol stack is a list of protocols, through which each
message passes. Each protocol implements an up() and down()
method, and may modify, reorder, encrypt, fragment/unfragment, drop,
or pass a message up/down. The protocol stack is created
according to a specification given when a channel is created. New
protocols can be plugged into the stack easily.
Building blocks hide the channel and provide a higher abstraction.
Example: ReplicatedHashMap implements java.util.Mapand implements
all methods that change the map (clear(), put(), remove()).
Those methods are invoked on all hashmap instances in the same group
simultaneously, so that all hashmaps have the same state.
A new hashmap uses a state transfer protocol to initially obtain
the shared group state from an existing member. This allows for
replication of data structures across processes.
Group communication is important in the following situations:
- A service has to be replicated for availability. As long as at
least one of the servers remains operational, the service itself
remains operational
- Service requests have to be balanced between a set of servers
- A large number of objects have to be managed as one entity (e.g. a
management domain)
- Notification service / push technology: receivers subscribe to a
channel, senders send data to the channels, channels distribute
data to all receivers subscribed to the channel.
Used for example for video distribution, videoconferencing
JGroups deliberately models a rather low-level message-oriented
middleware (MOM) model. The reason is that we don't want to impose a
one-size-fits-all model on the programmer, who usually will want to
extend the model in various (previously unconceived) ways anyway.
Providing low level Java classes allows the programmer to
extend/replace classes at will, as the granularity of the system is
finer.
libjgroups-java-2.12.2.Final.orig/bin/ 0000755 0001750 0001750 00000000000 11647260573 017327 5 ustar moeller moeller libjgroups-java-2.12.2.Final.orig/bin/concurrent.sh 0000755 0001750 0001750 00000000367 11647260573 022056 0 ustar moeller moeller #!/bin/bash
count=0
while [ $count -lt 20 ]
do
echo "Starting Draw instance #$count"
# change the IP address to your system
jgroups.sh org.jgroups.demos.Draw -props /home/bela/udp.xml -name $count &
# sleep 1
count=$(($count+1))
done libjgroups-java-2.12.2.Final.orig/bin/draw.bat 0000644 0001750 0001750 00000002005 11647260573 020751 0 ustar moeller moeller @rem Convenience launcher for the Draw demo (contributed by Laran Evans lc278@cornell.edu)
@echo off
set CPATH=../classes;../conf;
set JAVA_OPTS=
if -debug==%1 set JAVA_OPTS=-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_shmem,server=y,suspend=y,address=jgc1
set PROPS=TUNNEL(router_host=localhost;router_port=5556)
set PROPS=%PROPS%:TCPGOSSIP(initial_hosts=localhost[5556];gossip_refresh_rate=10000;num_initial_members=3;up_thread=true;down_thread=true)
set PROPS=%PROPS%:MERGE2(min_interval=5000;max_interval=10000)
set PROPS=%PROPS%:FD_SOCK
set PROPS=%PROPS%:VERIFY_SUSPECT(timeout=1500)
set PROPS=%PROPS%:pbcast.NAKACK(gc_lag=50;retransmit_timeout=600,1200,2400,4800)
set PROPS=%PROPS%:UNICAST(timeout=600,1200,2400,4800)
set PROPS=%PROPS%:pbcast.STABLE(desired_avg_gossip=20000)
set PROPS=%PROPS%:FRAG(frag_size=8096;down_thread=false;up_thread=false)
set PROPS=%PROPS%:pbcast.GMS(join_timeout=5000;print_local_addr=true)
@echo on
java -classpath %CPATH% %JAVA_OPTS% org.jgroups.demos.Draw -props %PROPS%
libjgroups-java-2.12.2.Final.orig/bin/draw.sh 0000755 0001750 0001750 00000002304 11647260573 020622 0 ustar moeller moeller #!/bin/sh
#
# Convenience launcher for the Draw demo
#
SEP=":"
case "`uname`" in
CYGWIN*)
cygwin=true
SEP=";"
;;
Darwin*)
darwin=true
;;
esac
relpath=`dirname $0`
while [ "$1" != "" ]; do
if [ "$1" = "-debug" ]; then
debug=true
fi
shift
done
CLASSPATH="$relpath/../classes$SEP$relpath/../conf$SEP"
if [ "$debug" = "true" ]; then
JAVA_OPTS="-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_shmem,server=y,suspend=y,address=jgc1"
fi
PROPS="\
TUNNEL(router_host=localhost;router_port=5556):\
TCPGOSSIP(initial_hosts=localhost[5556];gossip_refresh_rate=10000;num_initial_members=3;up_thread=true;down_thread=true):\
MERGE2(min_interval=5000;max_interval=10000):\
FD_SOCK:\
VERIFY_SUSPECT(timeout=1500):\
pbcast.NAKACK(gc_lag=50;retransmit_timeout=600,1200,2400,4800):\
UNICAST(timeout=600,1200,2400,4800):\
pbcast.STABLE(desired_avg_gossip=20000):\
FRAG(frag_size=8096;down_thread=false;up_thread=false):\
pbcast.GMS(join_timeout=5000;print_local_addr=true)"
if [ "$cygwin" = "true" ]; then
CLASSPATH=`echo $CLASSPATH | sed -e 's/\;/\\\\;/g'`
fi
java -classpath $CLASSPATH $JAVA_OPTS org.jgroups.demos.Draw -props $PROPS $*
libjgroups-java-2.12.2.Final.orig/bin/gaps.sh 0000755 0001750 0001750 00000000060 11647260573 020614 0 ustar moeller moeller #!/bin/bash
java org.jgroups.tests.CheckGaps $*
libjgroups-java-2.12.2.Final.orig/bin/gossiprouter.sh 0000755 0001750 0001750 00000000752 11647260573 022437 0 ustar moeller moeller #!/bin/sh
CP=../classes:../conf
for i in ../lib/*.jar
do CP=$CP:$i
done
OPTS="-Dlog4j.configuration=file:$HOME/log4j.properties -Djava.net.preferIPv4Stack=true"
OPTS="$OPTS -Dcom.sun.management.jmxremote"
## Uncomment for remote JMX access. Also modify JAVA_HOME/jre/lib/management/jmxremote.passwords
# OPTS="$OPTS -Dcom.sun.management.jmxremote.port=7000 -Dcom.sun.management.jmxremote.ssl=false"
java $OPTS -classpath $CP $JAVA_OPTS org.jgroups.stack.GossipRouter -port 12001 $*
libjgroups-java-2.12.2.Final.orig/bin/jg 0000755 0001750 0001750 00000000123 11647260573 017651 0 ustar moeller moeller
# Author: Bela Ban
#!/bin/bash
JG=$HOME/JGroups
jgroups.sh org.jgroups.demos.$* libjgroups-java-2.12.2.Final.orig/bin/jgroups.bat 0000644 0001750 0001750 00000001670 11647260573 021514 0 ustar moeller moeller @echo off
REM ====================== Script to start JGroups programs ==============================
REM Usage: jgroups.bat demos.Draw -props c:\udp.xml
REM set the value of JG to the root directory in which JGroups is located
set JG=.
set LIB=%JG%
set CP=%JG%\classes\;%JG%\conf\;%LIB%\jgroups-all.jar\;%LIB%\log4j.jar\;%JG%\keystore
set VMFLAGS=-Xmx500M -Xms500M -XX:NewRatio=1 -XX:+AggressiveHeap -verbose:gc -XX:+DisableExplicitGC -XX:ThreadStackSize=32 -XX:CompileThreshold=100
rem LOG="-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.Jdk14Logger -Djava.util.logging.config.file=c:\logging.properties"
set LOG=-Dlog4j.configuration=file:c:\log4j.properties
set FLAGS=-Djava.net.preferIPv4Stack=true -Djgroups.bind_addr=192.168.1.5 -Djgroups.tcpping.initial_hosts=127.0.0.1[7800]
java -Ddisable_canonicalization=false -classpath %CP% %LOG% %VMFLAGS% %FLAGS% -Dcom.sun.management.jmxremote -Dresolve.dns=false org.jgroups.%*
libjgroups-java-2.12.2.Final.orig/bin/jgroups.sh 0000755 0001750 0001750 00000003002 11647260573 021352 0 ustar moeller moeller # Author: Bela Ban
#!/bin/bash
JG=${JG-$HOME/JGroups}
LIB=$JG/lib
CP=$JG/classes:$JG/conf
# If this is a bin dist, JARs are in the $JG directory.
if [ ! -d $LIB ]; then
LIB=$JG
fi;
for i in $LIB/*.jar
do
CP=$CP:$i
done
if [ -f $HOME/log4j.properties ]; then
LOG="-Dlog4j.configuration=file:$HOME/log4j.properties"
fi;
JG_FLAGS="-Dresolve.dns=false -Djgroups.bind_addr=$IP_ADDR -Djboss.tcpping.initial_hosts=$IP_ADDR[7800]"
JG_FLAGS="$JG_FLAGS -Djava.net.preferIPv4Stack=true -Djgroups.timer.num_threads=4"
FLAGS="-server -Xmx600M -Xms600M -Xmn500M -Xss128K"
FLAGS="$FLAGS -XX:CompileThreshold=10000 -XX:+AggressiveHeap -XX:ThreadStackSize=64K -XX:SurvivorRatio=8"
FLAGS="$FLAGS -XX:TargetSurvivorRatio=90 -XX:MaxTenuringThreshold=31"
FLAGS="$FLAGS -Xshare:off"
JMX="-Dcom.sun.management.jmxremote"
#EXPERIMENTAL="-XX:+UseFastAccessorMethods -XX:+UseTLAB"
#EXPERIMENTAL="$EXPERIMENTAL -XX:+DoEscapeAnalysis -XX:+EliminateLocks -XX:+UseBiasedLocking"
EXPERIMENTAL="$EXPERIMENTAL -XX:+EliminateLocks -XX:+UseBiasedLocking"
#EXPERIMENTAL="$EXPERIMENTAL -XX:+AggressiveOpts -XX:+DoEscapeAnalysis -XX:+EliminateLocks -XX:+UseBiasedLocking -XX:+UseCompressedOops"
#EXPERIMENTAL="$EXPERIMENTAL -XX:+UnlockExperimentalVMOptions -XX:+UseG1GC"
#java -Xrunhprof:cpu=samples,monitor=y,interval=5,lineno=y,thread=y -classpath $CP $LOG $JG_FLAGS $FLAGS $EXPERIMENTAL $JMX $*
#DEBUG="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5000"
java -classpath $CP $DEBUG $LOG $JG_FLAGS $FLAGS $EXPERIMENTAL $JMX $*
libjgroups-java-2.12.2.Final.orig/bin/jt 0000755 0001750 0001750 00000000123 11647260573 017666 0 ustar moeller moeller # Author: Bela Ban
#!/bin/bash
JG=$HOME/JGroups
jgroups.sh org.jgroups.tests.$* libjgroups-java-2.12.2.Final.orig/bin/probe.bat 0000644 0001750 0001750 00000000506 11647260573 021127 0 ustar moeller moeller @echo off
REM Discovers all UDP-based members running on a certain mcast address (use -help for help)
REM Probe [-help] [-addr ] [-port ] [-ttl ] [-timeout ]
set CLASSPATH=..\classes
set LIB=..\lib
set LIBS=%LIB%\log4j.jar;
set CP=%CLASSPATH%;%LIBS%
java -cp %CP% org.jgroups.tests.Probe %*
libjgroups-java-2.12.2.Final.orig/bin/probe.sh 0000755 0001750 0001750 00000001070 11647260573 020773 0 ustar moeller moeller #!/bin/sh
# Discovers all UDP-based members running on a certain mcast address (use -help for help)
# Probe [-help] [-addr ] [-port ] [-ttl ] [-timeout ]
BIN=`dirname $0`
LIB=$BIN/../lib
LIBS=$LIB/log4j.jar
#echo $CLASSPATH
CLASSPATH=$BIN/../classes:$CLASSPATH:$LIBS
# OS specific support (must be 'true' or 'false').
cygwin=false;
case "`uname`" in
CYGWIN*)
cygwin=true
;;
esac
if [ $cygwin = "true" ]; then
CP=`cygpath -wp $CLASSPATH`
else
CP=$CLASSPATH
fi
java -classpath $CP org.jgroups.tests.Probe $*
libjgroups-java-2.12.2.Final.orig/bin/release_to_local_repo.sh 0000755 0001750 0001750 00000001255 11647260573 024212 0 ustar moeller moeller #!/bin/bash
# Uploads the artifacts in ./dist (JAR and src JAR) to the local repo ($HOME/.ms/jboss-repository)
# so we can do local testing before uploading to the Nexus maven repo
# Author: Bela Ban
DIST=../dist
POM=../pom.xml
JAR=`find $DIST -name "jgroups-*.jar" | grep -v source`
SRC_JAR=`find $DIST -name "jgroups-*.jar" | grep source`
REPO=file:$HOME/.m2/jboss-repository
FLAGS="-Dpackaging=jar -DrepositoryId=jboss-releases-repository"
echo "Deploying $JAR to $REPO"
mvn deploy:deploy-file -Dfile=$JAR -Durl=$REPO -DpomFile=$POM $FLAGS
echo "Deploying $SRC_JAR to $REPO"
mvn deploy:deploy-file -Dfile=$SRC_JAR -Durl=$REPO -DpomFile=$POM -Dclassifier=sources $FLAGS
libjgroups-java-2.12.2.Final.orig/bin/release_to_nexus.sh 0000755 0001750 0001750 00000001434 11647260573 023234 0 ustar moeller moeller #!/bin/bash
# Uploads the artifacts in ./dist (JAR and src JAR) to the Nexus Maven repo at repository.jboss.org/nexus
# The artifacts will be in the staging repo, go to repository.jboss.org/nexus and promote them to the releases repo in
# the next step
# Author: Bela Ban
DIST=../dist
POM=../pom.xml
JAR=`find $DIST -name "jgroups-*.jar" | grep -v source`
SRC_JAR=`find $DIST -name "jgroups-*.jar" | grep source`
REPO=https://repository.jboss.org/nexus/service/local/staging/deploy/maven2
FLAGS="-Dpackaging=jar -DrepositoryId=jboss-releases-repository"
echo "Deploying $JAR to $REPO"
mvn deploy:deploy-file -Dfile=$JAR -Durl=$REPO -DpomFile=$POM $FLAGS
echo "Deploying $SRC_JAR to $REPO"
mvn deploy:deploy-file -Dfile=$SRC_JAR -Durl=$REPO -DpomFile=$POM -Dclassifier=sources $FLAGS
libjgroups-java-2.12.2.Final.orig/build.bat 0000644 0001750 0001750 00000001460 11647260573 020347 0 ustar moeller moeller
@echo off
REM This script assumes that tools.jar is already in the classpath
if "%JAVA_HOME%" == "" goto noJavaHome
set LIB=lib
set LIBS=%LIB%\log4j.jar
set LIBS=%LIB%\ant.jar;%LIB%\ant-junit.jar;%LIB%\ant-launcher.jar;%LIB%\junit.jar;%LIB%\xalan.jar;%LIB%\serializer.jar;
REM echo LIBS=%LIBS%
set CP=%JAVA_HOME%\lib\tools.jar;%JAVA_HOME%\jre\lib\rt.jar;%CLASSPATH%;%LIBS%
%JAVA_HOME%\bin\java -classpath "%CP%" org.apache.tools.ant.Main -buildfile build.xml %1 %2 %3 %4 %5 %6 %7 %8 %9
goto endOfFile
:noJavaHome
if "%_JAVACMD%" == "" set _JAVACMD=java
echo.
echo Warning: JAVA_HOME environment variable is not set.
echo If build fails because sun.* classes could not be found
echo you will need to set the JAVA_HOME environment variable
echo to the installation directory of java.
echo.
:endOfFile
libjgroups-java-2.12.2.Final.orig/build.properties.template 0000644 0001750 0001750 00000001076 11647260573 023612 0 ustar moeller moeller # add your own properties in here
# the network interface (NIC) which will be used by the unit tests, change this to
# the one you want to use. Note that 'localhost' usually resolved to 127.0.0.1,
# which may not work on Linux unless you have a multicast route set up for loopback
jgroups.bind_addr=localhost
jgroups.tcpping.initial_hosts=localhost[7800],localhost[7801]
jgroups.tunnel.gossip_router_hosts=localhost[12001]
jgroups.udp.mcast_addr=232.10.10.10
jgroups.udp.mcast_port=45588
jgroups.udp.ip_ttl=5
# use true for IPv6 and false for IPv4
jgroups.useIPv6=false
libjgroups-java-2.12.2.Final.orig/build.properties.template.ipv6 0000644 0001750 0001750 00000001262 11647260573 024472 0 ustar moeller moeller # Example of IPv6 based build.properties
# Replace the IPv6 addresses with your own
# the network interface (NIC) which will be used by the unit tests, change this to
# the one you want to use. Note that 'localhost' usually resolved to 127.0.0.1,
# which may not work on Linux unless you have a multicast route set up for loopback
jgroups.bind_addr=fe80::21b:21ff:fe07:a3b0%3
jgroups.tcpping.initial_hosts=fe80::21b:21ff:fe07:a3b0%3[7800],fe80::21b:21ff:fe07:a3b0%3[7801]
jgroups.tunnel.gossip_router_hosts=fe80::21b:21ff:fe07:a3b0%3[12001]
jgroups.udp.mcast_addr=ff0e::5:6:7
jgroups.udp.mcast_port=45588
jgroups.udp.ip_ttl=5
# use true for IPv6 and false for IPv4
jgroups.useIPv6=true
libjgroups-java-2.12.2.Final.orig/build.sh 0000755 0001750 0001750 00000002324 11647260573 020216 0 ustar moeller moeller #!/bin/sh
# Ant build script for the JGroups project
# The following variables have to be set in the following way
# PATH should include $JAVA_HOME/bin
JG_HOME=.
case "`uname`" in
CYGWIN*)
cygwin=true
;;
Darwin*)
darwin=true
;;
esac
LIB=lib
if [ "$cygwin" = "true" ]; then
for i in ${LIB}/*.jar
do
CP=${CP}${i}\;
done
else
for i in ${LIB}/*.jar
do
CP=${CP}${i}:
done
fi
if [ -n "$JAVA_HOME" ]; then
if [ -f "$JAVA_HOME/lib/tools.jar" ]; then
if [ "$cygwin" = "true" ]; then
CP=${CP}\;${JAVA_HOME}/lib/tools.jar
else
CP=${CP}:${JAVA_HOME}/lib/tools.jar
fi
fi
else
echo "WARNING: JAVA_HOME environment variable is not set."
echo " If build fails because sun.* classes could not be found"
echo " you will need to set the JAVA_HOME environment variable"
echo " to the installation directory of java."
fi
if [ -n "$JAVA_HOME" ]; then
${JAVA_HOME}/bin/java -classpath "${CP}" org.apache.tools.ant.Main -buildfile ${JG_HOME}/build.xml $*
else
java -classpath "${CP}" org.apache.tools.ant.Main -buildfile ${JG_HOME}/build.xml $*
fi
#echo "CP is ${CP}"
libjgroups-java-2.12.2.Final.orig/build.xml 0000644 0001750 0001750 00000053543 11647260573 020412 0 ustar moeller moeller
build.xml file for JGroups. Needs Ant (jakarta.apache.org) to run
libjgroups-java-2.12.2.Final.orig/conf/ 0000755 0001750 0001750 00000000000 11647260573 017504 5 ustar moeller moeller libjgroups-java-2.12.2.Final.orig/conf/EncryptKeyStore.xml 0000644 0001750 0001750 00000001075 11647260573 023343 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/EncryptNoKeyStore.xml 0000644 0001750 0001750 00000002253 11647260573 023637 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/auth_X509.xml 0000644 0001750 0001750 00000002210 11647260573 021707 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/auth_fixedlist.xml 0000644 0001750 0001750 00000002151 11647260573 023241 0 ustar moeller moeller libjgroups-java-2.12.2.Final.orig/conf/auth_md5.xml 0000644 0001750 0001750 00000002042 11647260573 021732 0 ustar moeller moeller libjgroups-java-2.12.2.Final.orig/conf/auth_regex.xml 0000644 0001750 0001750 00000006374 11647260573 022373 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/auth_simple.xml 0000644 0001750 0001750 00000001604 11647260573 022541 0 ustar moeller moeller libjgroups-java-2.12.2.Final.orig/conf/bare-bones.xml 0000644 0001750 0001750 00000001654 11647260573 022251 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/bsh.xml 0000644 0001750 0001750 00000002030 11647260573 020775 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/compress.xml 0000644 0001750 0001750 00000002475 11647260573 022071 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/config.txt 0000755 0001750 0001750 00000003476 11647260573 021527 0 ustar moeller moeller #
# This file contains configuration for the JGroups performance tests (org.jgroups.tests.perf package)
#
# Class implementing the org.jgroups.tests.perf.Transport interface
transport=org.jgroups.tests.perf.transports.JGroupsTransport
#transport=org.jgroups.tests.perf.transports.JGroupsClusterTransport
#transport=org.jgroups.tests.perf.transports.UdpTransport
#transport=org.jgroups.tests.perf.transports.TcpTransport
# Number of messages a sender multicasts
num_msgs=10000
# Message size in bytes.
msg_size=1000
# Expected number of group members.
num_members=2
# Number of senders in the group. Min 1, max num_members.
num_senders=2
# dump stats every n msgs
log_interval=1000
# number of ms to wait at the receiver to simulate delay caused by processing of the message
processing_delay=0
# Needs to either contain the full property string, or an URL pointing to a valid
# location (needs to be changed)
props=file:c:\\udp.xml
# Dumps statistics about the transport
dump_transport_stats=false
# Register JGroups channel and protocols with MBeanServer, don't terminate at the end
jmx=false
#####################################################
# These properties are only used by the UDP transport
#####################################################
bind_addr=localhost
mcast_addr=228.1.2.3
mcast_port=7500
############################
# only used by TCP Transport
############################
# List of hosts in the cluster. Since we don't specify ports, you cannot run multiple TcpTransports
# on the same machine: each ember has to be run on a separate machine (this may be changed in a next version)
cluster=127.0.0.1:7800,127.0.0.1:7801
start_port=7800
#################################################
# JNDI name of topic (only used by JMS transport)
#################################################
topic=topic/testTopic libjgroups-java-2.12.2.Final.orig/conf/encrypt-entire-message.xml 0000644 0001750 0001750 00000002325 11647260573 024622 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/encrypt.xml 0000644 0001750 0001750 00000002220 11647260573 021706 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/execution-service.xml 0000644 0001750 0001750 00000004740 11647260573 023674 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/fast-local.xml 0000644 0001750 0001750 00000005364 11647260573 022263 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/flush-tcp-nio.xml 0000644 0001750 0001750 00000005612 11647260573 022722 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/flush-tcp.xml 0000644 0001750 0001750 00000005144 11647260573 022137 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/flush-udp.xml 0000644 0001750 0001750 00000004366 11647260573 022146 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/gossip-service.xml 0000644 0001750 0001750 00000011552 11647260573 023174 0 ustar moeller moeller
JGroups GossipRouterorg.jgroups.stack.GossipRouterThe default constructorGossipRouterThe local TCP port.PortintThe local address the server will bind to.BindAddressjava.lang.StringTime (msec) until a cached gossip member entry expires.ExpiryTimelongNumber of millisecs the main thread waits to receive a gossip request after connection was established; upon expiration, the router initiates the routing protocol on the connection. Don't set the interval too big, otherwise the router will appear slow in answering routing requests.GossipRequestTimeoutlongTime (in ms) main thread waits for a router client to send the routing request type and the group afiliation before it declares the request failed.RoutingClientReplyTimeoutlongReturns true if the router is operational.StartedbooleanNot usedcreateThe start lifecycle operation. Brings the Router in fully functional state.startThe stop lifecycle operation. Close connections and frees resources.stopNot useddestroyDumps the routing table.dumpRoutingTablejava.lang.StringDumps the gossip table.dumpGossipTablejava.lang.String12000300001000120000
libjgroups-java-2.12.2.Final.orig/conf/jboss-service.xml 0000644 0001750 0001750 00000003573 11647260573 023014 0 ustar moeller moeller
jgroups:name=DemoChanneltruetruetrueDemoChannel
libjgroups-java-2.12.2.Final.orig/conf/jg-magic-map.xml 0000644 0001750 0001750 00000007256 11647260573 022471 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/jg-protocol-ids.xml 0000644 0001750 0001750 00000006775 11647260573 023261 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/log4j.properties 0000644 0001750 0001750 00000002310 11647260573 022635 0 ustar moeller moeller
## Root logger
log4j.rootLogger=warn,console
## ConsoleAapender
log4j.appender.console=org.apache.log4j.ConsoleAppender
log4j.appender.console.Follow=true
# File appender
log4j.appender.file=org.apache.log4j.RollingFileAppender
log4j.appender.file.File=dump.log
log4j.appender.file.MaxFileSize=100KB
# Keep one backup file
log4j.appender.file.MaxBackupIndex=1
# log everything
#log4j.logger.org.jgroups=DEBUG
# trace only the protocols
#log4j.logger.org.jgroups.protocols=INFO
log4j.logger.org.jgroups=warn
log4j.logger.org.jgroups.protocols.pbcast.FLUSH=DEBUG
log4j.logger.org.jgroups.protocols.MERGE2=DEBUG
#log4j.logger.org.jgroups.protocols.pbcast.GMS=WARN
#log4j.additivity.org.jgroups.protocols.pbcast.STABLE=false
## Layout for the console appender
log4j.appender.console.layout=org.apache.log4j.PatternLayout
#log4j.appender.console.layout.ConversionPattern=%-7d{HH:mm:ss,SSS} [%p] %c: %m%n
log4j.appender.console.layout.ConversionPattern=%r [%p] %c{1}: - %m%n
## Layout for the file appender
log4j.appender.file.layout=org.apache.log4j.PatternLayout
#log4j.appender.file.layout.ConversionPattern=%-7d{HH:mm:ss,SSS} [%p] %c: %m%n
log4j.appender.file.layout.ConversionPattern=%r [%p] %c{1}: - %m%n
libjgroups-java-2.12.2.Final.orig/conf/manifest.mf 0000644 0001750 0001750 00000000167 11647260573 021642 0 ustar moeller moeller Manifest-Version: 1.0
Created-By: Apache Ant 1.6.5
Main-Class: org.jgroups.Version
Implementation-Version: 2.12.2.Final libjgroups-java-2.12.2.Final.orig/conf/mping.xml 0000644 0001750 0001750 00000002560 11647260573 021343 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/multiplexer-service.xml 0000644 0001750 0001750 00000001244 11647260573 024237 0 ustar moeller moeller
jgroups.muxstacks.xmltruetrue
libjgroups-java-2.12.2.Final.orig/conf/multiplexer-xmbean.xml 0000644 0001750 0001750 00000011224 11647260573 024050 0 ustar moeller moeller
JGroups Multiplexerorg.jgroups.jmx.JChannelFactoryThe default constructorJChannelFactoryThe domain which is used as prefix for all channels and protocols exposed via JMXDomainjava.lang.StringThe file used for configuration. If this is not an absolute pathname, it will need to be found on the classpathMultiplexerConfigjava.lang.StringWhether or not to expose channels via JMXExposeChannelsbooleanWhether or not to expose protocols via JMX (if true, will set ExposeChannels to true too)ExposeProtocolsbooleanThe create() life cycle operationcreateThe start lifecycle operation.startThe stop lifecycle operation.stopThe destroy() life cycle operationdestroyDumps the channelsdumpChannelsjava.lang.StringDumps the configurationdumpConfigurationjava.lang.StringcreateMultiplexerChannelThe name of the stack, as defined e.g. in stacks.xmlstack_namejava.lang.StringThe application ID, all IDs need to be unique across a Multiplexeridjava.lang.StringWhether this application wants to register for state transfer, getState() will only return when *all* registered listeners called itregister_for_state_transferbooleanThe ID of the substate to be retrieved (or null)substate_idjava.lang.Stringorg.jgroups.ChannelcreateMultiplexerChannelThe name of the stack, as defined e.g. in stacks.xmlstack_namejava.lang.StringThe application ID, all IDs need to be unique across a Multiplexeridjava.lang.Stringorg.jgroups.Channel
libjgroups-java-2.12.2.Final.orig/conf/performancetestconfig.txt 0000644 0001750 0001750 00000002562 11647260573 024641 0 ustar moeller moeller # Author: Vladimir Blagojevic
# Version: $Id$
#This file is used as an input for org.jgroups.tests.perf.PerformanceTestGenerator
#utility. PerformanceTestGenerator, given this input file with -config flag, then
#in turn generates test files that are used in conjunction with
#bin/clusterperfromancetest.sh. The number of test files generated is
#number_of_senders*message_sizes. Each test file represents one performance
#round. In each performance round JGroups cluster is formed and tests are
#executed using org.jgroups.tests.perf.Test utility.
#
#Configuration parameters are:
#
# - nodes: number of group member nodes (machines) used in the performance test
# - total_data: total size of data in bytes
# - number_of_sender: specifies how many nodes will be senders in each test
# - message_sizes: specifies message size used in each test
# - interval: log after interval messages
#
#
#Number of machines used for performance tests. This value should match number
#of computer nodes listed in CLUSTER_NODES variable of bin/clusterperformancetests.sh
nodes=8
#Total combined amount of data in bytes sent by all senders in a perfromance test round
total_data=200000000
#Number of senders in each performance round
number_of_senders=1,4,8
#Message size in bytes for each performance round
message_sizes=100,1000,10000,100000
#Log after receiving interval messages
interval=100000 libjgroups-java-2.12.2.Final.orig/conf/persist.properties 0000644 0001750 0001750 00000002126 11647260573 023314 0 ustar moeller moeller #choice for persist variable is DB or FILE
persist=DB
#========================================================
#fill these properties for DB persistence to work
#========================================================
# this is the string to create the table
# choose one of the options
#----------------------------------------------------
# hsql
#jdbc.table = create table replhashmap(key varchar, keybin varbinary, valbin varbinary)
# oracle
jdbc.table = create table replhashmap(key varchar2(100), keybin blob, valbin blob)
# Db2 and other
#jdbc.table = create table replhashmap(key varchar(100), keybin blob, valbin blob)
# insert other
#jdbc.table =
#--------------------- end of table create string
# Db related properties
jdbc.User =
jdbc.Pass =
jdbc.Conn =
jdbc.Driver =
#================ end of DB properties
#========================================================
# File-based PersistenceManager
#========================================================
# The class that implements the file-based PersistenceManager
# (default is FiledPersistenceManager)
# filePersistMgr = libjgroups-java-2.12.2.Final.orig/conf/sequencer.xml 0000644 0001750 0001750 00000004653 11647260573 022230 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/settings.xml 0000644 0001750 0001750 00000006025 11647260573 022071 0 ustar moeller moeller
/home/bela/.m2/jboss-repositoryjboss-releases-repositoryUSERNAMEPASSWORDjboss-public-repositoryjboss-public-repository-groupJBoss Public Maven Repository Grouphttps://repository.jboss.org/nexus/content/groups/public/defaulttruenevertrueneverjboss-public-repository-groupJBoss Public Maven Repository Grouphttps://repository.jboss.org/nexus/content/groups/public/defaulttruenevertrueneverjboss-deprecated-repositoryjboss-deprecated-repositoryJBoss Deprecated Maven Repositoryhttps://repository.jboss.org/nexus/content/repositories/deprecated/defaulttrueneverfalseneverjboss-public-repository
libjgroups-java-2.12.2.Final.orig/conf/sfc.xml 0000644 0001750 0001750 00000004362 11647260573 021006 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/smack.xml 0000644 0001750 0001750 00000001575 11647260573 021334 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/smack_tunnel.xml 0000644 0001750 0001750 00000001141 11647260573 022706 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/stacks.xml 0000644 0001750 0001750 00000041111 11647260573 021514 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/tcp-nio.xml 0000644 0001750 0001750 00000005530 11647260573 021602 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/tcp.xml 0000644 0001750 0001750 00000005362 11647260573 021022 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/tcp_nio.xml 0000644 0001750 0001750 00000005777 11647260573 021701 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/tcpgossip.xml 0000644 0001750 0001750 00000004101 11647260573 022235 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/testng/ 0000755 0001750 0001750 00000000000 11647260573 021010 5 ustar moeller moeller libjgroups-java-2.12.2.Final.orig/conf/testng/functional.xml 0000644 0001750 0001750 00000001211 11647260573 023667 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/testng/stack-independent.xml 0000644 0001750 0001750 00000001324 11647260573 025132 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/testng/testng-tcp-flush.xml 0000644 0001750 0001750 00000001645 11647260573 024747 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/testng/testng-tcp-stress.xml 0000644 0001750 0001750 00000001076 11647260573 025147 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/testng/testng-tcp.xml 0000644 0001750 0001750 00000001516 11647260573 023625 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/testng/testng-udp-flush.xml 0000644 0001750 0001750 00000001633 11647260573 024746 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/testng/testng-udp.xml 0000644 0001750 0001750 00000001463 11647260573 023630 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/testng/time-sensitive.xml 0000644 0001750 0001750 00000001224 11647260573 024476 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/tunnel.xml 0000644 0001750 0001750 00000002541 11647260573 021535 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/udp-largecluster.xml 0000644 0001750 0001750 00000005423 11647260573 023514 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/conf/udp.xml 0000644 0001750 0001750 00000005050 11647260573 021016 0 ustar moeller moeller
libjgroups-java-2.12.2.Final.orig/doc/ 0000755 0001750 0001750 00000000000 11647260573 017324 5 ustar moeller moeller libjgroups-java-2.12.2.Final.orig/doc/ENCRYPT.html 0000644 0001750 0001750 00000023576 11647260573 021353 0 ustar moeller moeller
Encryption Protocol Document
(Author : Steve Woodcock)
Introduction
The encryption protocol provides encryption of messages in JGroups that are generated by applications.
There are a few requirements in order to make use of the Encryption layer.
A suitable Security provider is required. (see security provider instructions later)
The java.security properties need to be configured (see installation guide).
The Encrypt layer can be used in one of two ways (the options are mutually exclusive so all participants in a JGroup must have the same settings).
Option 1. Configured with a secretKey in a keystore so it can be used at any
layer in JGroups without the need for a coordinator, or if you want protection against passive
monitoring but do not want the key exchange overhead and complexity. In this mode all nodes must be distributed with
the same keystore file. Due to issues with Sun's JCE you cannot use this option with JDK1.3
Option 2. Configured with only algorithms and key sizes. The Encrypt Layer in this mode should be used between the
FRAG and PBCast layers in the stack. The coordinator chooses the
secretkey which it distributes amongst all the peers. In this form no keystore exists as the keys are
the key is generated and distributed by the controller using a public/private key exchange. View changes that identify a new controller will result in a new session key
being generated and then distributed to all peers. This overhead can be substantial in a an application with
a reasonable peer churn.
Installation
The following steps need to be followed to make sure that ENCRYPT protocol can be used
Installing a Security Provider
First you need to download an appropriate security provider. A good option is an organisation called bouncycastle, who
provide an open-source clean room implementation of the JCE. You can find them at www.bouncycastle.org.
You must download the correct jar file for the JDK you are using - at the time of writing
the 1.3 version is: jce-jdk13-124.jar and the 1.4 version is: bcprov-jdk14-124.jar.
You do not have to use the bouncycastle provider - others available include those from Phaos Technology,
RSA and Wedgetail Communications. See the appropriate documentation for each provider.
If you are using 1.3 you must also install the SUN JCE provider (current version 1.2.2) to give access to the JCEKS keystore
formats. This can be downloaded from the www.javasoft.com site. The following instructions are for JDK1.3 and 1.4.
Assuming $JAVA_HOME to be the JDK the installation root.
JDK 1.3
Download the SunJCE file.
Unzip the file and place the jar files contained in the jce/lib folder in the
$JAVA_HOME/jre/lib/ext directory
Place the bouncycastle provider in the $JAVA_HOME/jre/lib/ext directory.
Next configure the security file to add the new providers.
Open the java.security file in $JAVA_HOME/jre/lib/security.
Search for security.provider.{list} in the opened file.
Add the SunJCE provider as provider 2, and
add the bouncycastle provider as the last.
You should end up with the entries similar to that shown below.
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.crypto.provider.SunJCE
security.provider.3=com.sun.rsajca.Provider
security.provider.4=org.bouncycastle.jce.provider.BouncyCastleProvider
JDK 1.4
The JDK1.4 already includes the SunJCE files, so you only need to configure the bouncycastle provider.
Place the bouncycastle provider in the $JAVA_HOME/jre/lib/ext directory.
Next configure the security file to add the new providers.
Open the java.security file in $JAVA_HOME/jre/lib/security.
Search for security.provider.{list} in the opened file.
Add the bouncycastle provider as the last.
You should end up with similar entries as shown below.
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
security.provider.3=com.sun.rsajca.Provider
security.provider.4=com.sun.crypto.provider.SunJCE
security.provider.5=sun.security.jgss.SunProvider
security.provider.6=org.bouncycastle.jce.provider.BouncyCastleProvider
Configure the Encrypt Protocol
Option 1 - Using a shared keystore (JDK1.4 Only)
This is the simplest option and can be used by simply inserting the Encryption layer
at any point in the JGroup stack - it will encrypt all Events of a type MSG that
have a non-null message buffer. The format of the JGroup XML entry in this form is:
An example bare-bones.xml file showing the keystore version can be found in the conf
directory in a file called EncryptKeyStore.xml - you will need to generate a keystore - see the KeyStoreGenerator file in the demo directory or use the makeKeystore target in the build file.
In order to use the Encrypt layer in this manner it is necessary to have the secretKey already generated
in a keystore file. The directory containing the keystore file must be on the application's classpath.
You cannot create a SecretKey keystore file using the keytool application shipped with the JDK.
A java file called KeyStoreGenerator is included in the demo
package that can be used from the command line (or IDE) to generate a suitable keystore.
IMPORTANT- A keystore generated under each version of the 1.4 JDK can be incompatible with other JDK versions.
Make sure you generate the keystore with the same JDK version as you are going to use at runtime. This is important for 1.4.2_04 and 1.4.2_05.
Option 2 - Dynamic Key Generation (JDK1.3/1.4)
This option is suited to an application that does not ship with a shared key but instead it is generated
and distributed by the controller. The secret key is first generated by the Controller (in JGroup terms). When a view change
occurs a peer will request the secret key by sending a key request with its own public key. The controller
encrypts the secret key with this key and sends it back to the peer who then decrypts it and installs the
key as its own secret key.
All encryption and decryption of Messages is done using this key. When a peer receives
a view change that shows a different keyserver it will repeat this process - the view change event
also trigger the encrypt layer to queue up and down messages until the new key is installed.
The previous keys are retained so that messages sent before the view change that are queued can be decrypted
if the key is different.
An example EncryptNoKeyStore.xml is included in the conf directory as a guide.
Note: the current version does not support the concept of perfect forward encryption (PFE)
which means that if a peer leaves the group, the keys are re-generated preventing the departed peer from
decrypting future messages if it chooses to listen in on the group. This is not included as it really requires
a suitable authentication scheme as well to make this feature useful as there is nothing to stop the peer rejoining and receiving the new
key. A future release will address this issue.
Demo
To test the usage of the protocol use any demo and change the xml config file to include the encrypt protocol.
Starting up an application using the keystore option will result in an output similar to:
04-Aug-2004 21:11:38 org.jgroups.protocols.ENCRYPT setProperties
INFO: key_store_name used is defaultStore1_4.keystore
04-Aug-2004 21:11:38 org.jgroups.protocols.ENCRYPT setProperties
INFO: store_password used is not null
04-Aug-2004 21:11:39 org.jgroups.protocols.ENCRYPT setProperties
INFO: key_password used is same as store_password
04-Aug-2004 21:11:39 org.jgroups.protocols.ENCRYPT setProperties
INFO: alias used is myKey
04-Aug-2004 21:11:39 org.jgroups.protocols.ENCRYPT initSymCiphers
INFO: Initializing symmetric ciphers
04-Aug-2004 21:11:39 org.jgroups.protocols.ENCRYPT initSymCiphers
INFO: Initialized symmetric ciphers with secret key version �;ٺ�8=fԱ;qe2�
If you want to confirm the encryption/decryption messages then set the logging level to debug
for the protocol.
If you are using the encryption without a keystore you should see output similar to:
05-Aug-2004 13:43:52 org.jgroups.protocols.ENCRYPT initSymKey
INFO: Symmetric key generated
05-Aug-2004 13:43:53 org.jgroups.protocols.ENCRYPT initKeyPair
INFO: asym algo initialized
05-Aug-2004 13:43:53 org.jgroups.protocols.ENCRYPT initSymCiphers
INFO: Initializing symmetric ciphers
05-Aug-2004 13:43:53 org.jgroups.protocols.ENCRYPT initSymCiphers
INFO: Initialized symmetric ciphers with secret key version �~6��Ɨ/h%ڤĹ
................
Later in the output you should see logging identifying that the JGroups peer has become the
keyServer - this will be the same peer that is the group coordinator.
05-Aug-2004 13:43:55 org.jgroups.protocols.ENCRYPT up
INFO: handling view change event
05-Aug-2004 13:43:55 org.jgroups.protocols.ENCRYPT becomeKeyServer
INFO: I have become key server
Note: the key version is an MD5 hash of the key in an encoded form from which you cannot get
the original key data.
libjgroups-java-2.12.2.Final.orig/doc/ENCRYPT1_4.html 0000644 0001750 0001750 00000015043 11647260573 021645 0 ustar moeller moeller
Encryption Protocol Document
(Author : Mandar Shinde)
Introduction
This document is required to be read by both the developers and the users.
The
ENCRYPT protocol will not work by directly compiling the javagroups
source
and then using the required "encrypt.xml" file. Since an external provider
needs
to be used (JDK1.4 does not provider for RSA as of now), hence this
provider
needs to be added to the users/developers security list.
Installation
The following steps need to be followed to make sure that ENCRYPT protocol
can ne used
Make sure that JDK1.4 is installed, ENCRYPT will not work with any other
version under JDK1.4.
After installation JDK1.4, set $JAVA_HOME to the installation root.
cd $JAVA_HOME/jre/lib/security. Open java.security file.
Search for security.provider.{list} in the opened file.
At the end of the list addProvider.{list+1}=org.bouncycastle.jce.provider.BouncyCastleProvider.
The above provider is the default provider that comes along with Javagroups;
users can use their own providers by adding the right provider jars in
the classpath
and adding the provider to the required list.
The encrypt.xml file is the default configuration on top of default.xml.
Any stack can use the Encrypt protocol by adding this stack below GMS.
<protocol>
<protocol-name> Encryption Protocol </protocol-name>
<description> Protocol provides encryption to all communication </description>
<class-name>org.jgroups.protocols.ENCRYPT1_4</class-name>
<protocol-params>
<protocol-param name="asymInit" value="512"/>
<protocol-param name="symInit" value="56"/>
<protocol-param name="asymAlgorithm" value="RSA"/>
<protocol-param name="symAlgorithm" value="DES/ECB/PKCS5Padding"/>
</protocol-params>
</protocol>
Demo
To test the usage of the protocol use any demo; I have used the Draw demo
for this purpose;.
First up uncomment the Print protocol and comment the Encrypt protocol
from the
encrypt.xml file. When the Draw demo is used, the user will see the deserialized
messages being exchanged between the 2 members.
Now, uncomment the Encrypt protocol (leave the Print Protocol intact)
from the protocol
stack. Run the same demo as above; the user will see that an ioexception
will thrown while
deserializing the message because it has been encrypted by the Encrypt
protocol.
How does Encrypt protocol work ?
The mechanism used by this protocol is the oldest know way for high performing
peer communication
protocols. To understand the working a couple algos need to be
detailed; these are very basic in
today's encryption world.
Asymmetric algo: this algo uses a set of keys; a public-keyand a private-key. The public-key is
public; it is published to the public. The private-key is known
only to the entity which makes the
public-key available. Any other entity will encrypt a message
using the former public-key and the
former will decrypt the message using the
private-key. Symmetric algo: this algo is the simplest known where a set
of communication peers know a single
shared secret-key(private-key) and ecrypt/decrypt
messages to communicate with each other.
Final algo : It is obvious that the asym algo seems more powerful
than the symm algo. But, the asym
algorithm is very expensive and the symm algorithm has a basic fault
on how to distribute the key. A
combination where the asym algo is used only for handshake and distribute
the shared key is the best bet.
Only when a member leaves does it require to re-generate a shared key.
Step-by-Step
The first-member in the group becomes the admin and generates the
shared-key.
When a new peer requests to join, the new-member publishes its public-key.
Using the public-key the admin encodes its shared-key.
Using its own private-key, client decodes the shared-key.
New member lets the admin know, it is ready.
Members use shared-key to encrypt/decrypt messages.
When member leaves, admin regeneratesshared-key. If admin
leaves, another member becomes admin
and regenerates key.
Attributes of thread poolsNameDescriptionenabledWhether of not to use a thread pool. If set to false, the caller's thread
is used.min_threadsThe minimum number of threads to use.max_threadsThe maximum number of threads to use.keep_alive_timeNumber of milliseconds until an idle thread is removed from the poolqueue_enabledWhether of not to use a (bounded) queue. If enabled, when all minimum
threads are busy, work items are added to the queue. When the queue is full,
additional threads are created, up to max_threads. When max_threads have been
reached, the rejection policy is consulted.max_sizeThe maximum number of elements in the queue. Ignored if the queue is
disabledrejection_policyDetermines what happens when the thread pool (and queue, if enabled) is
full. The default is to run on the caller's thread. "Abort" throws an runtime
exception. "Discard" discards the message, "DiscardOldest" discards the
oldest entry in the queue. Note that these values might change, for example a
"Wait" value might get added in the future.thread_naming_patternDetermines how threads are named that are running from thread pools in
concurrent stack. Valid values include any combination of "cl" letters, where
"c" includes the cluster name and "l" includes local address of the channel.
The default is "cl"
Elimination of up and down threads
By removing the 2 queues/protocol and the associated 2 threads, we effectively reduce the number of
threads needed to handle a message, and thus context switching overhead. We also get clear and unambiguous
semantics for Channel.send(): now, all messages are sent down the stack on the caller's thread and
the send() call only returns once the message has been put on the network. In addition, an exception will
only be propagated back to the caller if the message has not yet been placed in a retransmit buffer.
Otherwise, JGroups simply logs the error message but keeps retransmitting the message. Therefore,
if the caller gets an exception, the message should be re-sent.
On the receiving side, a message is handled by a thread pool, either the regular or OOB thread pool. Both
thread pools can be completely eliminated, so that we can save even more threads and thus further
reduce context switching. The point is that the developer is now able to control the threading behavior
almost completely.
Concurrent message delivery
Up to version 2.5, all messages received were processed by a single thread, even if the messages were
sent by different senders. For instance, if sender A sent messages 1,2 and 3, and B sent message 34 and 45,
and if A's messages were all received first, then B's messages 34 and 35 could only be processed after
messages 1-3 from A were processed !
Now, we can process messages from different senders in parallel, e.g. messages 1, 2 and 3 from A can be
processed by one thread from the thread pool and messages 34 and 35 from B can be processed on a different
thread.
As a result, we get a speedup of almost N for a cluster of N if every node is sending messages and we
configure the thread pool to have at least N threads. There is actually a unit test
(ConcurrentStackTest.java) which demonstrates this.
Scopes: concurrent message delivery for messages from the same sender
In the previous paragraph, we showed how the concurrent stack delivers messages from different senders
concurrently. But all (non-OOB) messages from the same sender P are delivered in the order in which
P sent them. However, this is not good enough for certain types of applications.
Consider the case of an application which replicates HTTP sessions. If we have sessions X, Y and Z, then
updates to these sessions are delivered in the order in which there were performed, e.g. X1, X2, X3,
Y1, Z1, Z2, Z3, Y2, Y3, X4. This means that update Y1 has to wait until updates X1-3 have been delivered.
If these updates take some time, e.g. spent in lock acquisition or deserialization, then all subsequent
messages are delayed by the sum of the times taken by the messages ahead of them in the delivery order.
However, in most cases, updates to different web sessions should be completely unrelated, so they could
be delivered concurrently. For instance, a modification to session X should not have any effect on
session Y, therefore updates to X, Y and Z can be delivered concurrently.
One solution to this is out-of-band (OOB) messages (see next paragraph). However, OOB messages do not
guarantee ordering, so updates X1-3 could be delivered as X1, X3, X2. If this is not wanted, but
messages pertaining to a given web session should all be delivered concurrently between sessions, but
ordered within a given session, then we can resort to scoped messages.
Scoped messages apply only to regular (non-OOB) messages, and are delivered
concurrently between scopes, but ordered within a given scope. For example, if we used the sessions above
(e.g. the jsessionid) as scopes, then the delivery could be as follows ('->' means sequential, '||' means concurrent):
X1 -> X2 -> X3 -> X4 || Y1 -> Y2 -> Y3 || Z1 -> Z2 -> Z3
This means that all updates to X are delivered in parallel to updates to Y and updates to Z. However, within
a given scope, updates are delivered in the order in which they were performed, so X1 is delivered before
X2, which is deliverd before X3 and so on.
Taking the above example, using scoped messages, update Y1 does not have to wait for
updates X1-3 to complete, but is processed immediately.
To set the scope of a message, use method Message.setScope(short).
Scopes are implemented in a separate protocol called . This protocol
has to be placed somewhere above ordering protocols like UNICAST or NAKACK (or SEQUENCER for that matter).
Uniqueness of scopes
Note that scopes should be as unique as possible. Compare this to hashing: the fewer collisions
there are, the better the concurrency will be. So, if for example, two web sessions pick the same
scope, then updates to those sessions will be delivered in the order in which they were sent, and
not concurrently. While this doesn't cause erraneous behavior, it defies the purpose of SCOPE.
Also note that, if multicast and unicast messages have the same scope, they will be delivered
in sequence. So if A multicasts messages to the group with scope 25, and A also unicasts messages
to B with scope 25, then A's multicasts and unicasts will be delivered in order at B ! Again,
this is correct, but since multicasts and unicasts are unrelated, might slow down things !
Out-of-band messages
OOB messages completely ignore any ordering constraints the stack might have. Any message marked as OOB
will be processed by the OOB thread pool. This is necessary in cases where we don't want the message
processing to wait until all other messages from the same sender have been processed, e.g. in the
heartbeat case: if sender P sends 5 messages and then a response to a heartbeat request received from
some other node, then the time taken to process P's 5 messages might take longer than the heartbeat
timeout, so that P might get falsely suspected ! However, if the heartbeat response is marked as OOB,
then it will get processed by the OOB thread pool and therefore might be concurrent to its previously
sent 5 messages and not trigger a false suspicion.
The 2 unit tests UNICAST_OOB_Test and NAKACK_OOB_Test demonstrate how OOB messages influence the ordering,
for both unicast and multicast messages.
Replacing the default and OOB thread pools
In 2.7, there are 3 thread pools and 4 thread factories in TP:
Thread pools and factories in TPNameDescriptionDefault thread poolThis is the pools for handling incoming messages. It can be fetched using
getDefaultThreadPool() and replaced using setDefaultThreadPool(). When setting a
thread pool, the old thread pool (if any) will be shutdown and all of it tasks
cancelled first
OOB thread poolThis is the pool for handling incoming OOB messages. Methods to get and set
it are getOOBThreadPool() and setOOBThreadPool()Timer thread poolThis is the thread pool for the timer. The max number of threads is set through
the timer.num_threads property. The timer thread pool cannot be set, it can only
be retrieved using getTimer(). However, the thread factory of the timer
can be replaced (see below)Default thread factoryThis is the thread factory (org.jgroups.util.ThreadFactory) of the default
thread pool, which handles incoming messages. A thread pool factory is used to
name threads and possibly make them daemons.
It can be accessed using
getDefaultThreadPoolThreadFactory() and setDefaultThreadPoolThreadFactory()OOB thread factoryThis is the thread factory for the OOB thread pool. It can be retrieved
using getOOBThreadPoolThreadFactory() and set using method
setOOBThreadPoolThreadFactory()Timer thread factoryThis is the thread factory for the timer thread pool. It can be accessed
using getTimerThreadFactory() and setTimerThreadFactory()Global thread factoryThe global thread factory can get used (e.g. by protocols) to create threads
which don't live in the transport, e.g. the FD_SOCK server socket handler thread.
Each protocol has a method getTransport(). Once the TP is obtained, getThreadFactory()
can be called to get the global thread factory. The global thread factory
can be replaced with setThreadFactory()
Sharing of thread pools between channels in the same JVM
In 2.7, the default and OOB thread pools can be shared between instances running inside the same JVM. The
advantage here is that multiple channels running within the same JVM can pool (and therefore save) threads.
The disadvantage is that thread naming will not show to which channel instance an incoming thread
belongs to.
Note that we can not just shared thread pools between JChannels within the same JVM, but we can also
share entire transports. For details see this section.
MiscShunning
Note that in 2.8, shunning has been removed, so the sections below only apply to versions up to 2.7.
Let's say we have 4 members in a group: {A,B,C,D}. When a member (say D) is expelled from the group, e.g.
because it didn't respond to are-you-alive messages, and later comes back, then it is shunned. Shunning
causes a member to leave the group and re-join, if this is enabled on the Channel. To enable automatic
re-connects, the AUTO_RECONNECT option has to be set on the Channel:
channel.setOpt(Channel.AUTO_RECONNECT, Boolean.TRUE);
To enable shunning, set FD.shun and GMS.shun to true.
Let's look at a more detailed example. Say member D is overloaded, and doesn't respond to are-you-alive
messages (done by the failure detection (FD) protocol). It is therefore suspected and excluded. The new
view for A, B and C will be {A,B,C}, however for D the view is still {A,B,C,D}. So when D comes back and
sends messages to the group, or any individiual member, those messages will be discarded, because A,B and
C don't see D in their view. D is shunned when A,B or C receive an are-you-alive message from D, or D
shuns itself when it receives a view which doesn't include D.
So shunning is always a unilateral decision. However, things may be different if all members exclude each
other from the group. For example, say we have a switch connecting A, B, C and D. If someone pulls all
plugs on the switch, or powers the switch down, then A, B, C and D will all form singleton groups, that is,
each member thinks it's the only member in the group. When the switch goes back to normal, then each member
will shun everybody else (a real shun fest :-)). This is clearly not desirable, so in this case shunning
should be turned off:
<FD timeout="2000" max_tries="3" shun="false"/>
...
<pbcast.GMS join_timeout="3000" shun="false"/>
Using a custom socket factory
JGroups creates all of its sockets through a SocketFactory, which is located in the transport (TP) or
TP.ProtocolAdapter (in a shared transport). The factory has methods to create sockets (Socket,
ServerSocket, DatagramSocket and MulticastSocket)
Currently, SocketFactory does not support creation of NIO sockets / channels.
,
closen sockets and list all open sockets. Every socket creation method has a service name, which could
be for example "jgroups.fd_sock.srv_sock". The service name is used to look up a port (e.g. in a config
file) and create the correct socket.
To provide one's own socket factory, the following has to be done: if we have a non-shared transport,
the code below creates a SocketFactory implementation and sets it in the transport:
JChannel ch;
MySocketFactory factory; // e.g. extends DefaultSocketFactory
ch=new JChannel("config.xml");
ch.setSocketFactory(new MySocketFactory());
ch.connect("demo");
If a shared transport is used, then we have to set 2 socket factories: 1 in the shared transport and
one in the TP.ProtocolAdapter:
JChannel c1=new JChannel("config.xml"), c2=new JChannel("config.xml");
TP transport=c1.getProtocolStack().getTransport();
transport.setSocketFactory(new MySocketFactory("transport"));
c1.setSocketFactory(new MySocketFactory("first-cluster"));
c2.setSocketFactory(new MySocketFactory("second-cluster"));
c1.connect("first-cluster");
c2.connect("second-cluster");
First, we grab one of the channels to fetch the transport and set a SocketFactory in it. Then we
set one SocketFactory per channel that resides on the shared transport. When JChannel.connect() is
called, the SocketFactory will be set in TP.ProtocolAdapter.
Handling network partitions
Network partitions can be caused by switch, router or network interface crashes, among other things. If we
have a cluster {A,B,C,D,E} spread across 2 subnets {A,B,C} and {D,E} and the switch to which D and E are
connected crashes, then we end up with a network partition, with subclusters {A,B,C} and {D,E}.
A, B and C can ping each other, but not D or E, and vice versa. We now have 2 coordinators, A and D. Both
subclusters operate independently, for example, if we maintain a shared state, subcluster {A,B,C} replicate
changes to A, B and C.
This means, that if during the partition, some clients access {A,B,C}, and others {D,E}, then we end up
with different states in both subclusters. When a partition heals, the merge protocol (e.g. MERGE2) will
notify A and D that there were 2 subclusters and merge them back into {A,B,C,D,E}, with A being the new
coordinator and D ceasing to be coordinator.
The question is what happens with the 2 diverged substates ?
There are 2 solutions to merging substates: first we can attempt to create a new state from the 2 substates,
and secondly we can shut down all members of the non primary partition, such that they
have to re-join and possibly reacquire the state from a member in the primary partition.
In both cases, the application has to handle a MergeView (subclass of View), as shown in the code below:
public void viewAccepted(View view) {
if(view instanceof MergeView) {
MergeView tmp=(MergeView)view;
Vector<View> subgroups=tmp.getSubgroups();
// merge state or determine primary partition
// run this in a separate thread !
}
}
It is essential that the merge view handling code run on a separate thread if it needs more than a few
milliseconds, or else it would block the calling thread.
The MergeView contains a list of views, each view represents a subgroups and has the list of members which
formed this group.
Merging substates
The application has to merge the substates from the various subgroups ({A,B,C} and {D,E}) back into one
single state for {A,B,C,D,E}. This task has to be done by the application because
JGroups knows nothing about the application state, other than it is a byte buffer.
If the in-memory state is backed by a database, then the solution is easy: simply discard the in-memory
state and fetch it (eagerly or lazily) from the DB again. This of course assumes that the members of
the 2 subgroups were able to write their changes to the DB. However, this is often not the case, as
connectivity to the DB might have been severed by the network partition.
Another solution could involve tagging the state with time stamps. On merging, we could compare the
time stamps for the substates and let the substate with the more recent time stamps win.
Yet another solution could increase a counter for a state each time the state has been modified. The state
with the highest counter wins.
Again, the merging of state can only be done by the application. Whatever algorithm is picked to merge
state, it has to be deterministic.
The primary partition approach
The primary partition approach is simple: on merging, one subgroup is designated as the
primary partition and all others as non-primary partitions. The members in the primary
partition don't do anything, whereas the members in the non-primary partitions need to drop their state and
re-initialize their state from fresh state obtained from a member of the primary partition.
The code to find the primary partition needs to be deterministic, so that all members pick the
same primary partition. This could be for example the first view in the MergeView, or we could
sort all members of the new MergeView and pick the subgroup which contained the new coordinator (the one
from the consolidated MergeView). Another possible solution could be to pick the largest subgroup, and, if
there is a tie, sort the tied views lexicographically (all Addresses have a compareTo() method) and pick the
subgroup with the lowest ranked member.
Here's code which picks as primary partition the first view in the MergeView, then re-acquires the state from
the new coordinator of the combined view:
public static void main(String[] args) throws Exception {
final JChannel ch=new JChannel("/home/bela/udp.xml");
ch.setReceiver(new ExtendedReceiverAdapter() {
public void viewAccepted(View new_view) {
handleView(ch, new_view);
}
});
ch.connect("x");
while(ch.isConnected())
Util.sleep(5000);
}
private static void handleView(JChannel ch, View new_view) {
if(new_view instanceof MergeView) {
ViewHandler handler=new ViewHandler(ch, (MergeView)new_view);
// requires separate thread as we don't want to block JGroups
handler.start();
}
}
private static class ViewHandler extends Thread {
JChannel ch;
MergeView view;
private ViewHandler(JChannel ch, MergeView view) {
this.ch=ch;
this.view=view;
}
public void run() {
Vector<View> subgroups=view.getSubgroups();
View tmp_view=subgroups.firstElement(); // picks the first
Address local_addr=ch.getLocalAddress();
if(!tmp_view.getMembers().contains(local_addr)) {
System.out.println("Not member of the new primary partition ("
+ tmp_view + "), will re-acquire the state");
try {
ch.getState(null, 30000);
}
catch(Exception ex) {
}
}
else {
System.out.println("Not member of the new primary partition ("
+ tmp_view + "), will do nothing");
}
}
}
The handleView() method is called from viewAccepted(), which is called whenever there is a new view. It spawns
a new thread which gets the subgroups from the MergeView, and picks the first subgroup to be the primary
partition. Then, if it was a member of the primary partition, it does nothing, and if not, it reaqcuires
the state from the coordinator of the primary partition (A).
The downside to the primary partition approach is that work (= state changes) on the non-primary partition
is discarded on merging. However, that's only problematic if the data was purely in-memory data, and not
backed by persistent storage. If the latter's the case, use state merging discussed above.
It would be simpler to shut down the non-primary partition as soon as the network partition is detected, but
that a non trivial problem, as we don't know whether {D,E} simply crashed, or whether they're still alive,
but were partitioned away by the crash of a switch. This is called a split brain syndrome,
and means that none of the members has enough information to determine whether it is in the primary or
non-primary partition, by simply exchanging messages.
The Split Brain syndrome and primary partitions
In certain situations, we can avoid having multiple subgroups where every subgroup is able to make
progress, and on merging having to discard state of the non-primary partitions.
If we have a fixed membership, e.g. the cluster always consists of 5 nodes, then we can run code on
a view reception that determines the primary partition. This code
assumes that the primary partition has to have at least 3 nodesany cluster which has less than 3 nodes doesn't accept modfications. This could be done for
shared state for example, by simply making the {D,E} partition read-only. Clients can access the
{D,E} partition and read state, but not modify it.
As an alternative, clusters without at least 3 members could shut down, so in this case D and
E would leave the cluster.
The algorithm is shown in pseudo code below:
On initialization:
- Mark the node as read-only
On view change V:
- If V has >= N members:
- If not read-write: get state from coord and switch to read-write
- Else: switch to read-only
Of course, the above mechanism requires that at least 3 nodes are up at any given time, so upgrades have
to be done in a staggered way, taking only one node down at a time. In the worst case, however, this
mechanism leaves the cluster read-only and notifies a system admin, who can fix the issue. This is still
better than shutting the entire cluster down.
Flushing: making sure every node in the cluster received a message
When sending messages, the properties of the default stacks (udp.xml, tcp.xml) are that all messages are delivered
reliably to all (non-crashed) members. However, there are no guarantees with respect to the view in which a message
will get delivered. For example, when a member A with view V1={A,B,C} multicasts message M1 to the group and D joins
at about the same time, then D may or may not receive M1, and there is no guarantee that A, B and C receive M1 in
V1 or V2={A,B,C,D}.
To change this, we can turn on virtual synchrony (by adding FLUSH to the top of the stack), which guarantees that
A message M sent in V1 will be delivered in V1. So, in the example above, M1 would get delivered in
view V1; by A, B and C, but not by D.
The set of messages seen by members in V1 is the same for all members before a new view V2 is installed.
This is important, as it ensures that all members in a given view see the same messages. For example,
in a group {A,B,C}, C sends 5 messages. A receives all 5 messages, but B doesn't. Now C crashes before
it can retransmit the messages to B. FLUSH will now ensure, that before installing V2={A,B} (excluding
C), B gets C's 5 messages. This is done through the flush protocol, which has all members reconcile
their messages before a new view is installed. In this case, A will send C's 5 messages to B.
Sometimes it is important to know that every node in the cluster received all messages up to a certain point,
even if there is no new view being installed. To do this (initiate a manual flush), an application programmer
can call Channel.startFlush() to start a flush and Channel.stopFlush() to terminate it.
Channel.startFlush() flushes all pending messages out of the system. This stops all senders (calling
Channel.down() during a flush will block until the flush has completed)Note that block()
will be called in a Receiver when the flush is about to start and unblock() will be called when it ends.
When startFlush() returns, the caller knows that (a) no messages will get sent anymore until stopFlush() is
called and (b) all members have received all messages sent before startFlush() was called.
Channel.stopFlush() terminates the flush protocol, no blocked senders can resume sending messages.
Note that the FLUSH protocol has to be present on top of the stack, or else the flush will fail.
Large clusters
This section is a collection of best practices and tips and tricks for running large clusters on JGroups.
By large clusters, we mean several hundred nodes in a cluster.
Reducing chattiness
When we have a chatty protocol, scaling to a large number of nodes might be a problem: too many messages
are sent and - because they are generated in addition to the regular traffic - this can have a
negative impact on the cluster. A possible impact is that more of the regular messages are dropped, and
have to be retransmitted, which impacts performance. Or heartbeats are dropped, leading to false
suspicions. So while the negative effects of chatty protocols may not be seen in small clusters, they
will be seen in large clusters !
Discovery
A discovery protocol (e.g. PING, TCPPING, MPING etc) is run at startup, to discover the initial
membership, and periodically by the merge protocol, to detect partitioned subclusters.
When we send a multicast discovery request to a large cluster, every node in the cluster might
possibly reply with a discovery response sent back to the sender. So, in a cluster of 300 nodes,
the discovery requester might be up to 299 discovery responses ! Even worse, because num_ping_requests
in Discovery is by default set to 2, so we're sending 2 discovery requests, we might receive up to
num_ping_requests * (N-1) discovery responses, even though we might be able to find out the
coordinator after a few responses already !
To reduce the large number of responses, we can set a max_rank property: the value defines which
members are going to send a discovery response. The rank is the index of a member in a cluster: in
{A,B,C,D,E}, A's index is 1, B's index is 2 and so on. A max_rank of 3 would trigger discovery
responses from only A, B and C, but not from D or E.
We highly recommend setting max_rank in large clusters.
This functionality was implemented in
https://jira.jboss.org/browse/JGRP-1181.
Failure detection protocols
Failure detection protocols determine when a member is unresponsive, and subsequently
suspect it. Usually (FD, FD_ALL), messages (heartbeats) are used to determine
the health of a member, but we can also use TCP connections (FD_SOCK) to connect to a member P, and
suspect P when the connection is closed.
Heartbeating requires messages to be sent around, and we need to be careful to limit the number of
messages sent by a failure detection protocol (1) to detect crashed members and (2) when a member
has been suspected. The following sections discuss how to configure FD_ALL and FD_SOCK, the most
commonly used failure detection protocols, for use in large clusters.
FD_SOCKFD_ALLBridging between remote clusters
In 2.12, the RELAY protocol was added to JGroups (for the properties see RELAY).
It allows for bridging of remote clusters. For example, if we have a cluster in New York (NYC) and another
one in San Francisco (SFO), then RELAY allows us to bridge NYC and SFO, so that multicast messages sent in
NYC will be forwarded to SFO and vice versa.
The NYC and SFO clusters could for example use IP multicasting (UDP as transport), and the bridge could use
TCP as transport. The SFO and NYC clusters don't even need to use the same cluster name.
shows how the two clusters are bridged.
Relaying between different clusters
The cluster on the left side with nodes A (the coordinator), B and C is called "NYC" and use IP
multicasting (UDP as transport). The cluster on the right side ("SFO") has nodes D (coordinator), E and F.
The bridge between the local clusters NYC and SFO is essentially another cluster with the coordinators
(A and D) of the local clusters as members. The bridge typically uses TCP as transport, but any of the
supported JGroups transports could be used (including UDP, if supported across a WAN, for instance).
Only a coordinator relays traffic between the local and remote cluster. When A crashes or leaves, then the
next-in-line (B) takes over and starts relaying.
Relaying is done via the RELAY protocol added to the top of the stack. The bridge is configured with
the bridge_props property, e.g. bridge_props="/home/bela/tcp.xml". This creates a JChannel inside RELAY.
Note that property "site" must be set in both subclusters. In the example above, we could set site="nyc"
for the NYC subcluster and site="sfo" for the SFO ubcluster.
The design is described in detail in JGroups/doc/design/RELAY.txt (part of the source distribution). In
a nutshell, multicast messages received in a local cluster are wrapped and forwarded to the remote cluster
by a relay (= the coordinator of a local cluster). When a remote cluster receives such a message, it is
unwrapped and put onto the local cluster.
JGroups uses subclasses of UUID (PayloadUUID) to ship the site name with an address. When we see an address
with site="nyc" on the SFO side, then RELAY will forward the message to the SFO subcluster, and vice versa.
When C multicasts a message in the NYC cluster, A will forward it to D, which will re-broadcast the message on
its local cluster, with the sender being D. This means that the sender of the local broadcast will appear
as D (so all retransmit requests got to D), but the original sender C is preserved in the header.
At the RELAY protocol, the sender will be replaced with the original sender (C) having site="nyc".
When node F wants to reply to the sender of the multicast, the destination
of the message will be C, which is intercepted by the RELAY protocol and forwarded to the current
relay (D). D then picks the correct destination (C) and sends the message to the remote cluster, where
A makes sure C (the original sender) receives it.
An important design goal of RELAY is to be able to have completely autonomous clusters, so NYC doesn't for
example have to block waiting for credits from SFO, or a node in the SFO cluster doesn't have to ask a node
in NYC for retransmission of a missing message.
Views
RELAY presents a global view to the application, e.g. a view received by
nodes could be {D,E,F,A,B,C}. This view is the same on all nodes, and a global view is generated by
taking the two local views, e.g. A|5 {A,B,C} and D|2 {D,E,F}, comparing the coordinators' addresses
(the UUIDs for A and D) and concatenating the views into a list. So if D's UUID is greater than
A's UUID, we first add D's members into the global view ({D,E,F}), and then A's members.
Therefore, we'll always see all of A's members, followed by all of D's members, or the other way round.
To see which nodes are local and which ones remote, we can iterate through the addresses (PayloadUUID)
and use the site (PayloadUUID.getPayload()) name to for example differentiate between "nyc" and "sfo".
Configuration
To setup a relay, we need essentially 3 XML configuration files: 2 to configure the local clusters and
1 for the bridge.
To configure the first local cluster, we can copy udp.xml from the JGroups distribution and add RELAY on top
of it: <RELAY bridge_props="/home/bela/tcp.xml" />. Let's say we call this config relay.xml.
The second local cluster can be configured by copying relay.xml to relay2.xml. Then change the
mcast_addr and/or mcast_port, so we actually have 2 different cluster in case we run instances of
both clusters in the same network. Of course, if the nodes of one cluster are run in a different
network from the nodes of the other cluster, and they cannot talk to each other, then we can simply
use the same configuration.
The 'site' property needs to be configured in relay.xml and relay2.xml, and it has to be different. For
example, relay.xml could use site="nyc" and relay2.xml could use site="sfo".
The bridge is configured by taking the stock tcp.xml and making sure both local clusters can see each
other through TCP.
Daisychaining
Daisychaining refers to a way of disseminating messages sent to the entire cluster.
The idea behind it is that it is inefficient to broadcast a message in clusters where IP multicasting is
not available. For example, if we only have TCP available (as is the case in most clouds today), then we
have to send a broadcast (or group) message N-1 times. If we want to broadcast M to a cluster of 10,
we send the same message 9 times.
Example: if we have {A,B,C,D,E,F}, and A broadcasts M, then it sends it to B, then to C, then to D etc.
If we have a 1 GB switch, and M is 1GB, then sending a broadcast to 9 members takes 9 seconds, even if we
parallelize the sending of M. This is due to the fact that the link to the switch only sustains 1GB / sec.
(Note that I'm conveniently ignoring the fact that the switch will start dropping packets if it is
overloaded, causing TCP to retransmit, slowing things down)...
Let's introduce the concept of a round. A round is the time it takes to send or receive a message.
In the above example, a round takes 1 second if we send 1 GB messages.
In the existing N-1 approach, it takes X * (N-1) rounds to send X messages to a cluster of N nodes.
So to broadcast 10 messages a the cluster of 10, it takes 90 rounds.
Enter DAISYCHAIN.
The idea is that, instead of sending a message to N-1 members, we only send it to our neighbor, which
forwards it to its neighbor, and so on. For example, in {A,B,C,D,E}, D would broadcast a message by
forwarding it to E, E forwards it to A, A to B, B to C and C to D. We use a time-to-live field,
which gets decremented on every forward, and a message gets discarded when the time-to-live is 0.
The advantage is that, instead of taxing the link between a member and the switch to send N-1 messages,
we distribute the traffic more evenly across the links between the nodes and the switch.
Let's take a look at an example, where A broadcasts messages m1 and m2 in
cluster {A,B,C,D}, '-->' means sending:
Traditional N-1 approachRound 1: A(m1) --> BRound 2: A(m1) --> CRound 3: A(m1) --> DRound 4: A(m2) --> BRound 5: A(m2) --> CRound 6: A(m2) --> D
It takes 6 rounds to broadcast m1 and m2 to the cluster.
Daisychaining approachRound 1: A(m1) --> BRound 2: A(m2) --> B || B(m1) --> CRound 3: B(m2) --> C || C(m1) --> DRound 4: C(m2) --> DIn round 1, A send m1 to B.In round 2, A sends m2 to B, but B also forwards m1 (received in round 1) to C.In round 3, A is done. B forwards m2 to C and C forwards m1 to D (in parallel, denoted by '||').In round 4, C forwards m2 to D.Switch usage
Let's take a look at this in terms of switch usage: in the N-1 approach, A can only send 125MB/sec,
no matter how many members there are in the cluster, so it is constrained by the link capacity to the
switch. (Note that A can also receive 125MB/sec in parallel with today's full duplex links).
So the link between A and the switch gets hot.
In the daisychaining approach, link usage is more even: if we look for example at round 2, A sending
to B and B sending to C uses 2 different links, so there are no constraints regarding capacity of a
link. The same goes for B sending to C and C sending to D.
In terms of rounds, the daisy chaining approach uses X + (N-2) rounds, so for a cluster size of 10 and
broadcasting 10 messages, it requires only 18 rounds, compared to 90 for the N-1 approach !
Performance
To measure performance of DAISYCHAIN, a performance test (test.Perf) was run, with 4 nodes connected
to a 1 GB switch; and every node sending 1 million 8K messages, for a total of 32GB received by
every node. The config used was tcp.xml.
The N-1 approach yielded a throughput of 73 MB/node/sec, and the daisy chaining approach 107MB/node/sec !
Configuration
DAISYCHAIN can be placed directly on top of the transport, regardless of whether it is UDP or TCP, e.g.
<TCP .../>
<DAISYCHAIN .../>
<TCPPING .../>
Ergonomics
Ergonomics is similar to the dynamic setting of optimal values for the JVM, e.g. garbage collection,
memory sizes etc. In JGroups, ergonomics means that we try to dynamically determine and set optimal
values for protocol properties. Examples are thread pool size, flow control credits, heartbeat
frequency and so on.
libjgroups-java-2.12.2.Final.orig/doc/manual/en/modules/api.xml 0000644 0001750 0001750 00000212750 11647260573 024155 0 ustar moeller moeller
APIThis chapter explains the classes available in JGroups that will be
used by applications to build reliable group communication applications. The
focus is on creating and using channels.Information in this document may not be up-to-date, but the nature of
the classes in the JGroups toolkit described here is the same. For the most
up-to-date information refer to the Javadoc-generated documentation in the
doc/javadoc directory.All of the classes discussed below reside in the
org.jgroups package unless otherwise
mentioned.Utility classesThe org.jgroups.util.Util class contains a
collection of useful functionality which cannot be assigned to any
particular package.objectToByteBuffer(), objectFromByteBuffer()The first method takes an object as argument and serializes it
into a byte buffer (the object has to be serializable or
externalizable). The byte array is then returned. This method is often
used to serialize objects into the byte buffer of a message. The second
method returns a reconstructed object from a buffer. Both methods throw
an exception if the object cannot be serialized or unserialized.InterfacesThese interfaces are used with some of the APIs presented below,
therefore they are listed first.MessageListenerContrary to the pull-style of channels, some building blocks (e.g.
PullPushAdapter ) provide an event-like
push-style message delivery model. In this case,
the entity to be notified of message reception needs to provide a
callback to be invoked whenever a message has been received. The
MessageListener interface below provides a method
to do so:
public interface MessageListener {
public void receive(Message msg);
byte[] getState();
void setState(byte[] state);
}
Method receive() will be called when a
message is received. The getState() and
setState() methods are used to fetch and set
the group state (e.g. when joining). Refer to for a discussion of state transfer.ExtendedMessageListener
JGroups release 2.3 introduced ExtendedMessageListener enabling
partial state transfer (refer to
) while release 2.4 further expands ExtendedMessageListener with
streaming state transfer callbacks:
public interface ExtendedMessageListener extends MessageListener {
byte[] getState(String state_id);
void setState(String state_id, byte[] state);
/*** since JGroups 2.4 *****/
void getState(OutputStream ostream);
void getState(String state_id, OutputStream ostream);
void setState(InputStream istream);
void setState(String state_id, InputStream istream);
}
MembershipListener
The MembershipListener interface is similar to the MessageListener
interface above: every time a new view, a suspicion message, or a block event is received, the corresponding
method of the class implementing MembershipListener will be called.
public interface MembershipListener {
public void viewAccepted(View new_view);
public void suspect(Object suspected_mbr);
public void block();
}
Oftentimes the only method containing any functionality will be
viewAccepted() which notifies the receiver that
a new member has joined the group or that an existing member has left or
crashed. The suspect() callback is invoked by
JGroups whenever a member if suspected of having crashed, but not yet
excluded It could be that the member is suspected falsely, in which
case the next view would still contain the suspected member (there
is currently no unsuspect() method.
The block() method is called
to notify the member that it will soon be blocked sending messages. This
is done by the FLUSH protocol, for example to ensure that nobody is sending
messages while a state transfer is in progress. When block() returns, any thread
sending messages will be blocked, until FLUSH unblocks the thread again, e.g.
after the state has been transferred successfully.
Therefore, block() can be used to send pending messages or complete some other work.
Note that block() should be brief, or else the entire FLUSH protocol is blocked.
Sending messages in callbacks
Note that anything that could block should not be done in a callback.
This includes sending of messages;
if we have FLUSH on the stack, and send a message in a viewAccepted() callback, then the following
happens: the FLUSH protocol blocks all (multicast) messages before installing a view, then installs
the view, then unblocks. However, because installation of the view triggers the viewAccepted() callback,
sending of messages inside of viewAccepted() will block. This in turn blocks the viewAccepted() thread,
so the flush will never return !
If we need to send a message in a callback, the sending should be done on a separate thread, or a timer
task should be submitted to the timer.
ExtendedMembershipListener
The ExtendedMembershipListener interface extends
MembershipListener:
public interface ExtendedMembershipListener extends MembershipListener {
public void unblock();
}
The unblock() method is called
to notify the member that the FLUSH protocol has completed and the member can resume
sending messages. If the member did not stop sending messages on block(), FLUSH simply blocked them and
will resume, so no action is required from a member. Implementation of the unblock() callback is optional.
ChannelListener
public interface ChannelListener {
void channelConnected(Channel channel);
void channelDisconnected(Channel channel);
void channelClosed(Channel channel);
void channelShunned(); // deprecated in 2.8
void channelReconnected(Address addr); // deprecated in 2.8
}
A class implementing ChannelListener can
use the Channel.setChannelListener() method to
register with a channel to obtain information about state changes in a
channel. Whenever a channel is closed, disconnected or opened a callback
will be invoked.Receiver
public interface Receiver extends MessageListener, MembershipListener {
}
A Receiver can be used to receive messages and view
changes in push-style; rather than having to pull these events from a
channel, they will be dispatched to the receiver as soon as they have
been received. This saves one thread (application thread, pulling
messages from a channel, or the PullPushAdapter thread
Note that JChannel.receive() has been deprecated and will be removed in 3.0. The
preferred way of receiving messages is now via a Receiver callback (push style).
ExtendedReceiver
public interface ExtendedReceiver extends ExtendedMessageListener, MembershipListener {
}
This is a receiver who will be able to handle partial state transferReceiverAdapter and ExtendedReceiverAdapter
These classes implement Receiver and ExtendedReceiver. When implementing a callback, one can simply
extend ReceiverAdapter and overwrite receive() in order to not having to implement all callbacks of
the interface.
Merging of Extended interfaces with their super interfacesThe Extended- interfaces (ExtendedMessageListener, ExtendedReceiver) will be merged with their parents in
the 3.0 release of JGroups. The reason is that this will create an API backwards
incompatibility, which we didn't want to introduce in the 2.x series.AddressEach member of a group has an address, which uniquely identifies the
member. The interface for such an address is Address, which requires
concrete implementations to provide methods for comparison and sorting of
addresses, and for determination whether the address is a multicast
address. JGroups addresses have to implement the following interface:
public interface Address extends Externalizable, Comparable, Cloneable {
boolean isMulticastAddress();
int size();
}
Please never use implementations of Address directly; Address should always be used
as an opaque identifier of a cluster node !Actual implementations of addresses are often generated by the
bottommost protocol layer (e.g. UDP or TCP). This allows for all possible
sorts of addresses to be used with JGroups, e.g. ATM.In JChannel, it is the IP address of the host on which the stack is
running and the port on which the stack is receiving incoming messages; it
is represented by the concrete class
org.jgroups.stack.IpAddress. Instances of this
class are only used within the JChannel protocol
stack; users of a channel see addresses (of any kind) only as
Addresses. Since an address uniquely identifies a channel, and
therefore a group member, it can be used to send messages to that group
member, e.g. in Messages (see next section).
In 2.8, the default implementation of Address was changed from IpAddress to
org.jgroups.util.UUID.
MessageData is sent between members in the form of messages (
org.jgroups.Message ). A message can be sent by a member to a
single member , or to all
members of the group of which the channel is an endpoint. The
structure of a message is shown in .Structure of a messageA message contains 5 fields:Destination addressThe address of the receiver. If null , the
message will be sent to all current group membersSource addressThe address of the sender. Can be left null
, and will be filled in by the transport protocol (e.g. UDP) before
the message is put on the networkFlagsThis is one byte used for flags. The currently recognized flags are OOB, LOW_PRIO and HIGH_PRIO.
See the discussion on the concurrent stack for OOB.
PayloadThe actual data (as a byte buffer). The Message class contains
convenience methods to set a serializable object and to retrieve it
again, using serialization to convert the object to/from a byte
buffer.HeadersA list of headers that can be attached to a message. Anything
that should not be in the payload can be attached to a message as a
header. Methods putHeader() ,
getHeader() and
removeHeader() of Message can be used to
manipulate headers.A message is similar to an IP packet and consists of the payload (a
byte buffer) and the addresses of the sender and receiver (as Addresses).
Any message put on the network can be routed to its destination (receiver
address), and replies can be returned to the sender's address.A message usually does not need to fill in the sender's address when
sending a message; this is done automatically by the protocol stack before
a message is put on the network. However, there may be cases, when the
sender of a message wants to give an address different from its own, so
that for example, a response should be returned to some other
member.The destination address (receiver) can be an Address, denoting the
address of a member, determined e.g. from a message received previously,
or it can be null , which means that the message will
be sent to all members of the group. A typical multicast message, sending
string "Hello" to all members would look like
this:
Message msg=new Message(null, null, "Hello");
channel.send(msg);
ViewA View ( View ) is a list of the current
members of a group. It consists of a ViewId , which
uniquely identifies the view (see below), and a list of members. Views are
set in a channel automatically by the underlying protocol stack whenever a
new member joins or an existing one leaves (or crashes). All members of a
group see the same sequence of views.Note that there is a comparison function which orders all the
members of a group in the same way. Usually, the first member of the list
is the coordinator (the one who emits new views).
Thus, whenever the membership changes, every member can determine the
coordinator easily and without having to contact other members.The code below shows how to send a (unicast) message to the first
member of a view (error checking code omitted):
View view=channel.getView();
Address first=view.getMembers().first();
Message msg=new Message(first, null, "Hello world");
channel.send(msg);
Whenever an application is notified that a new view has been
installed (e.g. by
Receiver.viewAccepted(), the view is already set in
the channel. For example, calling
Channel.getView() in a
viewAccepted() callback would return the same
view (or possibly the next one in case there has already been a new view
!).ViewIdThe ViewId is used to uniquely number views. It consists of the
address of the view creator and a sequence number. ViewIds can be
compared for equality and put in a hashtable as they implement equals()
and hashCode() methods.Note that the latter 2 methods only take the ID into account.MergeViewWhenever a group splits into subgroups, e.g. due to a network
partition, and later the subgroups merge back together, a MergeView
instead of a View will be received by the application. The MergeView
class is a subclass of View and contains as additional instance variable
the list of views that were merged. As an example if the group denoted
by view V1:(p,q,r,s,t) split into subgroups
V2:(p,q,r) and V2:(s,t) , the
merged view might be V3:(p,q,r,s,t) . In this case
the MergeView would contains a list of 2 views:
V2:(p,q,r) and V2:(s,t) .JChannelIn order to join a group and send messages, a process has to create
a channel. A channel is like a socket. When a client connects to a
channel, it gives the the name of the group it would like to join. Thus, a
channel is (in its connected state) always associated with a particular
group. The protocol stack takes care that channels with the same group
name find each other: whenever a client connects to a channel given group
name G, then it tries to find existing channels with the same name, and
joins them, resulting in a new view being installed (which contains the
new member). If no members exist, a new group will be created.A state transition diagram for the major states a channel can assume
are shown in .Channel statesWhen a channel is first created, it is in the unconnected state. An
attempt to perform certain operations which are only valid in the
connected state (e.g. send/receive messages) will result in an exception.
After a successful connection by a client, it moves to the connected
state. Now channels will receive messages, views and suspicions from other
members and may send messages to other members or to the group. Getting
the local address of a channel is guaranteed to be a valid operation in
this state (see below). When the channel is disconnected, it moves back to
the unconnected state. Both a connected and unconnected channel may be
closed, which makes the channel unusable for further operations. Any
attempt to do so will result in an exception. When a channel is closed
directly from a connected state, it will first be disconnected, and then
closed.The methods available for creating and manipulating channels are
discussed now.Creating a channel
A channel can be created in two ways: an instance of a subclass of
Channel is created directly using its public
constructor (e.g. new JChannel() ), or a
channel factory is created, which -- upon request -- creates instances
of channels. We will only look at the first method of creating channel:
by direct instantiation.
The public constructor of JChannel looks as follows:
public JChannel(String props) throws ChannelException {}
It creates an instance of JChannel . The
props argument points to an XML file containing the configuration
of the protocol stack to be used. This can be a String, but there are also other constructors which
take for example a DOM element or a URL (more on this later).
If the props argument is null, the default properties will be
used. An exception will be thrown if the channel cannot be created.
Possible causes include protocols that were specified in the property
argument, but were not found, or wrong parameters to protocols.For example, the Draw demo can be launched as follows:
java org.javagroups.demos.Draw -props file:/home/bela/udp.xml
or
java org.javagroups.demos.Draw -props http://www.jgroups.org/udp.xml
In the latter case, an application downloads its protocol stack
specification from a server, which allows for central administration
of application properties.
A sample XML configuration looks like this (edited from udp.xml):
<config>
<UDP
mcast_addr="${jgroups.udp.mcast_addr:228.10.10.10}"
mcast_port="${jgroups.udp.mcast_port:45588}"
discard_incompatible_packets="true"
max_bundle_size="60000"
max_bundle_timeout="30"
ip_ttl="${jgroups.udp.ip_ttl:2}"
enable_bundling="true"
thread_pool.enabled="true"
thread_pool.min_threads="1"
thread_pool.max_threads="25"
thread_pool.keep_alive_time="5000"
thread_pool.queue_enabled="false"
thread_pool.queue_max_size="100"
thread_pool.rejection_policy="Run"
oob_thread_pool.enabled="true"
oob_thread_pool.min_threads="1"
oob_thread_pool.max_threads="8"
oob_thread_pool.keep_alive_time="5000"
oob_thread_pool.queue_enabled="false"
oob_thread_pool.queue_max_size="100"
oob_thread_pool.rejection_policy="Run"/>
<PING timeout="2000"
num_initial_members="3"/>
<MERGE2 max_interval="30000"
min_interval="10000"/>
<FD_SOCK/>
<FD timeout="10000" max_tries="5" />
<VERIFY_SUSPECT timeout="1500" />
<BARRIER />
<pbcast.NAKACK
use_mcast_xmit="false" gc_lag="0"
retransmit_timeout="300,600,1200,2400,4800"
discard_delivered_msgs="true"/>
<UNICAST timeout="300,600,1200,2400,3600"/>
<pbcast.STABLE stability_delay="1000" desired_avg_gossip="50000"
max_bytes="400000"/>
<VIEW_SYNC avg_send_interval="60000" />
<pbcast.GMS print_local_addr="true" join_timeout="3000"
view_bundling="true"/>
<FC max_credits="20000000"
min_threshold="0.10"/>
<FRAG2 frag_size="60000" />
<pbcast.STATE_TRANSFER />
</config>
A stack is wrapped by <config> and </config> elements and lists all protocols from
bottom (UDP) to top (STATE_TRANSFER). Each element defines one protocol.
Each protocol is
implemented as a Java class. When a protocol stack is created
based on the above XML configuration, the first element ("UDP") becomes the
bottom-most layer, the second one will be placed on the first, etc: the
stack is created from the bottom to the top.
Each element has to be the name of a Java class
that resides in the org.jgroups.stack.protocols
package. Note that only the base name has to be given, not the fully
specified class name (UDP instead of
org.jgroups.stack.protocols.UDP). If the
protocol class is not found, JGroups assumes that the name given is a
fully qualified classname and will therefore try to instantiate that
class. If this does not work an exception is thrown. This allows for
protocol classes to reside in different packages altogether, e.g. a
valid protocol name could be
com.sun.eng.protocols.reliable.UCAST .
Each layer may have zero or more arguments, which are specified as
a list of name/value pairs in parentheses directly after the protocol name.
In the example above, UDP is configured with some options, one of them being the
IP multicast address (mcast_addr) which is set to 228.10.10.10, or to the value of
the system property jgroups.udp.mcast_addr, if set.
Note that all members in a group have to have the same
protocol stack.Programmatic creation
Usually, channels are created by passing the name of an XML configuration file to the JChannel() constructor.
On top of this declarative configuration, JGroups provides an API to create a channel programmatically.
The way to do this is to first create a JChannel, then an instance of ProtocolStack, then add all desired
protocols to the stack and finally calling init() on the stack to set it up. The rest, e.g. calling
JChannel.connect() is the same as with the declarative creation.
An example of how to programmatically create a channel is shown below (copied from ProgrammaticChat):
JChannel ch=new JChannel(false); // 1
ProtocolStack stack=new ProtocolStack(); // 2
ch.setProtocolStack(stack); // 3
stack.addProtocol(new UDP().setValue("bind_addr", InetAddress.getByName("192.168.1.5")))
.addProtocol(new PING())
.addProtocol(new MERGE2())
.addProtocol(new FD_SOCK())
.addProtocol(new FD_ALL().setValue("timeout", 12000).setValue("interval", 3000))
.addProtocol(new VERIFY_SUSPECT())
.addProtocol(new BARRIER())
.addProtocol(new NAKACK())
.addProtocol(new UNICAST2())
.addProtocol(new STABLE())
.addProtocol(new GMS())
.addProtocol(new UFC())
.addProtocol(new MFC())
.addProtocol(new FRAG2()); // 4
stack.init(); // 5
ch.setReceiver(new ReceiverAdapter() {
public void viewAccepted(View new_view) {
System.out.println("view: " + new_view);
}
public void receive(Message msg) {
System.out.println(msg.getObject() + " [" + msg.getSrc() + "]");
}
});
ch.connect("ChatCluster");
for(;;) {
String line=Util.readStringFromStdin(": ");
ch.send(null, null, line);
}
First a JChannel is created. The 'false' argument tells the channel not to create a ProtocolStack. This
is needed because we will create one ourselves later (2) and set it in the channel (3).
Next, all protocols are added to the stack. Note that the order is from bottom (transport protocol) to
top. So UDP as transport is added first, then PING and so on, until FRAG2, which is the top protocol.
Every protocol can be configured via setters, but there is also a generic setValue(String attr_name,
Object value), which can be used to configure protocols as well, as shown in the example.
Once the stack is configured, we call ProtocolStack.init() to link all protocols correctly and to call
init() in every protocol instance. After this, the channel is ready to be used and all subsequent
actions (e.g. connect()) can be executed. When the init() method returns, we have essentially the
equivalent of new JChannel(config_file).
Setting options
A number of options can be set in a channel. To do so, the following method is used:
public void setOpt(int option, Object value);
Arguments are the options number and a value. The following
options are currently recognized:Channel.BLOCKThe argument is a boolean object. If true, block messages will be received.Channel.LOCALLocal delivery. The argument is a boolean value. If set to
true, a member will receive all messages it sent to itself.
Otherwise, all messages sent by itself will be discarded. This
option allows to send messages to the group, without receiving a
copy. Default is true (members will receive their own copy of
messages multicast to the group).Channel.AUTO_RECONNECTWhen set to true, a shunned channel will leave the group and
then try to automatically re-join. Default is false. Note that in 2.8, shunning has been removed, therefore
this option has been deprecated.Channel.AUTO_GETSTATEWhen set to true a shunned channel, after reconnection, will
attempt to fetch the state from the coordinator. This requires
AUTO_RECONNECT to be true as well. Default is false. Note that in 2.8, shunning has been removed, therefore
this option has been deprecated.The equivalent method to get options is
getOpt():
public Object getOpt(int option);
Given an option, the current value of the option is
returned.Deprecating options in 3.0
Most of the options (except LOCAL) have been deprecated in 2.6.x and will be removed in 3.0.
Giving the channel a logical name
A channel can be given a logical name which is then used instead of the channel's address. A logical name
might show the function of a channel, e.g. "HostA-HTTP-Cluster", which is more legible than a UUID
3c7e52ea-4087-1859-e0a9-77a0d2f69f29.
For example, when we have 3 channels, using logical names we might see a view "{A,B,C}", which is nicer than
"{56f3f99e-2fc0-8282-9eb0-866f542ae437, ee0be4af-0b45-8ed6-3f6e-92548bfa5cde, 9241a071-10ce-a931-f675-ff2e3240e1ad} !"
If no logical name is set, JGroups generates one, using the hostname and a random number, e.g. linux-3442.
If this is not desired and the UUIDs should be shown, use system property -Djgroups.print_uuids=true.
The logical name can be set using:
public void setName(String logical_name);
This should be done before connecting a channel. Note that the logical name stays with a channel until
the channel is destroyed, whereas a UUID is created on each connection.
When JGroups starts, it prints the logical name and the associated physical address(es):
-------------------------------------------------------------------
GMS: address=mac-53465, cluster=DrawGroupDemo, physical address=192.168.1.3:49932
-------------------------------------------------------------------
** View=[mac-53465|0] [mac-53465]
The logical name is mac-53465 and the physical address is 192.168.1.3:49932. The UUID is not shown here.
Generating custom addresses
Since 2.12 address generation is pluggable. This means that an application can determine what kind of
addresses it uses. The default address type is UUID, and since some protocols use UUID, it is recommended
to provide custom classes as subclasses of UUID.
This can be used to for example pass additional data around with an address, for example information about
the location of the node to which the address is assigned. Note that methods equals(), hashCode() and
compare() of the UUID super class should not be changed.
To use custom addresses, the following things have to be done:
Write an implementation of org.jgroups.stack.AddressGeneratorFor any class CustomAddress, it will need to get registered with the ClassConfigurator
in order to marshal it correctly:
class CustomAddress extends UUID {
static {
ClassConfigurator.add((short)8900, CustomAddress.class);
}
}
Note that the ID should be chosen such that it doesn't collide with any IDs defined in
jg-magic-map.xml.
Set the address generator in JChannel: setAddressGenerator(AddressGenerator). This
has to be done before the channel is connected
An example of a subclass is org.jgroups.util.PayloadUUID.
Connecting to a channelWhen a client wants to join a group, it
connects to a channel giving the name of the group
to be joined:
public void connect(String clustername) throws ChannelClosed;
The cluster name is a string, naming the cluster to be joined. All
channels that are connected to the same name form a cluster.
Messages multicast on any channel in the cluster will be received by all
members (including the one who sent it Local delivery can be turned on/off using
setOpt() . ).The method returns as soon as the group has been joined
successfully. If the channel is in the closed state (see ), an exception will be thrown. If there
are no other members, i.e. no other member has connected to a group with
this name, then a new group is created and the member joined. The first
member of a group becomes its coordinator . A
coordinator is in charge of multicasting new views whenever the
membership changes This is managed internally however, and an application
programmer does not need to be concerned about it. .Connecting to a channel and getting the state in one operation
Clients can also join a cluster group and fetch cluster state in one operation.
The best way to conceptualize connect and fetch state connect method is to
think of it as an invocation of regular connect and getstate methods executed in
succession. However, there are several advantages of using connect and fetch state
connect method over regular connect. First of all, underlying message exchange is
heavily optimized, especially if the flush protocol is used in the stack. But more
importantly, from clients perspective, connect and join operations become one atomic
operation.
public void connect(string cluster_name, address target,
string state_id, long timeout)
throws ChannelException;
Just as in regular connect method cluster name represents a cluster to be joined.
Address parameter indicates a cluster member to fetch state from. Null address parameter
indicates that state should be fetched from the cluster coordinator. If state should be fetched
from a particular member other than coordinator clients can provide an address of that member.
State id used for partial state transfer while timeout bounds entire join and fetch operation.
Getting the local address and the group nameMethod getLocalAddress() returns the
local address of the channel
Since 2.8 the method is getAddress(). In the case of
JChannel , the local address is generated by the
bottom-most layer of the protocol stack when the stack is connected to.
That means that -- depending on the channel implementation -- the local
address may or may not be available when a channel is in the unconnected
state.
public Address getLocalAddress(); // use getAddress() with 2.8.0+
Method getClusterName() returns the name
of the cluster in which the channel is a member:
public String getClusterName();
Again, the result is undefined if the channel is in the
unconnected or closed state.Getting the current viewThe following method can be used to get the current view of a
channel:
public View getView();
This method does not retrieve a new view
(message) from the channel, but only returns the current view of the
channel. The current view is updated every time a view message is
received: when method receive() is called, and
the return value is a view, before the view is returned, it will be
installed in the channel, i.e. it will become the current view.Calling this method on an unconnected or closed channel is
implementation defined. A channel may return null, or it may return the
last view it knew of.Sending a messageOnce the channel is connected, messages can be sent using the
send() methods:
public void send(Message msg) throws ChannelNotConnected, ChannelClosed;
public void send(Address dst, Address src, Object obj)
throws ChannelNotConnected, ChannelClosed;
The first send() method has only one
argument, which is the message to be sent. The message's destination
should either be the address of the receiver (unicast) or null
(multicast). When it is null, the message will be sent to all members of
the group (including itself). The source address may be null; if it is,
it will be set to the channel's address (so that recipients may generate
a response and send it back to the sender).The second send() method is a helper
method and uses the former method internally. It requires the address of
receiver and sender and an object (which has to be serializable),
constructs a Message and sends it.If the channel is not connected, or was closed, an exception will
be thrown upon attempting to send a message.Here's an example of sending a (multicast) message to all members
of a group:
Map data; // any serializable data
try {
channel.send(null, null, data);
}
catch(Exception ex) {
// handle errors
}
The null value as destination address means that the message will
be sent to all members in the group. The sender's address will be filled
in by the bottom-most protocol. The payload is a hashmap, which will
be serialized into the message's buffer and unserialized at the
receiver's end. Alternatively, any other means of generating a byte
buffer and setting the message's buffer to it (e.g. using
Message.setBuffer()) would also work.Here's an example of sending a (unicast) message to the first
member (coordinator) of a group:
Map data;
try {
Address receiver=channel.getView().getMembers().first();
channel.send(receiver, null, data);
}
catch(Exception ex) {
// handle errors
}
It creates a Message with a specific address for the receiver (the
first member of the group). Again, the sender's address can be left null
as it will be filled in by the bottom-most protocol.Receiving a messageMethod receive() is used to receive
messages, views, suspicions and blocks:
public Object receive(long timeout) throws ChannelNotConnected,
ChannelClosed, Timeout;
A channel receives messages asynchronously from the network and
stores them in a queue. When receive() is called, the next available
message from the top of that queue is removed and returned. When there
are no messages on the queue, the method will block. If
timeout is greater than 0, it will wait the
specified number of milliseconds for a message to be received, and throw
a TimeoutException exception if none was received
during that time. If the timeout is 0 or negative, the method will wait
indefinitely for the next available message.Depending on the channel options (see ), the following types of objects may be
received:MessageA regular message. To send a response to the sender, a new
message can be created. Its destination address would be the
received message's source address. Method
Message.makeReply() is a helper method to
create a response.ViewA view change, signalling that a member has joined, left or
crashed. The application may or may not perform some action upon
receiving a view change (e.g. updating a GUI object of the
membership, or redistributing a load-balanced collaborative task
to all members). Note that a longer action, or any action that
blocks should be performed in a separate thread. A
MergeView will be received when 2 or more
subgroups merged into one (see for
details). Here, a possible state merge by the application needs to
be done in a separate thread.SuspectEventNotification of a member that is suspected. Method
SuspectEvent.getMember() retrieves the
address of the suspected member. Usually this message will be
followed by a view change.BlockEventThe application has to stop sending messages. When the application
has stopped sending messages, it needs to acknowledge this message
with a Channel.blockOk() method.
The BlockEvent reception can be used to complete pending tasks, e.g. send pending
messages, but once Channel.blockOk() has been called, all threads that send messages
(calling Channel.send() or Channel.down()) will be blocked until FLUSH unblocks them.
UnblockEventThe application can resume sending messages. Any previously messages blocked by FLUSH
will be unblocked; when the UnblockEvent is received the channel has already been unblocked.GetStateEventReceived when the application's current state should be
saved (for a later state transfer. A copy of
the current state should be made (possibly wrapped in a
synchronized statement and returned
calling method Channel.returnState() . If
state transfer events are not enabled on the channel (default),
then this event will never be received. This message will only be
received with the Virtual Synchrony suite of protocols (see the
Programmer's Guide).StreamingGetStateEventReceived when the application's current state should be
provided to a state requesting group member. If state transfer
events are not enabled on the channel (default), or if channel is
not configured with pbcast.STREAMING_STATE_TRANSFER then this
event will never be received. SetStateEventReceived as response to a
getState(s) method call. The argument
contains the state of a single member ( byte[] ) or
of all members ( Vector ). Since the state
of a single member could also be a vector, the interpretation of
the argument is left to the application.StreamingSetStateEventReceived at state requesting member when the state
InputStream becomes ready for reading. If state transfer events
are not enabled on the channel (default), or if channel is not
configured with pbcast.STREAMING_STATE_TRANSFER then this event
will never be received. The caller has to check the type of the object returned. This can
be done using the instanceof operator, as
follows:
Object obj=channel.receive(0); // wait forever
if(obj instanceof Message)
Message msg=(Message)obj;
else if(obj instanceof View)
View v=(View)obj;
else
; // don't handle suspicions or blocks
If for example views, suspicions and blocks are disabled, then the
caller is guaranteed to only receive return values of type
Message . In this case, the return value can be
cast to a Message directly, without using the
instanceof operator.If the channel is not connected, or was closed, a corresponding
exception will be thrown.The example below shows how to retrieve the "Hello world" string
from a message:
Message msg; // received above
try {
String s=(String)msg.getObject(); // error if obj not Serializable
// alternative: s=new String(msg.getBuffer());
}
catch(Exception ex) {
// handle errors, e.g. casting error above)
}
The Message.getObject() method retrieves the message's byte
buffer, converts it into a (serializable) object and returns the
object.Using a Receiver to receive messagesInstead of pulling messages from a channel in an application
thread, a Receiver can be registered with a channel. This is the preferred and recommended way of receiving
messages. In 3.0, the receive() method will be removed from JChannel.
All received messages, view changes and state transfer requests will invoke callbacks
on the registered Receiver:
JChannel ch=new JChannel();
ch.setReceiver(new ExtendedReceiverAdapter() {
public void receive(Message msg) {
System.out.println("received message " + msg);
}
public void viewAccepted(View new_view) {
System.out.println("received view " + new_view);
}
});
ch.connect("bla");
The ExtendedReceiverAdapter class
implements all callbacks of ExtendedReceiver with no-ops, in the example
above we override receive() and viewAccepted().The advantage of using a Receiver is that the application doesn't
have to waste 1 thread for pulling messages out of a channel. In
addition, the channel doesn't have to maintain an (unbounded) queue of
messages/views, which can quickly get large if the receiver cannot
process messages fast enough, and the sender keeps sending
messages.
Note that the Channel.receive() method has been deprecated, and will be removed in 3.0. Use the Receiver
interface instead and register as a Receiver with Channel.setReceiver(Receiver r).
Peeking at a messageInstead of removing the next available message from the channel,
peek() just returns a reference to the next
message, but does not remove it. This is useful when one has to check
the type of the next message, e.g. whether it is a regular message, or a
view change. The signature of this method is not shown here, it is the
same as for receive() .
The peek() method has also been deprecated, and will be removed in 3.0.
Getting the group's stateA newly joined member may wish to retrieve the state of the group
before starting work. This is done with
getState(). This method returns the state of
one member (in most cases, of the oldest member, the coordinator). It
returns true or false, depending on whether a valid state could be
retrieved. For example, if a member is a singleton, then calling this
method would always return false A member will never retrieve the state
from itself ! .The actual state is returned as the return value of one of the
subsequent receive() calls, in the form of a
SetStateEvent object. If
getState() returned true, then a valid state
(non-null) will be returned, otherwise a null state will be returned.
Alternatively if an application uses MembershipListener (see ) instead of pulling messages from a
channel, the getState() method will be invoked
and a copy of the current state should be returned. By the same token,
setting a state would be accomplished by JGroups calling the
setState() method of the state fetcher.The reason for not directly returning the state as a result of
getState() is that the state has to be returned
in the correct position relative to other messages. Returning it
directly would violate the FIFO properties of a channel, and state
transfer would not be correct.The following code fragment shows how a group member participates
in state transfers:
channel=new JChannel();
channel.connect("TestChannel");
boolean rc=channel.getState(null, 5000);
...
Object state, copy;
Object ret=channel.receive(0);
if(ret instanceof Message)
;
else if(ret instanceof GetStateEvent) {
// make a copy so that other msgs don't change the state
copy=copyState(state);
channel.returnState(Util.objectToByteBuffer(copy));
}
else if(ret instanceof SetStateEvent) {
SetStateEvent e=(SetStateEvent)ret;
state=e.getArg();
}
A JChannel has to be created whose stack includes the
STATE_TRANSFER or
pbcast.STATE_TRANSFER protocols (see ). Method getState()
subsequently asks the channel to return the current state. If there is a
current state (there may not be any other members in the group !), then
true is returned. In this case, one of the subsequent
receive() method invocations on the channel
will return a SetStateEvent object which contains
the current state. In this case, the caller sets its state to the one
received from the channel.Method receive() might return a
GetStateEvent object, requesting the state of the
member to be returned. In this case, a copy of the current
state should be made and returned using
JChannel.returnState() . It is important to a)
synchronize access to the state when returning it since other accesses
may modify it while it is being returned and b) make a copy of the state
since other accesses after returning the state may still be able to
modify it ! This is possible because the state is not immediately
returned, but travels down the stack (in the same address space), and a
reference to it could still alter it.Getting the state with a ReceiverAs an alternative to handling the GetStateEvent and SetStateEvent
events, and calling Channel.returnState(), a Receiver could be used. The
example above would look like this:
class MyReceiver extends ReceiverAdapter {
final Map m=new HashMap();
public byte[] getState() {
// so nobody else can modify the map while we serialize it
synchronized(m) {
byte[] state=Util.objectToByteBuffer(m);
return state;
}
}
public void setState(byte[] state) {
synchronized(m) {
Map new_m=(Map)Util.objectFromByteBuffer(state);
m.clear();
m.addAll(new_m);
}
}
}
// use default props (has to include STATE_TRANSFER)
channel=new JChannel();
channel.setReceiver(new MyReceiver());
channel.connect("TestChannel");
boolean rc=channel.getState(null, 5000);
In a group consisting of A,B and C, with D joining the group and
calling Channel.getState(), the following sequence of callbacks happens:
D calls Channel.getState(). The state will be retrieved from the oldest member, A
A.MyReceiver.getState() is called. A returns a copy of its hashmap
D: getState() returns true
D.MyReceiver.setState() is called with the serialized state. D unserializes the state and sets it
Partial state transferPartial state transfer means that instead of transferring the
entire state, we may want to transfer only a
substate. For example, with HTTP session
replication, a new node in a cluster may want to transfer only the state
of a specific session, not all HTTP sessions. This
can be done with either the pull or push model. The method to call would
be Channel.getState(), including the ID of the substate (a string). In
the pull model, GetStateEvent and SetStateEvent have an additional
member, state_id, and in the push model, there are 2 additional
getState() and setState() callbacks. The example below shows partial
state transfer for the push model:
class MyReceiver extends ExtendedReceiverAdapter {
final Map m=new HashMap();
public byte[] getState() {
return getState(null);
}
public byte[] getState(String substate_id) {
// so nobody can modify the map while we serialize it
synchronized(m) {
byte[] state=null;
if(substate_id == null) {
state=Util.objectToByteBuffer(m);
}
else {
Object value=m.get(substate_id);
if(value != null) {
return Util.objectToByteBuffer(value);
}
}
return state;
}
}
public void setState(byte[] state) {
setState(null, state);
}
public void setState(String substate_id, byte[] state) {
synchronized(m) {
if(substate_id != null) {
Object value=Util.objectFromByteBuffer(state);
m.put(substate_id, value);
}
else {
Map new_m=(Map)Util.objectFromByteBuffer(state);
m.clear();
m.addAll(new_m);
}
}
}
}
// use default props (has to include pbcast.STATE_TRANSFER)
channel=new JChannel();
channel.setReceiver(new MyReceiver());
channel.connect("TestChannel");
boolean rc=channel.getState(null, "MyID", 5000);
The example shows that the Channel.getState() method specifies the
ID of the substate, in this case "MyID". The
getState(String substate_id) method checks
whether the substate ID is not null, and returns the substate pertaining
to the ID, or the entire state if the substate_id is null. The same goes
for setting the substate: if setState(String substate_id,
byte[] state) has a non-null substate_id, only that part of
the current state will be overwritten, otherwise (if null) the entire
state will be overwritten.Streaming state transferStreaming state transfer allows transfer of application (partial)
state without having to load entire state into memory prior to sending
it to a joining member. Streaming state transfer is especially useful if
the state is very large (>1Gb), and use of regular state transfer
would likely result in OutOfMemoryException. Streaming state transfer
was introduced in JGroups 2.4. JGroups channel has to be configured with
either regular or streaming state transfer. The JChannel API that invokes
state transfer (i.e. JChannel.getState(long timeout, Address member))
remains the same. Streaming state transfer, just as regular byte based state
transfer, can be used in both pull and push mode. Similarly to the
current getState and setState methods of org.jgroups.MessageListener,
the application interested in streaming state transfer in a push mode would
implement streaming getState method(s) by sending/writing state through
a provided OutputStream reference and setState method(s) by
receiving/reading state through a provided InputStream reference. In
order to use streaming state transfer in a push mode, existing
ExtendedMessageListener has been expanded to include additional four
methods:
public interface ExtendedMessageListener {
/*non-streaming callback methods ommitted for clarity*/
void getState(OutputStream ostream);
void getState(String state_id, OutputStream ostream);
void setState(InputStream istream);
void setState(String state_id, InputStream istream);
}
For a pull mode (when application uses channel.receive() to fetch
events) two new event classes will be introduced:StreamingGetStateEventStreamingSetStateEvent These two events/classes are very similar to existing
GetStateEvent and SetStateEvent but introduce a new field;
StreamingGetStateEvent has an OutputStream and StreamingSetStateEvent
has an InputStream.The following code snippet demonstrates how to pull events from a
channel, processing StreamingGetStateEvent and sending hypothetical
state through a provided OutputStream reference. Handling of
StreamingSetStateEvent is analogous to this example:
...
Object obj=channel.receive(0);
if(obj instanceof StreamingGetStateEvent) {
StreamingGetStateEvent evt=(StreamingGetStateEvent)obj;
OutputStream oos = null;
try {
oos=new ObjectOutputStream(evt.getArg());
oos.writeObject(state);
oos.flush();
}
catch (Exception e) {}
finally {
try {
oos.close();
}
catch (IOException e) {
System.err.println(e);
}
}
}
JGroups has a great flexibility with state transfer methodology by
allowing application developers to implement both byte based and
streaming based state transfers. Application can, for example, implement
streaming and byte based state transfer callbacks and then interchange
state transfer protocol in channel configuration to use either streaming
or byte based state transfer. However, one cannot configure a channel
with both state transfers at the same time and then in runtime choose
which particular state transfer type to use.Disconnecting from a channelDisconnecting from a channel is done using the following
method:
public void disconnect();
It will have no effect if the channel is already in the
disconnected or closed state. If connected, it will remove itself from
the group membership. This is done (transparently for a channel user) by
sending a leave request to the current coordinator. The latter will
subsequently remove the channel's address from its local view and send
the new view to all remaining members.After a successful disconnect, the channel will be in the
unconnected state, and may subsequently be re-connected to.Closing a channelTo destroy a channel instance (destroy the associated protocol
stack, and release all resources), method
close() is used:
public void close();
It moves the channel to the closed state, in which no further
operations are allowed (most throw an exception when invoked on a closed
channel). In this state, a channel instance is not considered used any
longer by an application and -- when the reference to the instance is
reset -- the channel essentially only lingers around until it is garbage
collected by the Java runtime system. libjgroups-java-2.12.2.Final.orig/doc/manual/en/modules/blocks.xml 0000644 0001750 0001750 00000114707 11647260573 024664 0 ustar moeller moeller Building BlocksBuilding blocks are layered on top of channels. Most of them
do not even need a channel, all they need is a class that implements
interface Transport (channels do). This
enables them to work on any type of group transport that implements this
interface. Building blocks can be used instead of channels whenever
a higher-level interface is required.Whereas channels are simple
socket-like constructs, building blocks may offer a far more
sophisticated interface. In some cases, building blocks offer access
to the underlying channel, so that -- if the building block at hand
does not offer a certain functionality -- the channel can be
accessed directly. Building blocks are located in the
org.jgroups.blocks package. Only the ones
that are relevant for application programmers are discussed
below.PullPushAdapterNote that this building block has been deprecated and should not be used anymore !
Use a Receiver instead.
This class is a converter (or adapter, as used in between the pull-style of actively
receiving messages from the channel and the push-style where
clients register a callback which is invoked whenever a message
has been received. Clients of a channel do not have to allocate a
separate thread for message reception.A PullPushAdapter is always created
on top of a class that implements interface
Transport (e.g. a channel). Clients
interested in being called when a message is received can register
with the PullPushAdapter using method
setListener(). They have to implement
interface MessageListener, whose
receive() method will be called when a
message arrives. When a client is interested in getting view,
suspicion messages and blocks, then it must additionally register
as a MembershipListener using method
setMembershipListener(). Whenever a view,
suspicion or block is received, the corresponding method will be
called.Upon creation, an instance of
PullPushAdapter creates a thread which
constantly calls the receive() method of
the underlying Transport instance, blocking
until a message is available. When a message is received, if there
is a registered message listener, its
receive() method will be called.As this class does not implement interface
Transport, but merely uses it for receiving
messages, an underlying object has to be used to send messages
(e.g. the channel on top of which an object of this class
resides). This is shown in .Class <classname>PullPushAdapter</classname>A diagram representing the PullPushAdapter.As is shown, the thread constantly pulls messages from the
channel and forwards them to the registered listeners. An
application thus does not have to actively pull for messages, but
the PullPushAdapter does this for it. Note
however, that the application has to directly
access the channel if it wants to send a
message.ExampleThis section shows sample code for using a
PullPushAdapter. The example has been
shortened for readability (error handling has been
removed).
public class PullPushTest implements MessageListener {
Channel channel;
PullPushAdapter adapter;
byte[] data="Hello world".getBytes();
String props; // fetch properties
public void receive(Message msg) {
System.out.println("Received msg: " + msg);
}
public void start() throws Exception {
channel=new JChannel(props);
channel.connect("PullPushTest");
adapter=new PullPushAdapter(channel);
adapter.setListener(this);
for(int i=0; i < 10; i++) {
System.out.println("Sending msg #" + i);
channel.send(new Message(null, null, data));
Thread.currentThread().sleep(1000);
}
adapter.stop();
channel.close();
}
public static void main(String args[]) {
try {
new PullPushTest().start();
}
catch(Exception e) { /* error */ }
}
}
First a channel is created and connected to. Then an
instance of PullPushAdapter is created
with the channel as argument. The constructor of
PullPushAdapter starts its own thread
which continually reads on the channel. Then the
MessageListener is set, which causes all
messages received on the channel to be sent to
receive(). Then a number of messages
are sent via the channel to the entire group. As group messages
are also received by the sender, the
receive() method will be called every
time a message is received. Finally the
PullPushAdapter is stopped and the
channel closed. Note that explicitly stopping the
PullPushAdapter is not actually
necessary, a closing the channel would cause the
PullPushAdapter to terminate
anyway.Note that, compared to the pull-style example, push-style
message reception is considerably easier (no separate thread
management) and requires less code to program.
The PullPushAdapter has been deprecated, and will be removed in 3.0. Use a Receiver implementation
instead. The advantage of the Receiver-based (push) model is that we save 1 thread.
MessageDispatcherChannels are simple patterns to
asynchronously send a receive
messages. However, a significant number of communication patterns
in group communication require synchronous
communication. For example, a sender would like to send
a message to the group and wait for all responses. Or another
application would like to send a message to the group and wait
only until the majority of the receivers have sent a response, or
until a timeout occurred.MessageDispatcher offers a
combination of the above pattern with other patterns. It provides
synchronous (as well as asynchronous) message sending with
request-response correlation, e.g. matching responses with the
original request. It also offers push-style message reception (by
internally using the
PullPushAdapter).An instance of MessageDispatcher is
created with a channel as argument. It can now be used in both
client and server role: a client sends
requests and receives responses and a server receives requests and
send responses. MessageDispatcher allows a
application to be both at the same time. To be able to serve
requests, the RequestHandler.handle()
method has to be implemented:
Object handle(Message msg);
The handle() method is called any
time a request is received. It must return a return value (must be
serializable, but can be null) or throw an exception. The return
value will be returned to the sender (as a null response, see
below). The exception will also be propagated to the
requester.The two methods to send requests are:
public RspList castMessage(Vector dests, Message msg, int mode, long timeout);
public Object sendMessage(Message msg, int mode, long timeout)
throws TimeoutException;
The castMessage() method sends a
message to all members defined in dests. If
dests is null the message will be sent to
all members of the current group. Note that a possible destination
set in the message will be overridden. If a message is sent
synchronously then the timeout argument
defines the maximum amount of time in milliseconds to wait for the
responses.The mode parameter defines whether
the message will be sent synchronously or asynchronously. The
following values are valid (from
org.jgroups.blocks.GroupRequest):GET_FIRSTReturns the first response
received.GET_ALLWaits for all responses (minus the ones from
suspected members)GET_MAJORITYWaits for a majority of all responses
(relative to the group size)GET_ABS_MAJORITYWaits for the majority (absolute, computed
once)GET_NWait for n responses (may block if n > group
size)GET_NONEWait for no responses, return immediately
(non-blocking). This make the call
asynchronous.The sendMessage() method allows an
application programmer to send a unicast message to a receiver and
optionally receive the response. The destination of the message
has to be non-null (valid address of a receiver). The
mode argument is ignored (it is by default
set to GroupRequest.GET_FIRST) unless it is
set to GET_NONE in which case the request
becomes asynchronous, ie. we will not wait for the
response.One advantage of using this building block is that failed
members are removed from the set of expected responses. For
example, when sending a message to 10 members and waiting for all
responses, and 2 members crash before being able to send a
response, the call will return with 8 valid responses and 2 marked
as failed. The return value of
castMessage() is a
RspList which contains all responses (not
all methods shown):
public class RspList implements Map<Address,Rsp> {
public boolean isReceived(Address sender);
public int numSuspectedMembers();
public Vector getResults();
public Vector getSuspectedMembers();
public boolean isSuspected(Address sender);
public Object get(Address sender);
public int size();
}
Method isReceived() checks whether
a response from sender has already been
received. Note that this is only true as long as no response has
yet been received, and the member has not been marked as
failed. numSuspectedMembers() returns the
number of members that failed (e.g. crashed) during the wait for
responses. getResults() returns a list of
return values. get() returns the return
value for a specific member.ExampleThis section describes an example of how to use a
MessageDispatcher.
public class MessageDispatcherTest implements RequestHandler {
Channel channel;
MessageDispatcher disp;
RspList rsp_list;
String props; // to be set by application programmer
public void start() throws Exception {
channel=new JChannel(props);
disp=new MessageDispatcher(channel, null, null, this);
channel.connect("MessageDispatcherTestGroup");
for(int i=0; i < 10; i++) {
Util.sleep(100);
System.out.println("Casting message #" + i);
rsp_list=disp.castMessage(null,
new Message(null, null, new String("Number #" + i)),
GroupRequest.GET_ALL, 0);
System.out.println("Responses:\n" +rsp_list);
}
channel.close();
disp.stop();
}
public Object handle(Message msg) {
System.out.println("handle(): " + msg);
return new String("Success !");
}
public static void main(String[] args) {
try {
new MessageDispatcherTest().start();
}
catch(Exception e) {
System.err.println(e);
}
}
}
The example starts with the creation of a channel. Next,
an instance of MessageDispatcher is
created on top of the channel. Then the channel is
connected. The MessageDispatcher will
from now on send requests, receive matching responses (client
role) and receive requests and send responses (server
role).We then send 10 messages to the group and wait for all
responses. The timeout argument is 0,
which causes the call to block until all responses have been
received.The handle() method simply prints
out a message and returns a string.Finally both the MessageDispatcher
and channel are closed.RpcDispatcherThis class is derived from
MessageDispatcher. It allows a programmer
to invoke remote methods in all (or single) group members and
optionally wait for the return value(s). An application will
typically create a channel and layer the
RpcDispatcher building block on top of it,
which allows it to dispatch remote methods (client role) and at
the same time be called by other members (server role).Compared to MessageDispatcher, no
handle() method needs to be
implemented. Instead the methods to be called can be placed
directly in the class using regular method definitions (see
example below). The invoke remote method calls (unicast and
multicast) the following methods are used (not all methods
shown):
public RspList callRemoteMethods(Vector dests, String method_name, int mode, long timeout);
public RspList callRemoteMethods(Vector dests, String method_name, Object arg1, int mode,
long timeout);
public Object callRemoteMethod(Address dest, String method_name, int mode, long timeout);
public Object callRemoteMethod(Address dest, String method_name, Object arg1, int mode,
long timeout);
The family of callRemoteMethods()
is invoked with a list of receiver addresses. If null, the method
will be invoked in all group members (including the sender). Each
call takes the name of the method to be invoked and the
mode and timeout
parameters, which are the same as for
MessageDispatcher. Additionally, each
method takes zero or more parameters: there are
callRemoteMethods() methods with up to 3
arguments. As shown in the example above, the first 2 methods take
zero and one parameters respectively.The family of callRemoteMethod()
methods takes almost the same parameters, except that there is
only one destination address instead of a list. If the
dest argument is null, the call will
fail.If a sender needs to use more than 3 arguments, it can use
the generic versions of
callRemoteMethod() and
callRemoteMethods() which use a
MethodCallSee the
Programmer's Guide and the Javadoc documentation for more
information about this class. instance rather
than explicit arguments.Java's Reflection API is used to find the correct method in
the receiver according to the method name and number and types of
supplied arguments. There is a runtime exception if a method
cannot be resolved.(* Update: these methods are deprecated; must use
MethodCall argument now *)ExampleThe code below shows an example:
public class RpcDispatcherTest {
Channel channel;
RpcDispatcher disp;
RspList rsp_list;
String props; // set by application
public int print(int number) throws Exception {
return number * 2;
}
public void start() throws Exception {
channel=new JChannel(props);
disp=new RpcDispatcher(channel, null, null, this);
channel.connect("RpcDispatcherTestGroup");
for(int i=0; i < 10; i++) {
Util.sleep(100);
rsp_list=disp.callRemoteMethods(null, "print",
new Integer(i), GroupRequest.GET_ALL, 0);
System.out.println("Responses: " +rsp_list);
}
channel.close();
disp.stop();
}
public static void main(String[] args) {
try {
new RpcDispatcherTest().start();
}
catch(Exception e) {
System.err.println(e);
}
}
}
Class RpcDispatcher defines method
print() which will be called
subsequently. The entry point start()
method creates a channel and an
RpcDispatcher which is layered on
top. Method callRemoteMethods() then
invokes the remote print() method in
all group members (also in the caller). When all responses have
been received, the call returns and the responses are
printed.As can be seen, the RpcDispatcher
building block reduces the amount of code that needs to be
written to implement RPC-based group communication applications
by providing a higher abstraction level between the application
and the primitive channels.RequestOptions
RequestOptions is a collection of options that can be passed into a call, e.g. the mode (GET_ALL, GET_NONE),
timeout, flags etc. It is an alternative to passing multiple arguments to a method.
All calls with individual parameters have been deprecated in 2.9 and the new calls with RequestOptions
are:
public RspList callRemoteMethods(Collection<Address> dests, String method_name,
Object[] args,Class[] types, RequestOptions options);
public RspList callRemoteMethods(Collection<Address> dests, MethodCall method_call,
RequestOptions options);
public Object callRemoteMethod(Address dest, String method_name, Object[] args,
Class[] types, RequestOptions options);
public Object callRemoteMethod(Address dest, MethodCall call, RequestOptions options);
An example of how to use RequestOptions is:
RpcDispatcher disp;
RequestOptions opts=new RequestOptions(Request.GET_ALL)
.setFlags(Message.NO_FC | Message.DONT_BUNDLE);
Object val=disp.callRemoteMethod(target, method_call, opts);
Asynchronous calls with futures
When invoking a synchronous call, the calling thread is blocked until the response (or responses) has
been received.
A Future allows a caller to return immediately and grab the result(s) later. In
2.9, two new methods, which return futures, have been added to RpcDispatcher:
public NotifyingFuture<RspList> callRemoteMethodsWithFuture(Collection<Address> dests,
MethodCall method_call, RequestOptions options);
public <T> NotifyingFuture<T> callRemoteMethodWithFuture(Address dest, MethodCall call,
RequestOptions options);
A NotifyingFuture extends java.util.concurrent.Future, with its regular methods such as isDone(),
get() and cancel(). NotifyingFuture adds setListener<FutureListener> to get notified when
the result is available. This is shown in the following code:
NotifyingFuture<RspList> future=dispatcher.callRemoteMethodsWithFuture(...);
future.setListener(new FutureListener() {
void futureDone(Future<T> future) {
System.out.println("result is " + future.get());
}
}
);
ReplicatedHashMap
This class was written as a demo of how state can be shared between nodes of a cluster. It has never been
heavily tested and is therefore not meant to be used in production, and unsupported.
A ReplicatedHashMap uses a concurrent hashmap internally
and allows to
create several instances of hashmaps in different processes. All
of these instances have exactly the same state at all times. When
creating such an instance, a group name determines which group of
replicated hashmaps will be joined. The new instance will then query the
state from existing members and update itself before starting to
service requests. If there are no existing members, it will simply
start with an empty state.
Modifications such as put(),
clear() or
remove() will be propagated in orderly
fashion to all replicas. Read-only requests such as
get() will only be sent to the local
copy.
Since both keys and values of a hashtable will be sent
across the network, both of them have to be
serializable. This allows for example to register remote RMI
objects with any local instance of a hashtable, which can
subsequently be looked up by another process which can then invoke
remote methods (remote RMI objects are serializable). Thus, a
distributed naming and registration service can be built in just a
couple of lines.
A ReplicatedHashMap allows to
register for notifications, e.g. when a new item is set, or an
existing one removed. All registered listeners will notified when
such an event occurs. Notification is always local; for example in
the case of removing an element, first the element is removed in
all replicas, which then notify their listener(s) of the removal
(after the fact).
ReplicatedHashMap allow members in
a group to share common state across process and machine
boundaries.
NotificationBusThis class provides notification sending and handling
capability. Also, it allows an application programmer to maintain
a local cache which is replicated by all
instances. NotificationBus also sits on top
of a channel, however it creates its channel itself, so the
application programmers do not have to provide their own
channel. Notification consumers can subscribe to receive
notifications by calling setConsumer()
and implementing interface
NotificationBus.Consumer:
public interface Consumer {
void handleNotification(Serializable n);
Serializable getCache();
void memberJoined(Address mbr);
void memberLeft(Address mbr);
}
Method handleNotification() is
called whenever a notification is received from the channel. A
notification is any object that is serializable. Method
getCache() is called when someone wants
to retrieve our state; the state can be returned as a serializable
object. The memberJoined() and
memberLeft() callbacks are invoked
whenever a member joins or leaves (or crashes).The most important methods of
NotificationBus are:
public class NotificationBus {
public void setConsumer(Consumer c);
public void start() throws Exception;
public void stop();
public void sendNotification(Serializable n);
public Serializable getCacheFromCoordinator(long timeout, int max_tries);
public Serializable getCacheFromMember(Address mbr, long timeout, int max_tries);
}
Method setConsumer() allows a
consumer to register itself for notifications.The start() and
stop() methods start and stop the
NotificationBus.Method sendNotification() sends the
serializable object given as argument to all members of the group,
invoking their handleNotification()
methods on reception.Methods getCacheFromCoordinator()
and getCacheFromMember() provide
functionality to fetch the group state from the coordinator (first
member in membership list) or any other member (if its address is
known). They take as arguments a timeout and a maximum number of
unsuccessful attempts until they return null. Typically one of
these methods would be called just after creating a new
NotificationBus to acquire the group
state. Note that if these methods are used, then the consumers
must implement Consumer.getCache(),
otherwise the two methods above would always return null.Distributed locking
In 2.12, a new distributed locking service was added, replacing DistributedLockManager. The new service is
implemented as a protocol and is used via org.jgroups.blocks.locking.LockService.
LockService talks to the locking protocol via events. The main abstraction of a distributed lock is an
implementation of java.util.concurrent.locks.Lock. All lock methods are supported, however, conditions
are not yet supported. (Based on feedback, they might be added later).
Below is an example of how LockService is typically used:
// locking.xml needs to have a locking protocol
JChannel ch=new JChannel("/home/bela/locking.xml");
LockService lock_service=new LockService(ch);
ch.connect("lock-cluster");
Lock lock=lock_service.getLock("mylock");
lock.lock();
try {
// do something with the locked resource
}
finally {
lock.unlock();
}
In the example, we create a channel, then a LockService, then connect the channel. Then we grab a lock
named "mylock", which we lock and subsequently unlock.
Note that the owner of a lock is always a given thread in a cluster, so the owner is the JGroups address and
the thread ID. This means that different threads inside the same JVM trying to access the same named lock
will compete for it. If thread-22 grabs the lock first, then thread-5 will block until thread-23
releases the lock.
JGroups includes a demo (org.jgroups.demos.LockServiceDemo), which can be used to interactively experiment
with distributed locks. LockServiceDemo -h dumps all command line options.
Currently (Jan 2011), there are 2 protocols which provide locking:
PEER_LOCK and CENTRAL_LOCK. The locking
protocol has to be placed at or towards the top of the stack (close to the channel).
Locking and merges
The following scenario is susceptible to merging: we have a cluster view of {A,B,C,D} and then the cluster
splits into {A,B} and {C,D}. Assume that B and D now acquire a lock "mylock".
This is what happens (with the locking protocol being CENTRAL_LOCK):
There are 2 coordinators: A for {A,B} and C for {C,D}B successfully acquires "mylock" from AD successfully acquires "mylock" from CThe partitions merge back into {A,B,C,D}. Now, only A is the coordinator, but C ceases
to be a coordinatorProblem: D still holds a lock which should actually be invalid !
There is no easy way (via the Lock API) to 'remove' the lock from D. We could for example simply release
D's lock on "mylock", but then there's no way telling D that the lock it holds is actually stale !
Therefore the recommended solution here is for nodes to listen to MergeView changes if they expect
merging to occur, and re-acquire all of their locks after a merge, e.g.:
Lock l1, l2, l3;
LockService lock_service;
...
public void viewAccepted(View view) {
if(view instanceof MergeView) {
new Thread() {
public void run() {
lock_service.unlockAll();
// stop all access to resources protected by l1, l2 or l3
// every thread needs to re-acquire the locks it holds
}
}.start
}
}
Distributed ExecutionService
In 2.12, a distributed execution service was added. The new service is implemented as a protocol and is used
via org.jgroups.blocks.executor.ExecutionService.
ExecutionService talks to the executing protocol via events. The main abstraction is an implementation of
java.util.concurrent.locks.ExecutorService. All methods are supported. The restrictions are however that
the Callable or Runnable must be Serializable, Externalizable or Streamable. Also the result produced
from the future needs to be Serializable, Externalizable or Streamable. If the Callable or Runnable are not
then an IllegalArgumentException is immediately thrown. If a result is not then a NotSerializableException
with the name of the class will be returned to the Future as an exception cause.
Below is an example of how ExecutionService is typically used:
// locking.xml needs to have a locking protocol
JChannel ch=new JChannel("/home/bela/executing.xml");
ExecutionService exec_service =new ExecutionService(ch);
ch.connect("exec-cluster");
Future<Value> future = exec_service.submit(new MyCallable());
try {
Value value = future.get();
// Do something with value
}
catch (InterruptedException e) {
e.printStackTrace();
}
catch (ExecutionException e) {
e.getCause().printStackTrace();
}
In the example, we create a channel, then an ExecutionService, then connect the channel. Then we submit
our callable giving us a Future. Then we wait for the future to finish returning our value and do something
with it. If any exception occurs we print the stack trace of that exception.
JGroups includes a demo (org.jgroups.demos.ExecutionServiceDemo), which can be used to interactively
experiment with a distributed sort algorithm and performance. This is for demonstration purposes and
performance should not be assumed to be better than local.
ExecutionServiceDemo -h dumps all command line options.
Currently (March 2011), there is 1 protocol which provide executions:
CENTRAL_EXECUTOR. The executing protocol has to be placed at or
towards the top of the stack (close to the channel).
libjgroups-java-2.12.2.Final.orig/doc/manual/en/modules/eventlist.xml 0000644 0001750 0001750 00000000123 11647260573 025406 0 ustar moeller moeller List of events
libjgroups-java-2.12.2.Final.orig/doc/manual/en/modules/installation.xml 0000644 0001750 0001750 00000047333 11647260573 026110 0 ustar moeller moeller Installation and ConfigurationThe installation refers to version 2.8 of JGroups. Refer to the installation
instructions that are shipped with JGroups for details.Note that these instructions are also available in the
JGroups distribution (INSTALL.HTML).
JGroups comes in a binary and a source version: the binary
version is JGroups-2.x.x.bin.zip, the source
version is JGroups-2.x.x.src.zip. The binary
version contains the JGroups JAR file, plus a number of JARs needed
by JGroups. The source version contains all source files, plus
several JAR files needed by JGroups, e.g. ANT to build JGroups from
source.
RequirementsJGroups 2.5 requires JDK 1.5 or higher. Version 2.9 requires JDK 1.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)Installing the binary distributionThe binary version containsjgroups-all.jar: the JGroups library including the
demosCREDITS: list of contributorsINSTALL.html: this filelog4j.jar. This JAR is optional, for example if JDK logging is used, we don't need it. Note that
commons-logging is not a requirement any more since version 2.8.Place the JAR files somewhere in your CLASSPATH, and you're ready to start using JGroups.
Installing the source distributionThe source version consists of the following directories and files:src: the sourcestest: unit and stress testsconf: configuration files needed by JGroups, plus default protocol stack definitionsdoc: documentationlib: various JARs needed to build and run
JGroups:Ant
JARs: used to build JGroups. If you already have Ant installed, you won't need these files
xalan.jar: to format the output of
the JUnit tests using an XSLT converter to HTML
log4j.jaretcBuilding JGroups (source distribution only)Unzip the source distribution, e.g. unzip
JGroups-2.x.x.src.zip. This will create the JGroups-2.x.x
directory (root directory) under the current directory.cd to the root directoryModify build.properties if you want to use a Java
compiler other than javac (e.g. jikes), or if you want to change the
interface JGroups uses for sending and receiving messagesOn UNIX systems use build.sh, on Windows
build.bat:
$>
./build.sh compileThis will compile all Java files (into the classes directory).
To generate the JARs:
$> ./build.sh jarThis will generate the following JAR files in the
dist directory:
jgroups-core.jar
- the core JGroups library without unit tests and demos
jgroups-all.jar
- the complete JGroups library including demos and unit tests
The
CLASSPATH
now has to be set accordingly: the following directories and/or JARs have to be included:
<JGroups
rootdir>/classes<JGroups
rootdir>/confAll needed JAR files in
<JGroups
rootdir>/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 javadoc
and the Javadoc documentation will
be generated in the
dist/javadoc
directory
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 your home
directory.
For more details on Ant see
.
Testing your SetupTo see whether your system can find the JGroups classes,
execute the following command:
java org.jgroups.Version
or (from JGroups 2.2.8 on)
java -jar jgroups-all.jar
You should see the following output (more or less) if the
class is found:
[mac] /Users/bela/JGroups$ java org.jgroups.Version
Version: 2.8.0.GA
CVS: $Id: installation.xml,v 1.10 2010/04/30 14:27:39 vlada Exp $
Running a Demo ProgramTo test whether JGroups works okay on your machine, run
the following command twice:
java org.jgroups.demos.Draw
2 whiteboard windows should appear as shown in .
Screenshot of 2 Draw instances
Both windows should show 2 in their title bars. This means that the two instances found each other
and formed a group.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.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.
Using IP Multicasting without a network connectionSometimes 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).It doesn't work !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 -mcast_addr 224.10.10.10 -port 5555
Then start McastSenderTest:
java org.jgroups.tests.McastSenderTest -mcast_addr 224.10.10.10 -port 5555
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.
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.jgroups.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.jgroups.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.jgroups.tests.McastReceiverTest1_4 -mcast_addr 228.8.8.8
-bind_addr 192.168.1.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):..."
.
Problems with IPv6Another 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
java.net.preferIP4Stack=true
property,
e.g.
java -Djava.net.preferIPv4Stack=true org.jgroups.demos.Draw -props /home/bela/udp.xml
JDK 1.4.1 uses IPv6 by default, although is has a dual stack, that is, it also supports IPv4.
Here's
more details on the subject.
Wiki
There is a wiki which lists FAQs and their solutions at
. It is frequently updated and a useful companion
to this user's guide.
I have discovered a bug !If you think that you discovered a bug, submit a bug report
on
JIRA
or send
email to javagroups-developers 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 machinesSmall program that reproduces the bugSupported classesJGroups project has been around since 2001. 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.Experimental
${Experimental}
Unsupported
${Unsupported}
libjgroups-java-2.12.2.Final.orig/doc/manual/en/modules/overview.xml 0000644 0001750 0001750 00000024035 11647260573 025247 0 ustar moeller moeller Overview
Group communication uses the terms group and member. Members are part
of a group. In the more common terminology, a member is a node and a group is a
cluster. We use these terms interchangeably.
A node is a process, residing on some host. A cluster can have one or more nodes belonging to it. There
can be multiple nodes on the same host, and all may or may not be part of the same cluster.
JGroups is toolkit for reliable group
communication. Processes can join a group, send messages to all
members or single members and receive messages from members in the
group. The system keeps track of the members in every group, and
notifies group members when a new member joins, or an existing
member leaves or crashes. A group is identified by its name. Groups
do not have to be created explicitly; when a process joins a
non-existing group, that group will be created automatically. Member
processes of a group can be located on the same host, within the
same LAN, or across a WAN. A member can be part of multiple
groups.The architecture of JGroups is shown in .The architecture of JGroupsIt consists of 3 parts: (1) the Channel used by
application programmers to build reliable group communication
applications, (2) the building blocks, which are layered on top of
the channel and provide a higher abstraction level and (3) the
protocol stack, which implements the properties specified for a
given channel.
This document describes how to install and use JGroups, ie. the Channel API and the
building blocks. The targeted audience is application programmers who want to use JGroups to
build reliable distributed programs that need group communication.
A channel is connected to a protocol stack. Whenever the
application sends a message, the channel passes it on to the
protocol stack, which passes it to the topmost protocol. The
protocol processes the message and the passes it on to the protocol
below it. Thus the message is handed from protocol to protocol until
the bottom (transport) protocol puts it on the network. The same happens in the
reverse direction: the transport protocol listens for
messages on the network. When a message is received it will be
handed up the protocol stack until it reaches the channel. The
channel stores the message in a queue until the application consumes it.
When an application connects to the channel, the protocol
stack will be started, and when it disconnects the stack will be
stopped. When the channel is closed, the stack will be destroyed,
releasing its resources.The following three sections give an overview of channels,
building blocks and the protocol stack.ChannelTo join a group and send messages, a process has to create a
channel and connect to it using the group
name (all channels with the same name form a group). The channel
is the handle to the group. While connected, a member may send and
receive messages to/from all other group members. The client
leaves a group by disconnecting from the channel. A channel can be
reused: clients can connect to it again after having
disconnected. However, a channel allows only 1 client to be
connected at a time. If multiple groups are to be joined, multiple
channels can be created and connected to. A client signals that it
no longer wants to use a channel by closing it. After this
operation, the channel cannot be used any longer.Each channel has a unique address. Channels always know who
the other members are in the same group: a list of member
addresses can be retrieved from any channel. This list is called a
view. A process can select an address from
this list and send a unicast message to it (also to itself), or it
may send a multicast message to all members of the current
view (also including itself). Whenever a process joins or leaves a group, or when a
crashed process has been detected, a new view
is sent to all remaining group members. When a member process is
suspected of having crashed, a suspicion
message is received by all non-faulty members. Thus,
channels receive regular messages, view messages and suspicion
messages. A client may choose to turn reception of views and
suspicions on/off on a channel basis.Channels are similar to BSD sockets: messages are stored in
a channel until a client removes the next one
(pull-principle). When no message is currently available, a client
is blocked until the next available message has been
received.
Note that the push approach to receiving messages and views is preferred. This involves setting a Receiver
in the channel and getting callbacks invoked by JGroups whenever a message or view is received.
The current pull approach (JChannel.receive() method) has been deprecated in 2.8 and will be removed in 3.0.
There is currently only one implementation of Channel: JChannel.
The properties of a channel are typically defined in an XML file, but JGroups also allows for configuration
through simple strings, URIs, DOM trees or even programmatically.
The Channel API and its related classes is described in
.Building BlocksChannels are simple and primitive. They offer the bare
functionality of group communication, and have on purpose been
designed after the simple model of BSD sockets, which are widely
used and well understood. The reason is that an application can
make use of just this small subset of JGroups, without having
to include a whole set of sophisticated classes, that it may not
even need. Also, a somewhat minimalistic interface is simple to
understand: a client needs to know about 12 methods to be able to
create and use a channel (and oftentimes will only use 3-4 methods
frequently).Channels provide asynchronous message sending/reception,
somewhat similar to UDP. A message sent is essentially put on the
network and the send() method will return immediately. Conceptual
requests, or responses
to previous requests, are received in undefined order, and the
application has to take care of matching responses with
requests.Also, an application has to actively
retrieve messages from a channel (pull-style);
it is not notified when a message has been received. Note that
pull-style message reception often needs another thread of
execution, or some form of event-loop, in which a channel is
periodically polled for messages.JGroups offers building blocks that provide more
sophisticated APIs on top of a Channel. Building blocks either
create and use channels internally, or require an existing channel
to be specified when creating a building block. Applications
communicate directly with the building block, rather than the
channel. Building blocks are intended to save the application
programmer from having to write tedious and recurring code,
e.g. request-response correlation.Building blocks are described in .The Protocol StackThe protocol stack
containins a number of protocol layers in a bidirectional
list. All messages sent and received over the channel have to pass
through all protocols. Every layer may modify, reorder, pass
or drop a message, or add a header to a message. A fragmentation
layer might break up a message into several smaller messages,
adding a header with an id to each fragment, and re-assemble the
fragments on the receiver's side.The composition of the protocol stack, i.e. its layers, is
determined by the creator of the channel: an XML file
defines the layers to be used (and the parameters for each
layer). The configuration is used to create the
stack, depending on the protocol names given in the
property.Knowledge about the protocol stack is not necessary when
only using channels in an
application. However, when an application wishes to ignore the
default properties for a protocol stack, and configure their own
stack, then knowledge about what the individual layers are
supposed to do is needed. Although it is syntactically possible to
stack any layer on top of each other (they all have the same
interface), this wouldn't make sense semantically in most
cases.Header
A header is a custom bit of information that can be added to each message. JGroups uses headers extensively,
for example to add sequence numbers to each message (NAKACK and UNICAST), so that those messages can be
delivered in the order in which they were sent.
Event
Events are means by which JGroups protcols can talk to each other. Contrary to Messages, which travel over the
network between group members, events only travel up and down the stack.
libjgroups-java-2.12.2.Final.orig/doc/manual/en/modules/protocols.xml 0000644 0001750 0001750 00000152532 11647260573 025431 0 ustar moeller moeller
List of Protocols
This section is work in progress; we strive to update the documentation as we make changes to the code.
The most important properties are described on the
wiki. The idea is that users take one
of the predefined configurations (shipped with JGroups) and make only minor changes to it.
For each protocol define:Properties providedRequired servicesProvided servicesBehaviorTransportUDP
${UDP}
TCP
${TCP}
TUNNEL
${TUNNEL}
Initial membership discovery
The task of the discovery is to find an initial membership, which is used to determine the current
coordinator. Once a coordinator is found, the joiner sends a JOIN request to the coord.
PING
${PING}
FILE_PING
This uses a shared directory into which all members write their addresses. New joiners read all addresses
from this directory (which needs to be shared, e.g. via NFS or SMB) and ping each of the elements of
the resulting set of members. When a member leaves, it deletes its corresponding file.
FILE_PING can be used instead of GossipRouter in cases where no external process is desired.
${PING}
JDBC_PING
This uses a shared Database into which all members write their addresses. New joiners read all addresses
from this Database and ping each of the elements of the resulting set of members. When a member leaves,
it deletes its corresponding record.
JDBC_PING is an alternative to S3_PING by using Amazon RDS instead of S3.
${JDBC_PING}
TCPPING
${TCPPING}
TCPGOSSIP
${TCPGOSSIP}
MPING
${MPING}
BPING
BPING uses UDP broadcasts to discover other nodes. The default broadcast address (dest) is
255.255.255.255, and should be replaced with a subnet specific broadcast, e.g. 192.168.1.255.
${BPING}
S3_PING
This uses an Amazon S3 bucket into which all members write their addresses. New joiners read all addresses
from this bucket and ping each of the elements of the resulting set of members. When a member leaves, it
deletes its corresponding file.
S3_PING is primarily meant to be used on Amazon EC2 where multicast traffic is not allowed and
no external process (GossipRouter) is desired. When Amazon RDS is preferred over S3, or if a shared
database is used, an alternative is to use JDBC_PING.
${S3_PING}
Merging after a network partitionMERGE2
${MERGE2}
Failure Detection
The task of failure detection is to probe members of a group and see whether they are alive. When a member is
suspected (= deemed dead), then a SUSPECT message is sent to all nodes of the cluster. It is not the task of the
failure detection layer to exclude a crashed member (this is done by the group membership protocol, GMS), but
simply to notify everyone that a node in the cluster is suspected of having crashed.
FDFailure detection based on heartbeat messages. If reply is not
received without timeout ms, max_tries times, a member is declared
suspected, and will be excluded by GMS
Each member send a message containing a "FD" - HEARTBEAT header to
its neighbor to the right (identified by the ping_dest address). The
heartbeats are sent by the inner class Monitor. When the neighbor
receives the HEARTBEAT, it replies with a message containing a "FD" -
HEARTBEAT_ACK header. The first member watches for "FD" - HEARTBEAT_ACK
replies from its neigbor. For each received reply, it resets the
last_ack timestamp (sets it to current time) and num_tries counter (sets
it to 0). The same Monitor instance that sends heartbeats whatches the
difference between current time and last_ack. If this difference grows
over timeout, the Monitor cycles several more times (until max_tries) is
reached) and then sends a SUSPECT message for the neighbor's address.
The SUSPECT message is sent down the stack, is addressed to all members,
and is as a regular message with a FdHeader.SUSPECT header.
${FD}
FD_ALLFailure detection based on simple heartbeat protocol. Every member periodically multicasts a
heartbeat.
Every member also maintains a table of all members (minus itself). When data or a heartbeat from P are
received, we reset the timestamp for P to the current time.
Periodically, we check for expired members, and suspect those.
Example: <FD_ALL interval="3000" timeout="10000"/>
In the example above, we send a heartbeat every 3 seconds and suspect members if we haven't received a
heartbeat (or traffic) for more than 10 seconds. Note that since we check the timestamps every
'interval'
milliseconds, we will suspect a member after roughly 4 * 3s == 12 seconds. If we set the timeout to
8500,
then we would suspect a member after 3 * 3 secs == 9 seconds.
${FD_ALL}
FD_SIMPLEFD_PING
FD_PING uses a script or command that is
run with 1 argument (the host to be pinged) and needs to return 0
(success) or 1 (failure). The default command is /sbin/ping (ping.exe on
Windows), but this is user configurable and can be replaced with any
user-provided script or executable.
${FD_PING}
FD_ICMP
Uses InetAddress.isReachable() to
determine whether a host is up or not. Note that this is only available in
JDK 5, so reflection is used to determine whether InetAddress provides
such a method. If not, an exception will be thrown at protocol
initialization time.
The problem with InetAddress.isReachable()
is that it may or may not use ICMP in its implementation ! For example, an
implementation might try to establish a TCP connection to port 9 (echo
service), and - if the echo service is not running - the host would be
suspected, although a real ICMP packet would
not
have
suspected the host ! Please check your JDK/OS combo before running this
protocol.
PropertiesNameDescriptionbind_addrThe network interface to be used for sending ICMP
packets, e.g.
bind_addr="192.16.8.0.2"