The reserveFactor attribute is one of the cache parameters of the applications configuration file. This attribute can be handled from <table_name>DO.java class as following:
getConfigurationAdministartion().getReserveFactor()
This method returns the value of reserveFactor attribute.
Reserve factor is constant used in query caching. It is percent of how many more objects are taken for evaluation. If num is number of needed results, then it is used
num + reserveFactor * num
of 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%).
Example:
Let us assume that there is a PersonQuery query pQuery, and that are set databaseLimit and readSkip attributes to values:
pQuery.setReadSkip(5); pQuery.setDatabaseLimit(15);
When the query is executed, first is checked if this query is cached in the query cache. The reserve factor is used when the query is cached in query cache and the security is used (user != null).
Let us assume that the query is found in the query cache. The list of oids that are results of this query is retrieved from the query cache. For example, the result list has 50 oids.
If security is used, we don't know how many DOs from results will be skipped because the user can not read them, but, it has to be decided what to do (what is quicker): to execute the query on the database again, or to get only DOs from the database that are not in the DataStruct cache.
For this decision some kind of calculation must be done, and this is the reason why the reserveFactor is needed.
For example, reserveFactor = 0.25. Now calculation is performed: needed number of oids for calculation is:
(readSkip + databaseLimit) + (readSkip + databaseLimit) * reserveFactor
So, it is needed readSkip + databaseLimit = 5+15 = 20 results, but this may not be first 20 because of filtering (user rights may skip some oids), but, until the DO is not loaded from the database it is unknown whether user has rights for this DO or not.
For this reason, a little more oids must be taken and when they are filtered (only DOs whose original data is in the DataStruct cache can be checked for user rights), it is decided what might be better: to execute the query on the database again, or to get only DOs from the database that are not in the DataStruct cache.
In our case, that number is: needed number of oids for calculation is: 5 + 15 + (5 + 15) * 0.25 = 25. The first 25 oids from query result list are taken and they are filtered: it is checked for every oid if the DataStruct is in the DataStruct cache. If yes, the DO is created using this DataStruct object and then checked user rights for that DO. If user can read this DO, it is left in the result list, and if user can not read this DO, it is removed from the result list. If DataStruct with this oid is not in the DataStruct cache, the user rights can not be checked for that DO, so it is left in the result list for the moment.
When the filtering of chosen 25 oids is finished, there can happen two situations:
in the result list is less than 20 (needed number) results; in this case, base to the calculations, the query is again executed on the database
in the result list is more than 20 (needed number) results, or exacly 20;
in this case, if the time needed for getting only DOs that are not in the cache is less than the time needed for executing the whole query on the database, from the database are just retrieved DOs that are not in the DataStruct cache, checked user rights for them, and removed if neccessary
If, after this filtering there are still 20 results, they are returned as query result.
If not, the query is again executed on the database.