15. Appendix A: Configuration

BeanKeeper does not need to be configured in any way. However, if you want to tweak some settings, this chapter describes all parameters which can be tweaked. All settings are contained in a single file named beankeeper.properties in the root directory of the distributed jar file. What follows is a complete description of this file:

cache.min_free_bytes=512000

This is the minimum free bytes the JVM should have before the cache accepts an entry without freeing some other entries. If the JVM has less than this, then already cached resultset are freed, before the new resultset is cached. Keep in mind, that the new resultset is always cached, no matter what happens.

cache.min_free_rate=60

Same as above, but this time, the free/total memory rate is given in percentage. If the JVM has less, then some entries are freed from the cache. Note, that the JVM also usually allocates heap based on the free/total memory rate. Usually, at about 70% the JVM allocates more memory, and at 40% the JVM frees up heap, depending on your JVM implementation. But because of this, there are basically two strategies the library can use to allocate cache space:

If the min_free_rate is more than the JVM's maximum rate. Then the library will continue to use memory for the cache, and the JVM limit will be reached before the min_free_rate, which means the JVM will detect that more memory is needed, and allocate more heap. This again causes the library to use more memory, which causes the JVM to allocate yet more, and so on. The net result is, that the cache will "agressively" use up all memory which the JVM can give. Note, that if in the meantime the application uses more and more memory, the cache will slowly give back memory because of the min_free_bytes rule.

The second strategy is setting the min_free_rate below the JVM's threshold. This means, that the library itself will never cause the JVM to get more heap. Instead, if the application grows, and more heap is available, then the cache can use more memory too. Once that memory is used, the cache may scale back, if the cache entries start to expire.

cache.force_free_rate=2

When a cache detects, that is has no available memory (ether because cache.min_free_bytes or cache.min_free_rate), then it tries to free some entries. This parameter decides how many entries to free, in the outgoing/incoming result size ratio. If the incoming (new) result set contains 10 objects, then at least 20 objects will be freed, if the ratio is 2. This number should account for the differences in object memory footprint. As there is no reliable way to measure one object's memory footprint, if "large" objects enter the cache, and ther are only "small" objects in the cache, this ratio will ensure, that even in this case, approximately enough memory will be freed for the new objects.

cache.expiration=60000

This is the amount of time in milliseconds, a new entry in the cache will survive if it received no hits. If the entry receives a cache hit, than this interval is again added to the expiration date.

pool.connection_timeout=600000

The number of milliseconds an idle connection to the database will be kept before closing.

net.connect_timeout=3000

The time in milliseconds a Node should wait before it declares a potential other Node unreachable. If this setting is high (many seconds) , it may cause the library to appear freezed, until it can declare the othe Node unreachable (this is possible during network failures). If it's low (appr. below a second), it may declare a Node unreachable, even if it is, which may result in the Node becoming unusable.

node.timeout=10000

The maximum time in milliseconds a Node can wait to update it's heartbeat signal in the database. If this time passes, the other nodes may declare this Node dead if they are currently trying to appoint a server node. If setting must be higher than the heartbeat interval. If this value is too close to the heartbeat interval, a Node can be declared dead when it is not, this can potentially lead to cluster fragmentation, which can lead to data corruption. If it's high, then dead Node entries may cause the Nodes to wait this long until they can appoint a new server (so a server fallout will cause all Nodes in the cluster to wait this long). It is highly recommended, that if you tweak this value, keep it at least 150% heartbeat, or at least 3 seconds higher.

node.heartbeat=6000

This is the amount of time in milliseconds each Node will update the database table to signal other nodes, that it is still alive. This is very important to prevent cluster fragmentation, and potential data loss. The lower, the more frequently each node will issue an update statement to the database, but higher means, that the timeout value needs to be high too, which may cause wait periods when the cluster re-organizes itself.

lock.expire_kept=1800000

The amount of time in millisecons a kept lock will expire in. If this amount is small, kept locks will expire in short time, possibly causing large work-sessions to rollback due to locking problems. If this value is high, the memory usage is higher. Kept locks are locks which are basically unlocked, but they can not be re-locked by the same object unless they were not touched by others.

list.batch_size=30

This is the number of objects a lazy list should contain at any given time. This is also the amount of objects returned from the database in a single operation, so internal paging is based on this number. The lazy list is the base for member lists and maps too! The greater the number, the more cpu and memory is used on a single select, but the frequency of selects becomes less, because more data is present. If the number is too small, the number of select operations increases. It is recommended to keep this number between appr. 20-50. If you use this in a web application, the optimal setting for this is the number of result rows your pages display, because all pages then can be selected in a single select.

list.batch_size_linearmultiplier=3

This number is used to muliply the above batch size whenever the library detects, that the previous chunk was iterated linearly. This is used to make linear iterations more efficient.

list.batch_size_max=2500

This is the maximum batch size of the lazy list. When this number is high, linear iterations will consume more memory, but statement executions become rarer. If this number is small, linear iterations will become generally slower.

list.max_joins=16

This is the maximum number of left join tables a single select can contain. All subclasses of a selected class are selected with a left join, so all superclasses which have many subclasses (more than this number) will be split into more queries. This number is physically limited by the maximum number of tables per select the database supports (usually a few hundred). Setting this value low will yield more query executions, setting it high will make fewer, but more expensive selects.

profile.interval=5000

The number of milliseconds between profiling outputs.

performance.interval=5000

The number of milliseconds between performance outputs.

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