regionQueue

GemStone® GemFireTM 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 bridge 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.

Once your environment is set, change to the examples/dist/regionQueue directory 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, copy the defaultConfigs/gemfire.properties file to your examples/dist/regionQueue directory and edit it as needed.

The ServerQueue class has a main method that creates a ServerQueue whose contents is 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 below command line creates a ServerQueue named myqueue with a capacity of 10 elements hosted on port 12345.

$ java 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 below command line creates a ClientQueue named myqueue whose server is running on port 12345 of the localhost.

$ java regionQueue.ClientQueue myqueue localhost:12345

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

test> 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 kill after the client populates the queue, the queue's elements will fetched from the seconds ServerQueue.