001: /*
002: Copyright (C) 2007 Mobixess Inc. http://www.java-objects-database.com
003:
004: This file is part of the JODB (Java Objects Database) open source project.
005:
006: JODB is free software; you can redistribute it and/or modify it under
007: the terms of version 2 of the GNU General Public License as published
008: by the Free Software Foundation.
009:
010: JODB is distributed in the hope that it will be useful, but WITHOUT ANY
011: WARRANTY; without even the implied warranty of MERCHANTABILITY or
012: FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
013: for more details.
014:
015: You should have received a copy of the GNU General Public License along
016: with this program; if not, write to the Free Software Foundation, Inc.,
017: 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
018: */
019: package com.mobixess.jodb.soda.api;
020:
021: import java.io.IOException;
022:
023: import com.mobixess.jodb.core.IllegalClassTypeException;
024:
025: /**
026: * handle to a node in the query graph.
027: * <br><br>
028: * A node in the query graph can represent multiple
029: * classes, one class or an attribute of a class.<br><br>The graph
030: * is automatically extended with attributes of added constraints
031: * (see {@link #constrain constrain()})
032: * and upon calls to
033: * {@link #descend(java.lang.String) descend()}
034: * that request nodes that do not yet exist.
035: * <br><br>
036: * References to joined nodes in the query graph kann be obtained
037: * by "walking" along the nodes of the graph with the method
038: * {@link #descend(java.lang.String) descend()}.
039: * <br><br>
040: * {@link #execute()}
041: * evaluates the entire graph against all persistent objects.
042: * <br><br>
043: * {@link #execute()} can be called from any {@link Query} node
044: * of the graph. It will return an {@link ObjectSet} filled with
045: * objects of the class/classes that the node, it was called from,
046: * represents.
047: */
048: public interface Query {
049:
050: /**
051: * adds a constraint to this node.
052: * <br><br>
053: * If the constraint contains attributes that are not yet
054: * present in the query graph, the query graph is extended
055: * accordingly.
056: * <br><br>
057: * Special behaviour for:
058: * <ul>
059: * <li> class {@link Class}: confine the result to objects of one
060: * class (if the {@link Class} object represents a class)
061: * or to objects implementing a specific interface
062: * (if the {@link Class} object represents 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: * executes the {@link Query}.
082: * @return {@link ObjectSet} - the result of the {@link Query}.
083: * @throws IOException
084: * @throws IllegalClassTypeException
085: */
086: public ObjectSet execute() throws IOException,
087: IllegalClassTypeException;
088:
089: /**
090: * returns a reference to a descendant node in the query graph.
091: * <br><br>If the node does not exist, it will be created.
092: * <br><br>
093: * All classes represented in the query node are tested, whether
094: * they contain a field with the specified field name. The
095: * descendant Query node will be created from all possible candidate
096: * classes.
097: * @param field path to the descendant.
098: * @return descendant {@link Query} node
099: */
100: public Query descend(String fieldName);
101:
102: /**
103: * adds an ascending ordering criteria to this node of
104: * the query graph. Multiple ordering criteria will be applied
105: * in the order they were called.
106: * @return this {@link Query} object to allow the chaining of method calls.
107: */
108: public Query orderAscending();
109:
110: /**
111: * adds a descending order criteria to this node of
112: * the query graph. Multiple ordering criteria will be applied
113: * in the order they were called.
114: * @return this {@link Query} object to allow the chaining of method calls.
115: */
116: public Query orderDescending();
117:
118: }
|