KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > db4o > config > QueryConfiguration


1 /* Copyright (C) 2004 - 2006 db4objects Inc. http://www.db4o.com
2
3 This file is part of the db4o open source object database.
4
5 db4o is free software; you can redistribute it and/or modify it under
6 the terms of version 2 of the GNU General Public License as published
7 by the Free Software Foundation and as clarified by db4objects' GPL
8 interpretation policy, available at
9 http://www.db4o.com/about/company/legalpolicies/gplinterpretation/
10 Alternatively you can write to db4objects, Inc., 1900 S Norfolk Street,
11 Suite 350, San Mateo, CA 94403, USA.
12
13 db4o is distributed in the hope that it will be useful, but WITHOUT ANY
14 WARRANTY; without even the implied warranty of MERCHANTABILITY or
15 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16 for more details.
17
18 You should have received a copy of the GNU General Public License along
19 with this program; if not, write to the Free Software Foundation, Inc.,
20 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */

21 package com.db4o.config;
22
23 import com.db4o.*;
24 import com.db4o.query.*;
25
26
27 /**
28  * interface to configure the querying settings to be used by the query processor.
29  * <br><br>All settings can be configured after opening an ObjectContainer.
30  * In a Client/Server setup the client-side configuration will be used.
31  */

32 public interface QueryConfiguration {
33     
34     
35     /**
36      * configures the query processor evaluation mode.
37      * <br><br>The db4o query processor can run in three modes:<br>
38      * - <b>Immediate</b> mode<br>
39      * - <b>Snapshot</b> mode<br>
40      * - <b>Lazy</b> mode<br><br>
41      * In <b>Immediate</b> mode, a query will be fully evaluated when {@link Query#execute()}
42      * is called. The complete {@link ObjectSet} of all matching IDs is
43      * generated immediately.<br><br>
44      * In <b>Snapshot</b> mode, the {@link Query#execute()} call will trigger all index
45      * processing immediately. A snapshot of the current state of all relevant indexes
46      * is taken for further processing by the SODA query processor. All non-indexed
47      * constraints and all evaluations will be run when the user application iterates
48      * through the resulting {@link ObjectSet}.<br><br>
49      * In <b>Lazy</b> mode, the {@link Query#execute()} call will only create an Iterator
50      * against the best index found. Further query processing (including all index
51      * processing) will happen when the user application iterates through the resulting
52      * {@link ObjectSet}.<br><br>
53      * Advantages and disadvantages of the individual modes:<br><br>
54      * <b>Immediate</b> mode<br>
55      * <b>+</b> If the query is intended to iterate through the entire resulting {@link ObjectSet},
56      * this mode will be slightly faster than the others.<br>
57      * <b>+</b> The query will process without intermediate side effects from changed
58      * objects (by the caller or by other transactions).<br>
59      * <b>-</b> Query processing can block the server for a long time.<br>
60      * <b>-</b> In comparison to the other modes it will take longest until the first results
61      * are returned.<br>
62      * <b>-</b> The ObjectSet will require a considerate amount of memory to hold the IDs of
63      * all found objects.<br><br>
64      * <b>Snapshot</b> mode<br>
65      * <b>+</b> Index processing will happen without possible side effects from changes made
66      * by the caller or by other transaction.<br>
67      * <b>+</b> Since index processing is fast, a server will not be blocked for a long time.<br>
68      * <b>-</b> The entire candidate index will be loaded into memory. It will stay there
69      * until the query ObjectSet is garbage collected. In a C/S setup, the memory will
70      * be used on the server side.<br><br>
71      * <b>Lazy</b> mode<br>
72      * <b>+</b> The call to {@link Query#execute()} will return very fast. First results can be
73      * made available to the application before the query is fully processed.<br>
74      * <b>+</b> A query will consume hardly any memory at all because no intermediate ID
75      * representation is ever created.<br>
76      * <b>-</b> Lazy queries check candidates when iterating through the resulting {@link ObjectSet}.
77      * In doing so the query processor takes changes into account that may have happened
78      * since the Query#execute()call: committed changes from other transactions, <b>and
79      * uncommitted changes from the calling transaction</b>. There is a wide range
80      * of possible side effects. The underlying index may have changed. Objects themselves
81      * may have changed in the meanwhile. There even is the chance of creating an endless
82      * loop, if the caller of the iterates through the {@link ObjectSet} and changes each
83      * object in a way that it is placed at the end of the index: The same objects can be
84      * revisited over and over. <b>In lazy mode it can make sense to work in a way one would
85      * work with collections to avoid concurrent modification exceptions.</b> For instance one
86      * could iterate through the {@link ObjectSet} first and store all objects to a temporary
87      * other collection representation before changing objects and storing them back to db4o.<br><br>
88      * Note: Some method calls against a lazy {@link ObjectSet} will require the query
89      * processor to create a snapshot or to evaluate the query fully. An example of such
90      * a call is {@link ObjectSet#size()}.
91      * <br><br>
92      * The default query evaluation mode is <b>Immediate</b> mode.
93      * <br><br>
94      * Recommendations:<br>
95      * - <b>Lazy</b> mode can be an excellent choice for single transaction read use,
96      * to keep memory consumption as low as possible.<br>
97      * - Client/Server applications with the risk of concurrent modifications should prefer
98      * <b>Snapshot</b> mode to avoid side effects from other transactions.
99      * <br><br>
100      * To change the evaluationMode, pass any of the three static {@link QueryEvaluationMode}
101      * constants from the {@link QueryEvaluationMode} class to this method:<br>
102      * - {@link QueryEvaluationMode#IMMEDIATE}<br>
103      * - {@link QueryEvaluationMode#SNAPSHOT}<br>
104      * - {@link QueryEvaluationMode#LAZY}
105      */

106     public void evaluationMode(QueryEvaluationMode mode);
107     
108
109 }
110
Popular Tags