JGroups configuration is a complex area that goes well beyond the scope of this document. Users interested in exploring the details are encouraged to visit the JGroups website at http://www.jgroups.org as well as the JGroups wiki page at jboss.com.
The jgroups-stacks.xml
file found in the
org.hibernate.cache.jbc2.builder
package
in the hibernate-jbosscache2.jar
provides a good
set of standard JGroups configurations; these should be suitable for
most needs. If you need to create your own configuration set, we
recommend that you start with this file as a base.
The JGroups transport refers to the mechanism JGroups uses for sending messages to the group members. Choosing which transport to use is the main JGroups-related decision users will need to make. There are three transport types:
UDP -- uses UDP multicast for transmitting
messages to all members of the group. Multicast is efficient for the
Second Level Cache use case, particularly with larger clusters,
since maintaining cache consistency means many messages need to
be sent to all members. UDP-based channel configurations are
used in the JBoss Cache configurations in the standard
jbc2-configs.xml
file that ships with
Hibernate.
TCP -- uses multiple TCP unicasts for transmitting messages to all members of the group. Less efficient for the Second Level Cache use case, particularly as clusters get larger, i.e. over 4 to 6 nodes. However, in some network environments UDP multicast is not an option, in which case TCP is available.
If a TCP-based channel is used, there are a couple of options available for how a channel "discovers" the other members in the group when it first starts.
TCP + TCPPING -- here a static list of all the possible nodes in the cluster must be provided. The TCPPING "discovery" protocol uses that static list to probe for available peers, using TCP messages. The downside here is the need to provide and maintain the static list. The upside, for multicast-averse environments, is all communication uses TCP.
TCP + MPING -- here the MPING "discovery" protocol uses UDP multicast to probe for available peers; once they are detected all regular message traffic uses TCP. The downside here, for the multicast-averse, is that multicast is used. The upside is there is no need for a static configuration of all possible peers.
The TCP-based configurations in the
jgroups-stacks.xml
file found in
hibernate-jbosscache2.jar
all use
TCP + MPING. This is because there is no way for the
Hibernate authors to provide a meaningful static
configuration for TCPPING. If you want to use TCP + TCPPING
you will need to provide your own JGroups configuration file.
TUNNEL -- a specialized protocol designed for cases where cluster members need to communicate across firewalls. See the JGroups documentation for details.
By default the Second Level Cache will use JGroups configurations
found in the jgroups-stacks.xml
file included in
hibernate-jbosscache2.jar
. Following are their
names and a brief description of each:
udp
UDP multicast-based config; appropriate for all cache types. Includes JGroups flow control (FC) which is needed for caches that send significant numbers of asynchronous messages (i.e. timestamp caches and entity/collection caches configured for replication instead of invalidation). If you're not sure and want to use UDP multicast, this is the best choice.
udp-sync
UDP multicast-based config that omits JGroups flow control (FC). Optimal for caches that send little or no asynchronous messages, i.e. entity/collection caches configured for invalidation. Unsuitable for timestamp caches or entity/collection caches configured for replication.
tcp
TCP-based config with UDP multicast discovery (MPING).
Includes JGroups flow control (FC); see udp
above for the significance of that.
tcp-sync
TCP-based config with UDP multicast discovery (MPING).
Omits JGroups flow control (FC); see
udp-sync
above for the significance of that.
tunnel
Uses a specialized protocol designed for cases where cluster members need to communicate across firewalls. See the JGroups documentation for details.