GemStone® GemFire Enterprise®

Java Caching API Programming Example

The cacheRunner example performs distributed caching operations based on user commands. The example is located in the GemFire installation under examples/dist/cacheRunner.

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/cacheRunner 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/ file to your examples/dist/cacheRunner directory and edit it as needed.

The application takes a cache configuration file in input. You can use the example configuration files provided in the example directory and you can create and test your own. This sample loads the examples/cacheRunner/cache.xml file for cache initialization:

       java cacheRunner.CacheRunner cache.xml

Once started, the application allows you to perform most of the caching activities that are available through the Java API (the program's "help" lists all possible commands). With its free-form approach, this cacheRunner program allows you to to explore the various caching models. The following examples guide you through three basic cache applications, but we encourage you to try your own.

Example 1 - Exploring Data Distribution and Replication

This first example runs two Java applications in one distributed system. The applications define the same cache regions: a root region, named "root", with three subregions: rlocal (no distribution), rdistnoack (distribution with pull model), and rglobalreplication (complete replication of data).

To try out cacheRunner with these configuration files, set up two shells with the same environment settings and cd to the examples/dist/cacheRunner directory. You may need to change how these processes find each other to avoid conflicting with processes that are already running. To do so, copy from the defaultConfigs directory of the installation and modify the mcast-port setting.

In both shells, run:

       java cacheRunner.CacheRunner cache.xml

This starts the applications and initializes their caches according to cache.xml.

The program's help lists the available operations. In one shell, add some entries to the three subregions, rlocal, rdistnoack, and rglobalreplication. From the other shell, list the region contents and note that rglobalreplication is already equivalent to its counterpart in the first shell. Still in the second shell, try to get entries that are already defined in the first shell and note the result. Add some entries to the regions in the second shell and note the effects on the regions in the first shell.

Enter quit in both shells to shut down cacheRunner for the next example.

Example 2 - Persisting Data to Disk

The backup_cache.xml file configures a GemFire cache region, root, that backs up its contents to disk. When data is placed into this region, it is scheduled for an asynchronous write to disk. You can run this example from the examples/dist/cacheRunner directory as follows:

       java cacheRunner.CacheRunner backup_cache.xml

After adding several entries to the root region using the put command, you can exit the program. Upon restarting with the same XML configuration file, you can obtain the values of the entries you added using the get command. The entries should have the values you put in the previous invocation of the cacheRunner example.

Enter quit to shut down cacheRunner.

The backup files are in the cacheRunner subdirectory BackupDirectory. If you want to try out the rollover of backup files, edit this line in the backup_cache.xml to set the file size limit to 1 megabyte:

       <disk-write-attributes roll-oplogs ="true" max-oplog-size="1">

Then do puts until you create more than a megabyte of data. Alternatively, you can enter forceRolling at the command prompt. The active backup file is BACKUP_root_n.olg, where n is a sequence number. When the file rolls over, the data is archived to BACKUP_root.db and the current file is replaced by a new file with the next sequence number. To save all the backup files, rather than deleting the old ones, turn off rolling in the backup_cache.xml:

       <disk-write-attributes roll-oplogs ="false" max-oplog-size="1">
Example 3 - Querying and Indexing

The queryPortfolios.xml file configures a GemFire cache region with the Portfolios region that is discussed in the Querying and Indexing chapter of the GemFire Enterprise Developer's Guide. The accompanying script file,, can be used to run most of the queries that are listed in that chapter. To run those queries against the queryPortfolios.xml data, execute this command:

       java cacheRunner.CacheRunner queryPortfolios.xml <

This lists every query and its results, then exits.

You can run your own queries against the same data by starting cacheRunner like this:

       java cacheRunner.CacheRunner queryPortfolios.xml 

For information on creating queries and indexes interactively, see the program help or the examples in the file.

Close the open sessions by entering exit in each of them.