regionQueue

GemStone® GemFire Enterprise®

Queuing Implemented With Distributed Caching

The regionQueue example demonstrates how a distributed
queue could be implemented using GemFire's distributed caching API.
The example is located in the GemFire installation under
examples/dist/regionQueue.

There are three components to the region queue example. The RegionQueue class implements
a queue whose contents is stored in a GemFire Region.
The ServerQueue class
provides remote access to a RegionQueue via GemFire's
cache server. The ClientQueue class remotely
accesses a ServerQueue and can be configured to
automatically fail over to a backup ServerQueue to
provide high availability. A discussion of the design and
implementation of distributed region queues can be found here.

In every shell used to run this example application, configure your
environment according to the instructions provided in
examples/EnvSetup.html. This example uses three shells.

Once your environment is set, change to the
examples/dist/regionQueue directory in each shell to run the
application. You may wish to configure the example to run with
non-default connection properties (to use a unique mcast-port, for
example). To do this, start regionQueue.ServerQueue and regionQueue.ClientQueue with the -Dgemfire.mcast-port= option, as shown for each of the invocations using unique multicast ports.

The ServerQueue class has a main method
that creates a ServerQueue whose contents are hosted on a
given port.

$ java regionQueue.ServerQueue
** Missing queue name
usage: java regionQueue.ServerQueue name capacity port
name Name of distributed queue
capacity Maximum number of elements in the queue
port Port on which clients connect
Hosts a Server Queue

Executing the following command line creates a ServerQueue
named myqueue with a capacity of 10 elements hosted on
port 12345.

$ java regionQueue.ServerQueue myqueue 10 12345

If you need to use a unique multicast port,
execute the command using the -Dgemfire option:

The program will remain active, serving requests from clients,
until the ENTER key is pressed.

The ClientQueue class has a main method
that creates a ClientQueue that accesses a
ServerQueue that runs on a given host and port.

$ java regionQueue.ClientQueue
** Missing queue name
usage: java regionQueue.ClientQueue name (host:port)+
name Name of distributed queue
host:port Host and port of server queue
Creates a client queue and allows the user to interact with it

Executing the following command line creates a ClientQueue
named myqueue whose server is running on port 12345 of
the localhost.

$ java regionQueue.ClientQueue myqueue localhost:12345

If you used a unique multicast port for the server queue,
you need to use the same port for the client queue:

The ClientQueue program prompts the user to enter a
command that manipulates the remote ServerQueue.

myqueue> help
Available commands are:
offer string [timeout] Adds an element to the queue
timeout Seconds to wait for room in queue
put string Waits until an element can be added to the queue
poll [timeout] Removes an available element from the queue
timeout Seconds to wait for element
take Waits for an element queue to be available before
removing it.
peek Returns the element at the head of queue, but doesn't
remove it.
toArray Prints the entire contents of the queue
size Prints the size of the queue
isEmpty Prints whether or not the queue is empty
remaining Prints number of empty elements in the queu
exit Exits this program

High availability of distributed region queues can be demonstrated
by starting two ServerQueues and a
ClientQueue that communicates with both.

If you are running an evaluation copy of the product, you might not have enough licenses to run this high availability example .