001: /* Copyright (C) 2004 - 2007 db4objects Inc. http://www.db4o.com
002:
003: This file is part of the db4o open source object database.
004:
005: db4o is free software; you can redistribute it and/or modify it under
006: the terms of version 2 of the GNU General Public License as published
007: by the Free Software Foundation and as clarified by db4objects' GPL
008: interpretation policy, available at
009: http://www.db4o.com/about/company/legalpolicies/gplinterpretation/
010: Alternatively you can write to db4objects, Inc., 1900 S Norfolk Street,
011: Suite 350, San Mateo, CA 94403, USA.
012:
013: db4o is distributed in the hope that it will be useful, but WITHOUT ANY
014: WARRANTY; without even the implied warranty of MERCHANTABILITY or
015: FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
016: for more details.
017:
018: You should have received a copy of the GNU General Public License along
019: with this program; if not, write to the Free Software Foundation, Inc.,
020: 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. */
021: package com.db4o.query;
022:
023: import java.util.*;
024:
025: import com.db4o.*;
026:
027: /**
028: * handle to a node in a S.O.D.A. query graph.
029: * <br><br>
030: * A node in the query graph can represent multiple
031: * classes, one class or an attribute of a class.<br><br>The graph
032: * is automatically extended with attributes of added constraints
033: * (see {@link #constrain(java.lang.Object)}) and upon calls to {@link #descend(java.lang.String)} that request nodes that do not yet exist.
034: * <br><br>
035: * References to joined nodes in the query graph can be obtained
036: * by "walking" along the nodes of the graph with the method
037: * {@link #descend(java.lang.String)}.
038: * <br><br>
039: * {@link #execute()}
040: * evaluates the entire graph against all persistent objects.
041: * <br><br>
042: * {@link #execute()} can be called from any {@link Query} node
043: * of the graph. It will return an {@link ObjectSet} filled with
044: * objects of the class/classes that the node, it was called from,
045: * represents.<br><br>
046: * <b>Note:<br>
047: * {@link Predicate Native queries} are the recommended main query
048: * interface of db4o.</b>
049: */
050: public interface Query {
051:
052: /**
053: * adds a constraint to this node.
054: * <br><br>
055: * If the constraint contains attributes that are not yet
056: * present in the query graph, the query graph is extended
057: * accordingly.
058: * <br><br>
059: * Special behaviour for:
060: * <ul>
061: * <li> class {@link Class}: confine the result to objects of one
062: * class or to objects implementing an interface.</li>
063: * <li> interface {@link Evaluation}: run
064: * evaluation callbacks against all candidates.</li>
065: * </ul>
066: * @param constraint the constraint to be added to this Query.
067: * @return {@link Constraint} a new {@link Constraint} for this
068: * query node or <code>null</code> for objects implementing the
069: * {@link Evaluation} interface.
070: */
071: public Constraint constrain(Object constraint);
072:
073: /**
074: * returns a {@link Constraints}
075: * object that holds an array of all constraints on this node.
076: * @return {@link Constraints} on this query node.
077: */
078: public Constraints constraints();
079:
080: /**
081: * returns a reference to a descendant node in the query graph.
082: * <br><br>If the node does not exist, it will be created.
083: * <br><br>
084: * All classes represented in the query node are tested, whether
085: * they contain a field with the specified field name. The
086: * descendant Query node will be created from all possible candidate
087: * classes.
088: * @param fieldName path to the descendant.
089: * @return descendant {@link Query} node
090: */
091: public Query descend(String fieldName);
092:
093: /**
094: * executes the {@link Query}.
095: * @return {@link ObjectSet} - the result of the {@link Query}.
096: */
097: public ObjectSet execute();
098:
099: /**
100: * adds an ascending ordering criteria to this node of
101: * the query graph.
102: * <p>
103: * If multiple ordering criteria are applied, the chronological
104: * order of method calls is relevant: criteria created by 'earlier' calls are
105: * considered more significant, i.e. 'later' criteria only have an effect
106: * for elements that are considered equal by all 'earlier' criteria.
107: * <p>
108: * As an example, consider a type with two int fields, and an instance set
109: * {(a:1,b:3),(a:2,b:2),(a:1,b:2),(a:2,b:3)}. The call sequence [orderAscending(a),
110: * orderDescending(b)] will result in [(<b>a:1</b>,b:3),(<b>a:1</b>,b:2),(<b>a:2</b>,b:3),(<b>a:2</b>,b:2)].
111: * @return this {@link Query} object to allow the chaining of method calls.
112: */
113: public Query orderAscending();
114:
115: /**
116: * adds a descending order criteria to this node of
117: * the query graph.
118: * <br><br>
119: * For semantics of multiple calls setting ordering criteria, see {@link #orderAscending()}.
120: * @return this {@link Query} object to allow the chaining of method calls.
121: */
122: public Query orderDescending();
123:
124: /**
125: * Sort the resulting ObjectSet by the given comparator.
126: *
127: * @param comparator The comparator to apply.
128: * @return this {@link Query} object to allow the chaining of method calls.
129: */
130: public Query sortBy(QueryComparator comparator);
131:
132: /**
133: * Sort the resulting ObjectSet by the given comparator.
134: *
135: * @param comparator The comparator to apply.
136: * @return this {@link Query} object to allow the chaining of method calls.
137: */
138: public Query sortBy(Comparator comparator);
139:
140: // /**
141: // * defines a Query node to be represented as a column in the array
142: // * returned in every element of the ObjectSet upon query execution.
143: // * @param node the Query node to be represented
144: // * @param column the column in the result array
145: // */
146: // public void result(Query node, int column);
147: //
148: }
|