001: /* Copyright (C) 2004 - 2007 db4objects Inc. http://www.db4o.com
002:
003: This file is part of the db4o open source object database.
004:
005: db4o is free software; you can redistribute it and/or modify it under
006: the terms of version 2 of the GNU General Public License as published
007: by the Free Software Foundation and as clarified by db4objects' GPL
008: interpretation policy, available at
009: http://www.db4o.com/about/company/legalpolicies/gplinterpretation/
010: Alternatively you can write to db4objects, Inc., 1900 S Norfolk Street,
011: Suite 350, San Mateo, CA 94403, USA.
012:
013: db4o is distributed in the hope that it will be useful, but WITHOUT ANY
014: WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: for more details.
017:
018: You should have received a copy of the GNU General Public License along
019: with this program; if not, write to the Free Software Foundation, Inc.,
020: 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
021: package com.db4o.config;
022:
023: import com.db4o.*;
024: import com.db4o.query.*;
025:
026: /**
027: * interface to configure the querying settings to be used by the query processor.
028: * <br><br>All settings can be configured after opening an ObjectContainer.
029: * In a Client/Server setup the client-side configuration will be used.
030: */
031: public interface QueryConfiguration {
032:
033: /**
034: * configures the query processor evaluation mode.
035: * <br><br>The db4o query processor can run in three modes:<br>
036: * - <b>Immediate</b> mode<br>
037: * - <b>Snapshot</b> mode<br>
038: * - <b>Lazy</b> mode<br><br>
039: * In <b>Immediate</b> mode, a query will be fully evaluated when {@link Query#execute()}
040: * is called. The complete {@link ObjectSet} of all matching IDs is
041: * generated immediately.<br><br>
042: * In <b>Snapshot</b> mode, the {@link Query#execute()} call will trigger all index
043: * processing immediately. A snapshot of the current state of all relevant indexes
044: * is taken for further processing by the SODA query processor. All non-indexed
045: * constraints and all evaluations will be run when the user application iterates
046: * through the resulting {@link ObjectSet}.<br><br>
047: * In <b>Lazy</b> mode, the {@link Query#execute()} call will only create an Iterator
048: * against the best index found. Further query processing (including all index
049: * processing) will happen when the user application iterates through the resulting
050: * {@link ObjectSet}.<br><br>
051: * Advantages and disadvantages of the individual modes:<br><br>
052: * <b>Immediate</b> mode<br>
053: * <b>+</b> If the query is intended to iterate through the entire resulting {@link ObjectSet},
054: * this mode will be slightly faster than the others.<br>
055: * <b>+</b> The query will process without intermediate side effects from changed
056: * objects (by the caller or by other transactions).<br>
057: * <b>-</b> Query processing can block the server for a long time.<br>
058: * <b>-</b> In comparison to the other modes it will take longest until the first results
059: * are returned.<br>
060: * <b>-</b> The ObjectSet will require a considerate amount of memory to hold the IDs of
061: * all found objects.<br><br>
062: * <b>Snapshot</b> mode<br>
063: * <b>+</b> Index processing will happen without possible side effects from changes made
064: * by the caller or by other transaction.<br>
065: * <b>+</b> Since index processing is fast, a server will not be blocked for a long time.<br>
066: * <b>-</b> The entire candidate index will be loaded into memory. It will stay there
067: * until the query ObjectSet is garbage collected. In a C/S setup, the memory will
068: * be used on the server side.<br><br>
069: * <b>Lazy</b> mode<br>
070: * <b>+</b> The call to {@link Query#execute()} will return very fast. First results can be
071: * made available to the application before the query is fully processed.<br>
072: * <b>+</b> A query will consume hardly any memory at all because no intermediate ID
073: * representation is ever created.<br>
074: * <b>-</b> Lazy queries check candidates when iterating through the resulting {@link ObjectSet}.
075: * In doing so the query processor takes changes into account that may have happened
076: * since the Query#execute()call: committed changes from other transactions, <b>and
077: * uncommitted changes from the calling transaction</b>. There is a wide range
078: * of possible side effects. The underlying index may have changed. Objects themselves
079: * may have changed in the meanwhile. There even is the chance of creating an endless
080: * loop, if the caller of the iterates through the {@link ObjectSet} and changes each
081: * object in a way that it is placed at the end of the index: The same objects can be
082: * revisited over and over. <b>In lazy mode it can make sense to work in a way one would
083: * work with collections to avoid concurrent modification exceptions.</b> For instance one
084: * could iterate through the {@link ObjectSet} first and store all objects to a temporary
085: * other collection representation before changing objects and storing them back to db4o.<br><br>
086: * Note: Some method calls against a lazy {@link ObjectSet} will require the query
087: * processor to create a snapshot or to evaluate the query fully. An example of such
088: * a call is {@link ObjectSet#size()}.
089: * <br><br>
090: * The default query evaluation mode is <b>Immediate</b> mode.
091: * <br><br>
092: * Recommendations:<br>
093: * - <b>Lazy</b> mode can be an excellent choice for single transaction read use,
094: * to keep memory consumption as low as possible.<br>
095: * - Client/Server applications with the risk of concurrent modifications should prefer
096: * <b>Snapshot</b> mode to avoid side effects from other transactions.
097: * <br><br>
098: * To change the evaluationMode, pass any of the three static {@link com.db4o.config.QueryEvaluationMode}
099: * constants from the {@link com.db4o.config.QueryEvaluationMode} class to this method:<br>
100: * - {@link com.db4o.config.QueryEvaluationMode#IMMEDIATE}<br>
101: * - {@link com.db4o.config.QueryEvaluationMode#SNAPSHOT}<br>
102: * - {@link com.db4o.config.QueryEvaluationMode#LAZY}<br><br>
103: * This setting must be issued from the client side.
104: */
105: public void evaluationMode(QueryEvaluationMode mode);
106:
107: }
|