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: /**
024: * constraint to limit the objects returned upon
025: * {@link Query#execute() query execution}.
026: * <br><br>
027: * Constraints are constructed by calling
028: * {@link Query#constrain(Object)}.
029: * <br><br>
030: * Constraints can be joined with the methods {@link #and}
031: * and {@link #or}.
032: * <br><br>
033: * The methods to modify the constraint evaluation algorithm may
034: * be merged, to construct combined evaluation rules.
035: * Examples:
036: * <ul>
037: * <li> <code>Constraint#smaller().equal()</code> for "smaller or equal" </li>
038: * <li> <code>Constraint#not().like()</code> for "not like" </li>
039: * <li> <code>Constraint#not().greater().equal()</code> for "not greater or equal" </li>
040: * </ul>
041: */
042: public interface Constraint {
043:
044: /**
045: * links two Constraints for AND evaluation.
046: * For example:<br>
047: * <code>query.constrain(Pilot.class);</code><br>
048: * <code>query.descend("points").constrain(101).smaller().and(query.descend("name").constrain("Test Pilot0")); </code><br>
049: * will retrieve all pilots with points less than 101 and name as "Test Pilot0"<br>
050: * @param with the other {@link Constraint}
051: * @return a new {@link Constraint}, that can be used for further calls
052: * to {@link #and and()} and {@link #or or()}
053: */
054: public Constraint and(Constraint with);
055:
056: /**
057: * links two Constraints for OR evaluation.
058: * For example:<br><br>
059: * <code>query.constrain(Pilot.class);</code><br>
060: * <code>query.descend("points").constrain(101).greater().or(query.descend("name").constrain("Test Pilot0"));</code><br>
061: * will retrieve all pilots with points more than 101 or pilots with the name "Test Pilot0"<br>
062: * @param with the other {@link Constraint}
063: * @return a new {@link Constraint}, that can be used for further calls
064: * to {@link #and and()} and {@link #or or()}
065: */
066: public Constraint or(Constraint with);
067:
068: /**
069: * Used in conjunction with {@link #smaller()} or {@link #greater()} to create constraints
070: * like "smaller or equal", "greater or equal".
071: * For example:<br>
072: * <code>query.constrain(Pilot.class);</code><br>
073: * <code>query.descend("points").constrain(101).smaller().equal();</code><br>
074: * will return all pilots with points <= 101.<br>
075: * @return this {@link Constraint} to allow the chaining of method calls.
076: */
077: public Constraint equal();
078:
079: /**
080: * sets the evaluation mode to <code>></code>.
081: * For example:<br>
082: * <code>query.constrain(Pilot.class);</code><br>
083: * <code>query.descend("points").constrain(101).greater()</code><br>
084: * will return all pilots with points > 101.<br>
085: * @return this {@link Constraint} to allow the chaining of method calls.
086: */
087: public Constraint greater();
088:
089: /**
090: * sets the evaluation mode to <code><</code>.
091: * For example:<br>
092: * <code>query.constrain(Pilot.class);</code><br>
093: * <code>query.descend("points").constrain(101).smaller()</code><br>
094: * will return all pilots with points < 101.<br>
095: * @return this {@link Constraint} to allow the chaining of method calls.
096: */
097: public Constraint smaller();
098:
099: /**
100: * sets the evaluation mode to identity comparison. In this case only
101: * objects having the same database identity will be included in the result set.
102: * For example:<br>
103: * <code>Pilot pilot = new Pilot("Test Pilot1", 100);</code><br>
104: * <code>Car car = new Car("BMW", pilot);</code><br>
105: * <code>container.set(car);</code><br>
106: * <code>// Change the name, the pilot instance stays the same</code><br>
107: * <code>pilot.setName("Test Pilot2");</code><br>
108: * <code>// create a new car</code><br>
109: * <code>car = new Car("Ferrari", pilot);</code><br>
110: * <code>container.set(car);</code><br>
111: * <code>Query query = container.query();</code><br>
112: * <code>query.constrain(Car.class);</code><br>
113: * <code>// All cars having pilot with the same database identity</code><br>
114: * <code>// will be retrieved. As we only created Pilot object once</code><br>
115: * <code>// it should mean all car objects</code><br>
116: * <code>query.descend("_pilot").constrain(pilot).identity();</code><br><br>
117: * @return this {@link Constraint} to allow the chaining of method calls.
118: */
119: public Constraint identity();
120:
121: /**
122: * sets the evaluation mode to "like" comparison. This mode will include
123: * all objects having the constrain expression somewhere inside the string field.
124: * For example:<br>
125: * <code>Pilot pilot = new Pilot("Test Pilot1", 100);</code><br>
126: * <code>container.set(pilot);</code><br>
127: * <code> ...</code><br>
128: * <code>query.constrain(Pilot.class);</code><br>
129: * <code>// All pilots with the name containing "est" will be retrieved</code><br>
130: * <code>query.descend("name").constrain("est").like();</code><br>
131: * @return this {@link Constraint} to allow the chaining of method calls.
132: */
133: public Constraint like();
134:
135: /**
136: * sets the evaluation mode to containment comparison.
137: * For example:<br>
138: * <code>Pilot pilot1 = new Pilot("Test 1", 1);</code><br>
139: * <code>list.add(pilot1);</code><br>
140: * <code>Pilot pilot2 = new Pilot("Test 2", 2);</code><br>
141: * <code>list.add(pilot2);</code><br>
142: * <code>Team team = new Team("Ferrari", list);</code><br>
143: * <code>container.set(team);</code><br>
144: * <code>Query query = container.query();</code><br>
145: * <code>query.constrain(Team.class);</code><br>
146: * <code>query.descend("pilots").constrain(pilot2).contains();</code><br>
147: * will return the Team object as it contains pilot2.<br>
148: * If applied to a String object, this constrain will behave as {@link #like()}.
149: * @return this {@link Constraint} to allow the chaining of method calls.
150: */
151: public Constraint contains();
152:
153: /**
154: * sets the evaluation mode to string startsWith comparison.
155: * For example:<br>
156: * <code>Pilot pilot = new Pilot("Test Pilot0", 100);</code><br>
157: * <code>container.set(pilot);</code><br>
158: * <code> ...</code><br>
159: * <code>query.constrain(Pilot.class);</code><br>
160: * <code>query.descend("name").constrain("Test").startsWith(true);</code><br>
161: * @param caseSensitive comparison will be case sensitive if true, case insensitive otherwise
162: * @return this {@link Constraint} to allow the chaining of method calls.
163: */
164: public Constraint startsWith(boolean caseSensitive);
165:
166: /**
167: * sets the evaluation mode to string endsWith comparison.
168: * For example:<br>
169: * <code>Pilot pilot = new Pilot("Test Pilot0", 100);</code><br>
170: * <code>container.set(pilot);</code><br>
171: * <code> ...</code><br>
172: * <code>query.constrain(Pilot.class);</code><br>
173: * <code>query.descend("name").constrain("T0").endsWith(false);</code><br>
174: * @param caseSensitive comparison will be case sensitive if true, case insensitive otherwise
175: * @return this {@link Constraint} to allow the chaining of method calls.
176: */
177: public Constraint endsWith(boolean caseSensitive);
178:
179: /**
180: * turns on not() comparison. All objects not fullfilling the constrain condition will be returned.
181: * For example:<br>
182: * <code>Pilot pilot = new Pilot("Test Pilot1", 100);</code><br>
183: * <code>container.set(pilot);</code><br>
184: * <code> ...</code><br>
185: * <code>query.constrain(Pilot.class);</code><br>
186: * <code>query.descend("name").constrain("t0").endsWith(true).not();</code><br>
187: * @return this {@link Constraint} to allow the chaining of method calls.
188: */
189: public Constraint not();
190:
191: /**
192: * returns the Object the query graph was constrained with to
193: * create this {@link Constraint}.
194: * @return Object the constraining object.
195: */
196: public Object getObject();
197:
198: }
|