KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > db4o > query > Query


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.query;
22
23 import com.db4o.*;
24
25
26 /**
27  * handle to a node in a S.O.D.A. query graph.
28  * <br><br>
29  * A node in the query graph can represent multiple
30  * classes, one class or an attribute of a class.<br><br>The graph
31  * is automatically extended with attributes of added constraints
32  * (see {@link #constrain(java.lang.Object)}) and upon calls to {@link #descend(java.lang.String)} that request nodes that do not yet exist.
33  * <br><br>
34  * References to joined nodes in the query graph can be obtained
35  * by "walking" along the nodes of the graph with the method
36  * {@link #descend(java.lang.String)}.
37  * <br><br>
38  * {@link #execute()}
39  * evaluates the entire graph against all persistent objects.
40  * <br><br>
41  * {@link #execute()} can be called from any {@link Query} node
42  * of the graph. It will return an {@link ObjectSet} filled with
43  * objects of the class/classes that the node, it was called from,
44  * represents.<br><br>
45  * <b>Note:<br>
46  * {@link Predicate Native queries} are the recommended main query
47  * interface of db4o.</b>
48  */
49 public interface Query {
50
51
52     /**
53      * adds a constraint to this node.
54      * <br><br>
55      * If the constraint contains attributes that are not yet
56      * present in the query graph, the query graph is extended
57      * accordingly.
58      * <br><br>
59      * Special behaviour for:
60      * <ul>
61      * <li> class {@link Class}: confine the result to objects of one
62      * class or to objects implementing an interface.</li>
63      * <li> interface {@link Evaluation}: run
64      * evaluation callbacks against all candidates.</li>
65      * </ul>
66      * @param constraint the constraint to be added to this Query.
67      * @return {@link Constraint} a new {@link Constraint} for this
68      * query node or <code>null</code> for objects implementing the
69      * {@link Evaluation} interface.
70      */
71     public Constraint constrain (Object JavaDoc constraint);
72
73     
74     /**
75      * returns a {@link Constraints}
76      * object that holds an array of all constraints on this node.
77      * @return {@link Constraints} on this query node.
78      */
79     public Constraints constraints();
80
81
82     /**
83      * returns a reference to a descendant node in the query graph.
84      * <br><br>If the node does not exist, it will be created.
85      * <br><br>
86      * All classes represented in the query node are tested, whether
87      * they contain a field with the specified field name. The
88      * descendant Query node will be created from all possible candidate
89      * classes.
90      * @param fieldName path to the descendant.
91      * @return descendant {@link Query} node
92      */
93     public Query descend (String JavaDoc fieldName);
94
95
96     /**
97      * executes the {@link Query}.
98      * @return {@link ObjectSet} - the result of the {@link Query}.
99      */
100     public ObjectSet execute ();
101
102     
103     /**
104      * adds an ascending ordering criteria to this node of
105      * the query graph. Multiple ordering criteria will be applied
106      * in the order they were called.
107      * @return this {@link Query} object to allow the chaining of method calls.
108      */
109     public Query orderAscending ();
110
111
112     /**
113      * adds a descending order criteria to this node of
114      * the query graph. Multiple ordering criteria will be applied
115      * in the order they were called.
116      * @return this {@link Query} object to allow the chaining of method calls.
117      */
118     public Query orderDescending ();
119     
120     /**
121      * Sort the resulting ObjectSet by the given comparator.
122      *
123      * @param comparator The comparator to apply.
124      * @return this {@link Query} object to allow the chaining of method calls.
125      */
126     public Query sortBy(QueryComparator comparator);
127
128     
129 // /**
130 // * defines a Query node to be represented as a column in the array
131 // * returned in every element of the ObjectSet upon query execution.
132 // * @param node the Query node to be represented
133 // * @param column the column in the result array
134 // */
135 // public void result(Query node, int column);
136 //
137 }
138
139
Popular Tags