JBoss.orgCommunity Documentation

Reliable group communication with JGroups 3.x

by Bela Ban (Red Hat, Inc.) and Vladimir Blagojevic (Red Hat, Inc.)

August 2013

Preface
1. Overview
1.1. Channel
1.2. Building Blocks
1.3. The Protocol Stack
2. Installation and Configuration
2.1. Requirements
2.2. Structure of the source version
2.3. Building JGroups (source distribution only)
2.4. Logging
2.4.1. log4j2
2.4.2. log4j
2.4.3. JDK logging (JUL)
2.4.4. Support for custom logging frameworks
2.5. Testing your Setup
2.6. Running a Demo Program
2.7. Using IP Multicasting without a network connection
2.8. It doesn't work !
2.9. Problems with IPv6
2.10. Wiki
2.11. I have discovered a bug !
2.12. Supported classes
2.12.1. Experimental
2.12.2. Unsupported
3. API
3.1. Utility classes
3.1.1. objectToByteBuffer(), objectFromByteBuffer()
3.1.2. objectToStream(), objectFromStream()
3.2. Interfaces
3.2.1. MessageListener
3.2.2. MembershipListener
3.2.3. Receiver
3.2.4. ReceiverAdapter
3.2.5. ChannelListener
3.3. Address
3.4. Message
3.5. Header
3.6. Event
3.7. View
3.7.1. ViewId
3.7.2. MergeView
3.8. JChannel
3.8.1. Creating a channel
3.8.2. Giving the channel a logical name
3.8.3. Generating custom addresses
3.8.4. Joining a cluster
3.8.5. Joining a cluster and getting the state in one operation
3.8.6. Getting the local address and the cluster name
3.8.7. Getting the current view
3.8.8. Sending messages
3.8.9. Receiving messages
3.8.10. Receiving view changes
3.8.11. Getting the group's state
3.8.12. Disconnecting from a channel
3.8.13. Closing a channel
4. Building Blocks
4.1. MessageDispatcher
4.1.1. RequestOptions
4.1.2. Requests and target destinations
4.1.3. Example
4.2. RpcDispatcher
4.2.1. Example
4.2.2. Response filters
4.3. Asynchronous invocation in MessageDispatcher and RpcDispatcher
4.4. ReplicatedHashMap
4.5. ReplCache
4.6. Cluster wide locking
4.6.1. Locking and merges
4.7. Cluster wide task execution
4.8. Cluster wide atomic counters
4.8.1. Design
5. Advanced Concepts
5.1. Using multiple channels
5.2. Sharing a transport between multiple channels in a JVM
5.3. Transport protocols
5.3.1. Message bundling
5.3.2. UDP
5.3.3. TCP
5.3.4. TUNNEL
5.4. The concurrent stack
5.4.1. Overview
5.4.2. Elimination of up and down threads
5.4.3. Concurrent message delivery
5.4.4. Scopes: concurrent message delivery for messages from the same sender
5.4.5. Out-of-band messages
5.4.6. Replacing the default and OOB thread pools
5.4.7. Sharing of thread pools between channels in the same JVM
5.5. Using a custom socket factory
5.6. Handling network partitions
5.6.1. Merging substates
5.6.2. The primary partition approach
5.6.3. The Split Brain syndrome and primary partitions
5.7. Flushing: making sure every node in the cluster received a message
5.8. Large clusters
5.8.1. Reducing chattiness
5.9. STOMP support
5.10. Bridging between remote clusters
5.10.1. Views
5.10.2. Configuration
5.11. Relaying between multiple sites (RELAY2)
5.11.1. Relaying of multicasts
5.11.2. Relaying of unicasts
5.11.3. Invoking RPCs across sites
5.11.4. Configuration
5.12. Daisychaining
5.12.1. Traditional N-1 approach
5.12.2. Daisychaining approach
5.12.3. Switch usage
5.12.4. Performance
5.12.5. Configuration
5.13. Tagging messages with flags
5.14. Performance tests
5.14.1. MPerf
5.15. Ergonomics
5.16. Supervising a running stack
5.17. Probe
5.18. Determining the coordinator and controlling view generation
5.19. ForkChannels: light-weight channels to piggy-back messages over an existing channel
5.19.1. Configuration
5.19.2. Creation of fork channels
6. Writing protocols
6.1. Writing user defined headers
7. List of Protocols
7.1. Properties availabe in every protocol
7.2. Transport
7.2.1. UDP
7.2.2. TCP
7.2.3. TUNNEL
7.3. Initial membership discovery
7.3.1. Discovery
7.3.2. PING
7.3.3. TCPPING
7.3.4. TCPGOSSIP
7.3.5. MPING
7.3.6. FILE_PING
7.3.7. JDBC_PING
7.3.8. BPING
7.3.9. RACKSPACE_PING
7.3.10. S3_PING
7.3.11. GOOGLE_PING
7.3.12. SWIFT_PING
7.3.13. AWS_PING
7.3.14. PDC - Persistent Discovery Cache
7.4. Merging after a network partition
7.4.1. MERGE2
7.4.2. MERGE3
7.5. Failure Detection
7.5.1. FD
7.5.2. FD_ALL
7.5.3. FD_ALL2
7.5.4. FD_SOCK
7.5.5. FD_PING
7.5.6. FD_HOST
7.5.7. VERIFY_SUSPECT
7.6. Reliable message transmission
7.6.1. pbcast.NAKACK
7.6.2. NAKACK2
7.6.3. UNICAST
7.6.4. UNICAST2
7.6.5. UNICAST3
7.6.6. RSVP
7.7. Message stability
7.7.1. STABLE
7.8. Group Membership
7.8.1. pbcast.GMS
7.9. Flow control
7.9.1. FC
7.9.2. MFC and UFC
7.10. Fragmentation
7.10.1. FRAG and FRAG2
7.11. Ordering
7.11.1. SEQUENCER
7.11.2. Total Order Anycast (TOA)
7.12. State Transfer
7.12.1. pbcast.STATE_TRANSFER
7.12.2. StreamingStateTransfer
7.12.3. pbcast.STATE
7.12.4. STATE_SOCK
7.12.5. BARRIER
7.13. pbcast.FLUSH
7.14. Misc
7.14.1. Statistics
7.14.2. Security
7.14.3. COMPRESS
7.14.4. SCOPE
7.14.5. RELAY
7.14.6. RELAY2
7.14.7. STOMP
7.14.8. DAISYCHAIN
7.14.9. RATE_LIMITER
7.14.10. Locking protocols
7.14.11. CENTRAL_EXECUTOR
7.14.12. COUNTER
7.14.13. SUPERVISOR
7.14.14. FORK