com.db4o.config

Interface QueryConfiguration

All Known Implementing Classes:

Config4Impl

public interface QueryConfiguration

interface to configure the querying settings to be used by the query processor.

All settings can be configured after opening an ObjectContainer. In a Client/Server setup the client-side configuration will be used.

Method Summary

Methods

Modifier and Type	Method and Description
QueryEvaluationMode	evaluationMode()
void	evaluationMode(QueryEvaluationMode mode) configures the query processor evaluation mode.

Method Detail

evaluationMode

void evaluationMode(QueryEvaluationMode mode)

configures the query processor evaluation mode.

The db4o query processor can run in three modes:
- Immediate mode
- Snapshot mode
- Lazy mode

In Immediate mode, a query will be fully evaluated when Query.execute() is called. The complete ObjectSet of all matching IDs is generated immediately.

In Snapshot mode, the Query.execute() call will trigger all index processing immediately. A snapshot of the current state of all relevant indexes is taken for further processing by the SODA query processor. All non-indexed constraints and all evaluations will be run when the user application iterates through the resulting ObjectSet.

In Lazy mode, the Query.execute() call will only create an Iterator against the best index found. Further query processing (including all index processing) will happen when the user application iterates through the resulting ObjectSet.

Advantages and disadvantages of the individual modes:

Immediate mode
+ If the query is intended to iterate through the entire resulting ObjectSet, this mode will be slightly faster than the others.
+ The query will process without intermediate side effects from changed objects (by the caller or by other transactions).
- Query processing can block the server for a long time.
- In comparison to the other modes it will take longest until the first results are returned.
- The ObjectSet will require a considerate amount of memory to hold the IDs of all found objects.

Snapshot mode
+ Index processing will happen without possible side effects from changes made by the caller or by other transaction.
+ Since index processing is fast, a server will not be blocked for a long time.
- The entire candidate index will be loaded into memory. It will stay there until the query ObjectSet is garbage collected. In a C/S setup, the memory will be used on the server side.

Lazy mode
+ The call to Query.execute() will return very fast. First results can be made available to the application before the query is fully processed.
+ A query will consume hardly any memory at all because no intermediate ID representation is ever created.
- Lazy queries check candidates when iterating through the resulting ObjectSet. In doing so the query processor takes changes into account that may have happened since the Query#execute()call: committed changes from other transactions, and uncommitted changes from the calling transaction. There is a wide range of possible side effects. The underlying index may have changed. Objects themselves may have changed in the meanwhile. There even is the chance of creating an endless loop, if the caller of the iterates through the ObjectSet and changes each object in a way that it is placed at the end of the index: The same objects can be revisited over and over. In lazy mode it can make sense to work in a way one would work with collections to avoid concurrent modification exceptions. For instance one could iterate through the ObjectSet first and store all objects to a temporary other collection representation before changing objects and storing them back to db4o.

Note: Some method calls against a lazy ObjectSet will require the query processor to create a snapshot or to evaluate the query fully. An example of such a call is ObjectSet.size().

The default query evaluation mode is Immediate mode.

Recommendations:
- Lazy mode can be an excellent choice for single transaction read use, to keep memory consumption as low as possible.
- Client/Server applications with the risk of concurrent modifications should prefer Snapshot mode to avoid side effects from other transactions.

To change the evaluationMode, pass any of the three static QueryEvaluationMode constants from the QueryEvaluationMode class to this method:
- QueryEvaluationMode.IMMEDIATE
- QueryEvaluationMode.SNAPSHOT
- QueryEvaluationMode.LAZY

This setting must be issued from the client side.

evaluationMode

QueryEvaluationMode evaluationMode()

Returns:

the currently configured query evaluation mode

See Also:

evaluationMode(QueryEvaluationMode)