KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > odbms > Query


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 JavaDoc 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 JavaDoc 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 JavaDoc 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
121
Popular Tags