12. Internal Caches and Pools

12.1 Connection Pool

The Store object can be instantiated in two different ways. Either a DataSource is given as the source for database connections, or the database Driver and the URL of the database is given. Either case, the library maintains a pool of connections at all times. The pool's size is determined dynamically by the load. When a new connection is requested from the pool, and there is no available pooled connection, the pool allocates one from the connection source (from the DataSource or Driver). After a given amount of time, if a connection is not used, it is closed, and removed from the pool.

The library also keeps a shutdown hook on the JVM, so when the JVM exists, all pooled connections are closed. If a transaction was running on a connection, it will be rolled back. Also, if you use the JVM's shutdown hook to do some jobs, you can not rely on the library to function, as it may already have closed all connections, and freed all resources.

12.2 Results Cache

The library uses a flat read-only cache, which means, that it does not take versioning into consideration. It only caches actual data, which are likely to be used many times. This means not all queries will be cached:

• Historical queries are never cached.
• Queries with which the query's transaction interferes are also never cached.

Historical queries are not used regularly, so they are never cached. Also, probably the memory usage would outweight the benefits of a cache if they would be handled.

If the query would return a resultset which is influenced by the current transaction, that means, that the modifications made prior to the query are not independent of the query, then this result set would be not usable for other transactions currently, since these modifications are currently not visible to the others, until this transaction commits. So until then this query won't be cached. If the transaction commits, then the cache is notified which tables are changed, and all query results which may have changed are discarded from the cache.

The memory allocation of the cache is fully dynamic. The cache will match the used memory size to the footprint of the application (or more exactly the JVM). If the application is under heavy load, it usually causes the JVM to allocate more heap, then the library's cache will also use more of that memory. If the application is running in a low-memory mode, the library will only use little memory for the cache. For this to work, the cache inspects the free/total memory ratio, and determines upon that ratio if more memory can be used for the purposes of the cache.

The cache strategy is also very simple:

• All new resultsets are cached, and receive a timeout of T.
• If a resultset reaches it's timeout, it is removed from the cache.
• If a resultset receives a cache hit, T is added again to it's timeout.

This basically means, all resultsets (which are considered for caching), are always cached, and have a chance to remain in the cache indefinately. All resultsets in the cache have a timeout, and if they are not accessed in that time, they are removed from the cache (even if there is enough memory). A cache entry can stay in the cache, if it receives hits, and all hits buy it again some more time.

This document was generated by Robert Brautigam on November, 21 2009 using texi2html 1.78.