Package regionQueue

This example uses GemFire Regions to build a distributed queue.

See:
Description

Class Summary

ClientQueue	The client side of a distributed queue.
RegionQueue	A queue whose contents are stored in a GemFire Region.
ServerQueue	The server side of a distributed queue.

Exception Summary

RegionQueueException

A runtime exception thrown by a RegionQueue when an unexpected cache error is encountered.

Package regionQueue Description

This example uses GemFire Regions to build a distributed queue. The elements of the queue reside in a RegionQueue are are made available to other VM via a ServerQueue. A ClientQueue uses the GemFire BridgeServer to communicate with the ServerQueue. The architecture of the distributed queue is described in the below diagram:

Underlying the distributed queue is a RegionQueue that provides the standard BlockingQueue interface which FIFO (first in, first out) semantics and a bounded size (capacity). The RegionQueue stores the queue's elements in a GemFire Region. The region's keys are monotonically increasing Long objects that preserve the order in which the elements were added to the queue. The values in the region are the elements of the queue. The region queue uses Java synchronization to ensure that the state of the queue is kept consistent while it is accessed by multiple threads.

Because the elements of the queue are stored in a GemFire Region, the queue can take advantage of distributed caching to ensure high availability of the data. For instance, if the underlying region is a replicate, another VM can serve as a "backup" for the queue. Alternatively, the region could be configured to write its contents to a disk file. If the VM hosting the queue were to crash, the queue could be recovered from this file.

The RegionQueue is only a building blocking of a distributed queue. A ServerQueue provides remote access to a RegionQueue via a GemFire Region referred to as the "communication region". The communication region uses a CacheLoader and a CacheWriter to access the RegionQueue. That is, when a get is performed on the communication region, its CacheLoader is invoked. The CacheLoader, in turn, removes an element from the queue. The dequeued element is propagated back to the requestor through the communication region. The communication region doesn't really cache any data. The data just passed through on its way to its destination.

A ClientQueue uses uses the GemFire cache bridge to perform point-to-point communcation with one or more ServerQueues. The client and server use a special region-based communications prototcol to implement the remote queue operations. For instance, the take operation performs a get on the communication region which is, in turn, propagated to the ServerQueue via a BridgeLoader. On the server side, the get on the communication region invokes a CacheLoader that performs a take on the underlying RegionQueue. The region API's callback arguments are used to pass information such as the amount of time to wait for an element to become available from the client to the server. CacheLoaderExceptions and CacheWriterExceptions are used to propagate information from the server back to the client.

The distributed region-based queue relies on the bridge server's failover capabilities to provide high availability. The user can start multiple ServerQueues that host their queue on different ports. A ClientQueue can be configured with multiple host/port configurations. When the ClientQueue is started it will interact with the first ServerQueue. (That is, the distributed queue uses the "sticky" load balancing policy.) If the first ServerQueue should fail, the ClientQueue will automatically fail over to the second queue and begin interacting with it. If the ServerQueues' underlying RegionQueue is configured to be a replicate with "distributed ack" scope, all ServerQueues will have the same queue data. Thus, when the ClientQueue fails over, no data is lost. Also note that the RegionQueue must recompute some VM-local (that is, non-distributed) state before the queue's contents can be served.