cacheRunner.README.html Maven / Gradle / Ivy
vFabric™ GemFire®
cacheRunner
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/gemfire.properties 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 gemfire.properties 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 max-oplog-size to 1 megabyte:
<disk-store name="DEFAULT" auto-compact="true" max-oplog-size="20" queue-size="10000000" time-interval="15000">
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 BACKUPds1_n.crf and BACKUPds1_n.drf, where
n is a
sequence number. When the file rolls over, 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 auto-compact in the backup_cache.xml:
<disk-store name="DEFAULT" auto-compact="false" max-oplog-size="20" queue-size="10000000" time-interval="15000">
This backup example won't work if you try to run with multiple java VMs because they will each try to write to the same disk files. If you want to try using replication and persistence, you will need to copy backup_cache.xml and change the directory specified in the disk-dir element. You can then start a second VM using the new backup_cache.xml file.
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 User's Guide. The accompanying
script file, queryPortfolios.in, 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 < queryPortfolios.in
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 queryPortfolios.in file.
Close the open sessions by entering exit in each of them.