GemStone® GemFire Enterprise®

Java Caching API Programming Example

The cacheOverflow example program demonstrates the "overflow" feature of GemFire cache regions. The example is located in the GemFire installation under examples/dist/cacheOverflow.

Before running this application, you need to start a terminal session and configure its environment according to the instructions provided under the GemFire installation in examples/EnvSetup.html.

After the environment has been set, change directory to examples/dist/cacheOverflow in the GemFire product directory.

You can run the cacheOverflow example with no command line arguments to obtain usage information.

    java cacheOverflow.CacheOverflow

    ** Missing number of threads

    usage: java cacheOverflow.CacheOverflow [options] args

    Where [options] are
      -backup            Backup the region data on disk (data will be written
                         to disk as soon as it is added to the region)
      -synchronous       Writes to disk are synchronous
      -validate          Instead of populating a region validates its contents.
                         Only useful with -backup
      -disableRolling    Save the old backup files instead of rolling over to 
                         an archive and deleting the files

    Where args are
      threads            Number of threads adding to region
      arrays             Number of 8 kilobyte arrays added by each thread
      overflowThreshold  Number of megabytes of region data that can reside
                         in the VM before overflowing to disk
      maxOplogSize       Number of megabytes of region data that can be written
                         to a backup file before rolling over to a new file
      dir+               One or more directories in which to write region data

The cacheOverflow example launches one or more threads that populate a GemFire region with 8 kilobyte chunks of data (long arrays of size 1024). Once the amount of region data exceeds the specified threshold, the data is overflowed to disk, thus allowing the logical size of the region to exceed the amount of heap space in the VM.

Enter the following command exactly as shown. The call puts a total of 20*100*8K = 16MB of data into a region with a size limit of 1 megabyte, so 15 megabytes are overflowed (into a 30 megabyte file in the current working directory) as the threads run.

    java cacheOverflow.CacheOverflow 20 100 1 30 .

When the threads finish, the program exits. This forces a cache close and region destruction.

Enter exit to close the terminal session.

While the program itself does not have very interesting output, there are a number of GemFire statistics that are worth observing: the number of bytes that are added by the example program (the bytesAdded statistic of the WorkerStats), the number of region entry values that have been overflowed to disk (the lruEvictions statistic of MemLRUStatistics, and the amount of time that is spent writing data to disk (the writeTime statistic of DiskRegionStatistics).

By default, the cacheOverflow program runs as a standalone GemFire application, meaning it does not join a distributed system, but only creates a cache. The program's statistics are archived in a file named statArchive.gfs. The optional GFMon tool can be used to view these statistics. The CacheOverflow program can be configured to join a distributed system by setting certain distribution-related system properties as outlined in the online documentation for the DistributedSystem class and in the GemFire Enterprise Developer's Guide.