Chapter 5. Caching

Table of Contents

Table configuration
Cache configuration
Table and cache statistics

DODS provides the possibility for every table to have its cache.

The possible cache types are:

1.None

No caching is available.

2.LRU

The size of the cache is limited by the maximal number of objects that can be stored in it. When the cache is full, the objects in it are being replaced by new objects according to LRU (least recently used) algorithm. This algorithm says that the object which had been used the least recently (in the scale of time, the object to which had been accessed the longest time ago, which is on the end of LRU list) is removed from list and new one is put in front of the LRU list. If maximal number of objects is set to 0, it means that caching is not available (None type) at the moment.

3.Complete

This cache extends HashMap and is unbounded. This cache type is defined by the negative number of maximal cache size.

4.Full (special case of complete cache)

This is a complete cache (HashMap), for which is the entire table queried and cached when the application starts (initial condition is "*"). This is appropriate for tables of "static" data which are accessed frequently.

There is a method, isComplete(), in the cache class that checks if the cache (DataStruct cache) is complete or not. If the cache was not complete at the start, it is not checked if it becomes complete or not. But, if the cache was complete, it is than calculated whether the cache is still complete. The method for setting max cache size (in the situation when cache is not null and new cache size is not zero) for DataStruct cache changes cache implementation (form complete to LRU), only if the cache was complete and the new maxCacheSize is positive. In all other cases, the implementation stays as it was.

It is a little bit different with query caches. They don't define the global caching type, so any change form negative to positive max cache size (and vice versa) changes the cache implementation (Complete or LRU).

When any of the caches (DataStruct or any of query caches) is created from scratch, the procedure is the same. Based on max cache size, the proper implementation is used. The same goes for methods for cache refreshing and enabling.

DODS has two levels of caching:

1.Data Caching level

There is only one LRU cache: cache with DataStruct objects. The keys of this cache are cache handles - Strings in the following form:

"<DataStruct_database_name>.<Table_name>.<String_presentation_of_DataStruct_oid>"

and cache values are, as mentioned before, DataStruct objects.

2.Query caching level

Beside DataStruct object cache, there is a possibility of using three query caches (simple, complex and multi-join). Multi-join cache is included since DODS 6.0. All query caches are also LRU caches. The keys of these caches are Strings in the following form:

"<query_database_name>.<String_presentation_of_query>",

and cache values are Query objects. Query objects are objects of the org.enhydra.dods.cache.QueryCacheItem class.

The QueryCacheItem object stores one query and its necessary data:

The default values for maximal cache sizes for DataStruct, simple and complex query cache are 0 (no caching).

Table configuration

Table configuration is explained on DiscRack example (directory <DODS_HOME>/examples/discrack). The table parameters are defined on three levels.

The first level is DatabaseManager level. On this level can be defined the following parameters (all information are optional):

DatabaseManager.defaults.lazyLoading = true 
DatabaseManager.defaults.maxExecuteTime = 200
DatabaseManager.defaults.AllReadOnly = false 

The second level is Database level. On this level can be defined the following parameters (all information are optional):

DatabaseManager.DB.<database_name>.lazyLoading = false 
DatabaseManager.DB.<database_name>.maxExecuteTime = 350
DatabaseManager.DB.<database_name>.AllReadOnly = false 

The third level is table level. In the case of DiscRack example, there are two tables: Disc and person. The tables can have the following parameters:

# 
# Table Disc - table configuration 
# DatabaseManager.DB.DiscRack.Disc.readOnly = false 
DatabaseManager.DB.DiscRack.Disc.lazyLoading = false 
DatabaseManager.DB.DiscRack.Disc.maxExecuteTime = 150 
# 
# Table Person - table configuration 
# DatabaseManager.DB.DiscRack.person.readOnly = true 
DatabaseManager.DB.DiscRack.person.lazyLoading = false 
# DatabaseManager.DB.DiscRack.person.maxExecuteTime = 150 

Table defaults on DatabaseManager and Database are default values for all application's tables. If any of these parameters is defined on the Database level, that value is used as a default for all tables. If any of the parameters is not defined on the Database level, then, if it is defined on the DatabaseManager level, this value is used. If any of these parameter is not defined neither on the Database, nor on DatabaseManager level, DODS uses its own program defaults. For lazyLoading, program default is false, for maxExecuteTime 0 and for readOnly and AllReadOnly false.

If any of parameters lazyLoading or maxExecuteTime is defined on the table level, that value is used. If not, the default value for all tables is used (explained in previous paragraph).

If parameter AllReadOnly is defined and set to true (it can be defined on DatabaseManager or Database level), all applications will be read-only. In that case, readOnly parameter is ignored. Only, If AllReadOnly is set to true and readOnly attribute of the table is set to false, warning is written to log during table initialization. In runtime exception is thrown on attempt of writing to that table.

Parameter maxExecuteTime is time for query execution. Every query that is executed longer than maxExecuteTime is printed (SQL statement, execution time and maxExecutionTime) in application's log file.

All other parameters are explained later in this document.