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: * adds a constraint to this node. <br>
041: * If the object parameter is deeper than the entire query graph,
042: * the query graph is extended accordingly.
043: * @param example object for comparison
044: * @return Constraint
045: */
046: public Constraint constrain(Object example);
047:
048: /**
049: * executes the query.
050: * @return ObjectSet - the resultset of the Query
051: */
052: public ObjectSet execute();
053:
054: /**
055: * returns a reference to a descendant node in the query graph.
056: * If the node does not exist, it will be created.
057: * Path notation:<br>
058: * <code>"[membername].[membername].[membername]"</code><br>
059: * (any number of members)<br><br>
060: * To request references to elements of multi-element objects like
061: * arrays, lists, vectors, maps, hashMaps, ...:<br>
062: * <code>"[membername].[membername].[membername]<b>.</b>"</code><br>
063: * (Note the extra "." at the end.)<br>
064: * @param path path to the descendant. "[membername].[membername]"
065: * @return Query descendant node - the member node at the end of the
066: * <code>path</code> specified.
067: */
068: public Query descendant(String path);
069:
070: /**
071: * returns a reference to a parent node in the query graph.
072: * If the node does not exist, it will be created.
073: * Path notation:<br>
074: * <code>"[classname].[membername].[membername]"</code>
075: * <br>where the last member is this Query node.
076: * @param path to the parent node "[classname].[membername]"
077: * @return Query parent node - the class node at the beginning of the
078: * <code>path</code> specified.
079: */
080: public Query parent(String path);
081:
082: /**
083: * limits the maximum amount of objects returned.
084: * Especially for sorted queries, large performance advantages are
085: * possible.
086: * @param count - the maximum amount of objects desired.
087: * @return this Query to allow the chaining of method calls
088: */
089: public Query limitSize(int count);
090:
091: /**
092: * adds an ascending order criteria to this node of
093: * the query graph. In case of multiple calls to ordering
094: * methods, the query graph is ordered by all criteria in the
095: * order they were called.<br><br>
096: * @return this Query to allow the chaining of method calls
097: */
098: public Query orderAscending();
099:
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: }
|