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