Using AutoFetch with Ebean

• Explicit Control
• Implicit Control
• Settings in avaje.properties
• The AutoFetch file
• Garbage Collection and Profile collection
• Profiling and Tuned Query
• JMX and AutoFetchControl

You need Ebean 0.9.7

0.9.7 is the first version of Ebean with the AutoFetch feature.

Explicit Control

  ...  
  // explicitly turn on AutoFetch for this query
  query.setAutoFetch(true);
  ...

Implicit Control

For queries where autoFetch has not been explicitly set there are three options which can be configured.

# implicit autofetch mode
#     DEFAULT_OFF         - Don't use AutoFetch
#     DEFAULT_ON          - Use AutoFetch
#     DEFAULT_ON_IF_EMPTY - Use if neither select() or join() have been set

ebean.autofetch.implicitmode=default_on

Settings in avaje.properties

These are the settings you put in avaje.properties to control autofetch.

# enable autofetch
ebean.autofetch.querytuning=true

# enable collection of profiling information
ebean.autofetch.profiling=true

# implicit autofetch mode
#     DEFAULT_OFF         - Don't use AutoFetch
#     DEFAULT_ON          - Use AutoFetch
#     DEFAULT_ON_IF_EMPTY - Use if neither select() or join() have been set
ebean.autofetch.implicitmode=default_on

# minimum amount of profiling to collect before
# autofetch will start tuning the query
ebean.autofetch.profiling.min=1

# profile every query up to base 
ebean.autofetch.profiling.base=10

# after base collect profiling on 5% of queries
ebean.autofetch.profiling.rate=0.05

The AutoFetch file

Ebean collects profiling information. On startup it is read from a file and on shutdown it is written to a file. This file is located in the same directory as the dictionary file.

Garbage Collection and Profile collection

When Ebean is collecting profiling information it puts a NodeUsageCollector object on each entity bean. The NodeUsageCollector collects profiling information which essentially is the set of properties for that bean that where used (read or written).

Q: When does the NodeUsageCollector know when to stop collecting information?

A: For Ebean this occurs via Garbage collection. The finalize is called on the NodeUsageCollector and at that point it publishes its profiling information back to a AutoFetchListener.

The approach has worked very well for me on the Sun JVM. For applications that run for a short time it should be noted that garbage collection is not likely to occur. As part of Ebean's shutdown it triggers a GC and collects any leftover profiling information before writing that to a file.

This works well on the Sun JVM but we should note that triggering a GC is a HINT to the JVM and not a guarantee that a GC will actually occur. We really DON'T want to be triggering GC (let the JVM do its thing) so Ebean only does this on shutdown.

Profiling and Tuned Query

Ebean actually holds two sets of information for AutoFetch. The first is the profiling information and the second is the Tuned query.

Tuned Query

Periodically the profiling information is converted into a tuned query. The Tuned query is actually just the select() and join() parts of a query. When autoFetch tunes a query it is simply a matter of replacing the select() & join() parts of the query.

A log is generated which shows new and changed "tuned query information". In this log you will be able to see the tuned query change if the usage changes.

Profiling Information

In addition to knowing which properties on which nodes where used the query execution of associated lazy loading queries are also collected. This is a pretty interesting point in that you can see how much and how expensive and the lazy loading queries are for a given original query - very interesting stuff.

JMX and AutoFetchControl

Ebean provides an API for controlling the AutoFetch at runtime. This means you can turn it on/off change the profiling rate as well as trigger profile collection and "tuned query info" generation.

This is useful when you are playing around with AutoFetch. Along with this you can use LogControl to turn on/off the generated sql logging and generally get a feel for whats going on.