By default, your cache is limited to a percentage of the JVM maximum memory as specified by the -Xmx parameter. You can change this percentage by using the je.maxMemoryPercent property or through EnvironmentMutableConfig.setCachePercent(). That is, the maximum amount of memory available to your cache is normally calculated as:

je.maxMemoryPercent * JVM_maximum_memory

You can find out what the value for this property is by using EnvironmentConfig.getCachePercent().

Note that you can cause JE to use a fixed maximum cache size by using je.maxMemory or by using EnvironmentConfig.setCacheSize().

Also, not every JVM is capable of identifying the amount of memory requested via the -Xmx parameter. For those JVMs you must use je.maxMemory to change your maximum cache size. The default maximum memory available to your cache in this case is 38M.

Of the amount of memory allowed for your cache, 93% is used for the internal BTree and the other 7% is used for internal buffers. When your application first starts up, the 7% for buffers is immediately allocated. The remainder of the cache grows lazily as your application reads and writes data.

In order for your application to start up successfully, the Java virtual machine must have enough memory available to it (as identified by the -Xmx command line switch) for both your application and 7% of your maximum cache value. In order for your application to run continuously (all the while loading data into the cache), you must make sure your JVM has enough memory for your application plus the maximum cache size.

The best way to determine how large your cache needs to be is to put your application into a production environment and watch to see how much disk I/O is occurring. If the application is going to disk quite a lot to retrieve database records, then you should increase the size of your cache (provided that you have enough memory to do so).

You can also use the com.sleepycat.je.util.DbCacheSize utility to obtain a rough estimate of how large your cache needs to be for a given number of records and record characteristics. The utility returns an estimate of the cache size to hold the specified number of records in memory. See the DbCacheSize javadoc for information on the utility's usage.

In order to determine how frequently your application is going to disk for database records not found in the cache, you can examine the value returned by EnvironmentStats.getNCacheMiss().

EnvironmentStats.getNCacheMiss() identifies the total number of requests for database objects that were not serviceable from the cache. This value is cumulative since the application started. The faster this number grows, the more your application is going to disk to service database operations. Upon application startup you can expect this value to grow quite rapidly. However, as time passes and your cache is seeded with your most frequently accessed database records, what you want is for this number's growth to be zero or at least very small.

Note that this statistic can only be collected from within the application itself or using the JMX extension (see JConsole and JMX Support).

For more information on collecting this statistic, see Environment Statistics.