1 package org.odbms;
2
3 /* Copyright 2002-2005 The Apache Software Foundation
4 *
5 * Licensed under the Apache License, Version 2.0 (the "License");
6 * you may not use this file except in compliance with the License.
7 * You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 /**
19 * handle to a query graph and reference to a specific node.
20 * <br><br>The query graph consists of multiple nodes, each representing a
21 * class or a member of a class. The structure can be linked in
22 * any way that the class model used allows. A <code>Query</code>
23 * object references a single node of this graph. <br><br>The graph can
24 * be traversed with the functions descendant() and parent()
25 * which return references to other nodes of the graph. These two
26 * functions will automatically extend the graph, if necessary. <br><br>
27 * execute() evaluates the entire graph against the objects stored
28 * in the data container. execute() can be called from any node of the
29 * graph and will create an <a href="ObjectSet.html">
30 * <code>ObjectSet</code></a> filled with objects of the object type
31 * that the node, it was called from, represents. Objects for all
32 * descendant nodes of the caller <code>Query</code> object will be instantiated.
33 * Objects of parent nodes will not be visible in the <a href="ObjectSet.html">
34 * <code>ObjectSet</code></a> if they are
35 * not referenced from the caller <code>Query</code> object.
36 */
37 public interface Query {
38
39
40 /**
41 * adds a constraint to this node. <br>
42 * If the object parameter is deeper than the entire query graph,
43 * the query graph is extended accordingly.
44 * @param example object for comparison
45 * @return Constraint
46 */
47 public Constraint constrain (Object example);
48
49
50
51 /**
52 * executes the query.
53 * @return ObjectSet - the resultset of the Query
54 */
55 public ObjectSet execute ();
56
57
58
59 /**
60 * returns a reference to a descendant node in the query graph.
61 * If the node does not exist, it will be created.
62 * Path notation:<br>
63 * <code>"[membername].[membername].[membername]"</code><br>
64 * (any number of members)<br><br>
65 * To request references to elements of multi-element objects like
66 * arrays, lists, vectors, maps, hashMaps, ...:<br>
67 * <code>"[membername].[membername].[membername]<b>.</b>"</code><br>
68 * (Note the extra "." at the end.)<br>
69 * @param path path to the descendant. "[membername].[membername]"
70 * @return Query descendant node - the member node at the end of the
71 * <code>path</code> specified.
72 */
73 public Query descendant (String path);
74
75
76 /**
77 * returns a reference to a parent node in the query graph.
78 * If the node does not exist, it will be created.
79 * Path notation:<br>
80 * <code>"[classname].[membername].[membername]"</code>
81 * <br>where the last member is this Query node.
82 * @param path to the parent node "[classname].[membername]"
83 * @return Query parent node - the class node at the beginning of the
84 * <code>path</code> specified.
85 */
86 public Query parent (String path);
87
88
89 /**
90 * limits the maximum amount of objects returned.
91 * Especially for sorted queries, large performance advantages are
92 * possible.
93 * @param count - the maximum amount of objects desired.
94 * @return this Query to allow the chaining of method calls
95 */
96 public Query limitSize (int count);
97
98
99 /**
100 * adds an ascending order criteria to this node of
101 * the query graph. In case of multiple calls to ordering
102 * methods, the query graph is ordered by all criteria in the
103 * order they were called.<br><br>
104 * @return this Query to allow the chaining of method calls
105 */
106 public Query orderAscending ();
107
108
109 /**
110 * adds a descending order criteria to this node of
111 * the query graph. In case of multiple calls to ordering
112 * methods, the query graph is ordered by all criteria in the
113 * order they were called.<br><br>
114 * @return this Query to allow the chaining of method calls
115 */
116 public Query orderDescending ();
117
118
119 }
120