| Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
| Query |
|
| 1.0;1 |
| 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 |