Cache configuration is explained on DiscRack example (directory <DODS_HOME>/examples/discrack). The cache 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.cache.maxCacheSize = 100 DatabaseManager.defaults.cache.maxSimpleCacheSize = 20 DatabaseManager.defaults.cache.maxComplexCacheSize = 5 DatabaseManager.defaults.cache.maxMultiJoinCacheSize = 3 DatabaseManager.defaults.cache.reserveFactor = 0.1 DatabaseManager.defaults.cache.CachePercentage = -1 # DatabaseManager.defaults.cache.initAllCaches = true DatabaseManager.defaults.cache.asynchLoadThreadNum = 2 DatabaseManager.defaults.cache.simpleCacheRowCountLimit = 300 DatabaseManager.defaults.cache.synchLoadRowCountLimit = 5000 DatabaseManager.defaults.cache.maxExecuteTimeCacheInit = 300 DatabaseManager.defaults.cache.queryTimeoutCacheInit = 10 DatabaseManager.defaults.cache.queryTimeLimitCacheInit = 12000
The second level is database level. On this level can be defined the following parameters (all information are optional):
DatabaseManager.DB.<database_name>.cache.maxCacheSize = 1100 # DatabaseManager.DB.<database_name>.cache.maxSimpleCacheSize = 10 # DatabaseManager.DB.<database_name>.cache.maxComplexCacheSize = 5 # DatabaseManager.DB.<database_name>.cache.maxMultiJoinCacheSize = 3 DatabaseManager.DB.<database_name>.cache.reserveFactor = 0.1 DatabaseManager.DB.<database_name>.cache.CachePercentage = -1 DatabaseManager.DB.<database_name>.cache.initAllCaches = true DatabaseManager.DB.<database_name>.cache.simpleCacheRowCountLimit = 400 DatabaseManager.DB.<database_name>.cache.synchLoadRowCountLimit = 6000 DatabaseManager.DB.<database_name>.cache.maxExecuteTimeCacheInit = 400 DatabaseManager.DB.<database_name>.cache.queryTimeoutCacheInit = 15 DatabaseManager.DB.<database_name>.cache.queryTimeLimitCacheInit = 20000
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 - cache configuration # DatabaseManager.DB.DiscRack.Disc.cache.maxCacheSize = 10000 DatabaseManager.DB.DiscRack.Disc.cache.maxSimpleCacheSize = 2000 DatabaseManager.DB.DiscRack.Disc.cache.maxComplexCacheSize = 250 DatabaseManager.DB.DiscRack.Disc.cache.maxMultiJoinCacheSize = 100 DatabaseManager.DB.DiscRack.Disc.cache.reserveFactor = 0.1 DatabaseManager.DB.DiscRack.Disc.cache.CachePercentage = 0.5 DatabaseManager.DB.DiscRack.Disc.cache.asynchLoadPriority = 2 DatabaseManager.DB.DiscRack.Disc.cache.simpleCacheRowCountLimit = 1000 DatabaseManager.DB.DiscRack.Disc.cache.synchLoadRowCountLimit = 10000 DatabaseManager.DB.DiscRack.Disc.cache.maxExecuteTimeCacheInit = 500 DatabaseManager.DB.DiscRack.Disc.cache.queryTimeoutCacheInit = 10 DatabaseManager.DB.DiscRack.Disc.cache.queryTimeLimitCacheInit = 12000 # # Table Person - cache configuration # DatabaseManager.DB.DiscRack.person.cache.maxCacheSize = -1 DatabaseManager.DB.DiscRack.person.cache.maxSimpleCacheSize = 2000 DatabaseManager.DB.DiscRack.person.cache.maxComplexCacheSize = 250 DatabaseManager.DB.DiscRack.person.cache.maxMultiJoinCacheSize = 75 DatabaseManager.DB.DiscRack.person.cache.initialCondition = * DatabaseManager.DB.DiscRack.person.cache.asynchLoadPriority = 1 DatabaseManager.DB.DiscRack.person.cache.simpleCacheRowCountLimit = 100 DatabaseManager.DB.DiscRack.person.cache.synchLoadRowCountLimit = 5000 DatabaseManager.DB.DiscRack.person.cache.maxExecuteTimeCacheInit = 200 DatabaseManager.DB.DiscRack.person.cache.queryTimeoutCacheInit = 5 DatabaseManager.DB.DiscRack.person.cache.queryTimeLimitCacheInit = 7000
Cache defaults on DatabaseManager and Database are default values for all application's table caches. 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 parameters is not defined neither on the Database, nor on DatabaseManager level, DODS uses its own program defaults. For maxCacheSize, maxSimpleCacheSize, maxComplexCacheSize, maxMultiJoinCacheSize, reserveFactor, asynchLoadThreadNum, simpleCacheRowCountLimit, synchLoadRowCountLimit program default value is 0, for CachePercentage is -1.0, for initAllCaches is false and for maxExecuteTimeCacheInit, queryTimeoutCacheInit and queryTimeLimitCacheInit program default is value defined for parameters maxExecuteTime, QueryTimeout and QueryTimeLimit.
If any of table level parameters maxCacheSize, maxSimpleCacheSize, maxComplexCacheSize, maxMultiJoinCacheSize, reserveFactor, CachePercentage, simpleCacheRowCountLimit, synchLoadRowCountLimit, maxExecuteTimeCacheInit, queryTimeoutCacheInit or queryTimeLimitCacheInit is defined on the table level, that value is used. If not, the default value for all tables is used (explained in previous paragraph).
The parameter initialCondition can be defined only on the table level. It contains "where" part of select clause. With this select clause is DataStruct cache of specified table initialized. If initialCondition = '*', the entire table will be added to the DataStruct cache in DataStruct cache initialization. If the parameter is NULL or not defined, no objects are added to the Data cache during the cache initialization.
If, for any table parameter initialCondition is not defined and the initAllCaches parameter is set to 'true' (on DatabaseManager or Database level, as explained before), the default value of initialCondition parameter for the table is "*".
Parameter maxCacheSize contains information about maximal size of DataStruct cache. Parameter maxSimpleCacheSize contains information about maximal size of simple query cache. Parameter maxComplexCacheSize contains information about maximal size of complex query cache. Parameter maxMultiJoinCacheSize contains information about maximal size of multi-join query cache.
Parameter CachePercentage is used for query to make decision what type of query will be executed: select t.* or select t.oid. If no lazy loading and caching is turned on and value of CachePercentage is less then currently used cache (in percents), t1.* is used for query statement. Otherwise select t.oid. Parameter value 0 means use always t1.oid if cache is turned on, -1 (default) means never if not lazyloading but cached. If lazy loading is on always is used t1.oid query.
In <table_name>Query.java class are added new methods:
setLoadData(boolean newValue)
If parameter newValue set to true, query select t.* will be executed no matter what are the values of parameters lazyLoading and CachePercentage.
getLoadData()
Returns true if query select t.* will be executed, otherwise false.
Reserve factor is constant used in query caching. It is percent of how many more object are taken for evaluation. If num is number of needed results, then it is used
num + reserveFactor * num
objects for estimating what is quicker: go to database for all object that are not in the cache, or run again query on database. This value is given in percents, as number between 0 and 1 (0.25 means 25%).
For example, if reserveFactor is 0.5, and wanted number of results is 50, the estimation will be done on 75 (50 + 0.5 * 50) objects.
In the following text are explained maximal cache sizes (for DataStruct cache and query caches). The parameters maxCacheSize, maxSimpleCacheSize, maxComplexCacheSize and maxMultiJoinCacheSize of application's configuration file define these sizes.
maxCacheSize > 0
This cache is limited. The maximal number of elements in the cache is maxCacheSize. This is LRU cache type.
maxCacheSize = 0
This means that there is no cache available. This value excludes cache from use.
maxCacheSize < 0
This cache is unlimited. This is complete type of cache (HashMap).
The parameter asynchLoadThreadNum is only defined on DatabaseManager level. This is the number of threads used for asynchronous cache load during application startup. The default value is 0 (asynchronous cache load is not used).
The parameter asynchLoadPriority is only defined on table level. It is the priority of asynchronous cache load for the table. The table that has the lowest value for this parameter will be first asynchronous loaded during application startup. When a thread finishes cache load of a table, it takes the next table from the priority list and loads its cache, and so on. The default value for this parameter is -1. This means that the cache for that table will not be asynchronous loaded.
The parameter simpleCacheRowCountLimit defines max number of rows in the table for which simple cache is still used. If the table has more rows than defined by this parameter, complex cache is used for simple queries. The default value is 0 (simple cache is used for all simple queries).
The parameter synchLoadRowCountLimit defines the max number of rows in the table for which the synchronous cache load is performed if defined by configuration. If the number of rows is greater, the table's cache will be loaded asynchronous and this number will be taken for the asynchLoadPriority . The default value is 0 (asynch cache load is not performed if configuration parameters for asynch cache load are not defined).
The parameter maxExecuteTimeCacheInit is similar to table parameter maxExecuteTime, but defined for cache initialization. It defines the max time for which the query is not printed in application's log file during the cache initialization. If the time is greater, query (SQL statement, execution time and maxExecutionTime) is printed. The default value is value defined for parameter maxExecuteTime (whose default is 0 - nothing is printed).
The parameter queryTimeoutCacheInit is similar to table parameter QueryTimeout, but defined for cache initialization. It defines max number of seconds for which the query for cache initialization should be executed. If the limit is exceeded, an exception is thrown. The default value is value defined for parameter QueryTimeout (whose default is 0 - no limit).
The parameter queryTimeLimitCacheInit is similar to table parameter QueryTimeLimit, but defined for cache initialization. It defines max number of milliseconds for which the query for cache initialization should be executed and the resulset read from ResultSet. If the limit is exceeded, an Exception is thrown. The default value is value defined for parameter QueryTimeLimit (whose default is 0 - no limit).
In the previous mentioned DiscRack example for cache configuration, DataStruct cache for table person has type full, because maxCacheSize is negative and initialCondition is "*". This combination of parameters values forms special case of complete cache: full cache.
DODS has class org.enhydra.dods.cache.UpdateConfigurationAdministration. This class has public synchronized methods that provide possibility of run-time setting some cache and table parameters. This class is used by Enhydra application CacheAdmin. It is not recommended to be used by user applications.