001 package org.odbms;
002
003 /* Copyright 2002-2005 The Apache Software Foundation
004 *
005 * Licensed under the Apache License, Version 2.0 (the "License");
006 * you may not use this file except in compliance with the License.
007 * You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017
018 /**
019 * handle to a query graph and reference to a specific node.
020 * <br><br>The query graph consists of multiple nodes, each representing a
021 * class or a member of a class. The structure can be linked in
022 * any way that the class model used allows. A <code>Query</code>
023 * object references a single node of this graph. <br><br>The graph can
024 * be traversed with the functions descendant() and parent()
025 * which return references to other nodes of the graph. These two
026 * functions will automatically extend the graph, if necessary. <br><br>
027 * execute() evaluates the entire graph against the objects stored
028 * in the data container. execute() can be called from any node of the
029 * graph and will create an <a href="ObjectSet.html">
030 * <code>ObjectSet</code></a> filled with objects of the object type
031 * that the node, it was called from, represents. Objects for all
032 * descendant nodes of the caller <code>Query</code> object will be instantiated.
033 * Objects of parent nodes will not be visible in the <a href="ObjectSet.html">
034 * <code>ObjectSet</code></a> if they are
035 * not referenced from the caller <code>Query</code> object.
036 */
037 public interface Query {
038
039
040 /**
041 * adds a constraint to this node. <br>
042 * If the object parameter is deeper than the entire query graph,
043 * the query graph is extended accordingly.
044 * @param example object for comparison
045 * @return Constraint
046 */
047 public Constraint constrain (Object example);
048
049
050
051 /**
052 * executes the query.
053 * @return ObjectSet - the resultset of the Query
054 */
055 public ObjectSet execute ();
056
057
058
059 /**
060 * returns a reference to a descendant node in the query graph.
061 * If the node does not exist, it will be created.
062 * Path notation:<br>
063 * <code>"[membername].[membername].[membername]"</code><br>
064 * (any number of members)<br><br>
065 * To request references to elements of multi-element objects like
066 * arrays, lists, vectors, maps, hashMaps, ...:<br>
067 * <code>"[membername].[membername].[membername]<b>.</b>"</code><br>
068 * (Note the extra "." at the end.)<br>
069 * @param path path to the descendant. "[membername].[membername]"
070 * @return Query descendant node - the member node at the end of the
071 * <code>path</code> specified.
072 */
073 public Query descendant (String path);
074
075
076 /**
077 * returns a reference to a parent node in the query graph.
078 * If the node does not exist, it will be created.
079 * Path notation:<br>
080 * <code>"[classname].[membername].[membername]"</code>
081 * <br>where the last member is this Query node.
082 * @param path to the parent node "[classname].[membername]"
083 * @return Query parent node - the class node at the beginning of the
084 * <code>path</code> specified.
085 */
086 public Query parent (String path);
087
088
089 /**
090 * limits the maximum amount of objects returned.
091 * Especially for sorted queries, large performance advantages are
092 * possible.
093 * @param count - the maximum amount of objects desired.
094 * @return this Query to allow the chaining of method calls
095 */
096 public Query limitSize (int count);
097
098
099 /**
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