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:

$ java -Dgemfire.mcast-port=10412 regionQueue.ServerQueue myqueue 10 12345

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:

$ java -Dgemfire.mcast-port=10412 regionQueue.ClientQueue myqueue localhost:12345

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 .

In one shell:

$ java regionQueue.ServerQueue myqueue 10 12345

In another shell:

$ java regionQueue.ServerQueue myqueue 10 12346

In a third shell:

$ java regionQueue.ClientQueue myqueue localhost:12345 localhost:12346

If the first ServerQueue exits or is killed after the client populates the queue, the queue's elements will be fetched from the second ServerQueue.

Follow these steps to stop the GemFire locator and close the example sessions:

  1. To end the server applications, press enter in each server session.
  2. End the client application by entering exit in the client session.
  3. Close all open sessions by entering exit in each of them.