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: /**
022: * constraint to limit the objects returned upon
023: * {@linkplain Query#execute() query execution}.
024: * <br><br>
025: * Constraints are constructed by calling
026: * {@link Query#constrain Query.constrain()}.
027: * <br><br>
028: * Constraints can be joined with the methods {@link #and and()}
029: * and {@link #or or()}.
030: * <br><br>
031: * The methods to modify the constraint evaluation algorithm may
032: * be merged, to construct combined evaluation rules.
033: * Examples:
034: * <ul>
035: * <li> <code>Constraint#smaller().equal()</code> for "smaller or equal" </li>
036: * <li> <code>Constraint#not().like()</code> for "not like" </li>
037: * <li> <code>Constraint#not().greater().equal()</code> for "not greater or equal" </li>
038: * </ul>
039: */
040: public interface Constraint {
041:
042: /**
043: * links two Constraints for AND evaluation.
044: * @param with the other {@link Constraint}
045: * @return a new {@link Constraint}, that can be used for further calls
046: * to {@link #and and()} and {@link #or or()}
047: */
048: public Constraint and(Constraint with);
049:
050: /**
051: * links two Constraints for OR evaluation.
052: * @param with the other {@link Constraint}
053: * @return a new {@link Constraint}, that can be used for further calls
054: * to {@link #and and()} and {@link #or or()}
055: */
056: public Constraint or(Constraint with);
057:
058: /**
059: * sets the evaluation mode to <code>==</code>.
060: * @return this {@link Constraint} to allow the chaining of method calls.
061: */
062: public Constraint equal();
063:
064: /**
065: * sets the evaluation mode to <code>></code>.
066: * @return this {@link Constraint} to allow the chaining of method calls.
067: */
068: public Constraint greater();
069:
070: /**
071: * sets the evaluation mode to <code><</code>.
072: * @return this {@link Constraint} to allow the chaining of method calls.
073: */
074: public Constraint smaller();
075:
076: /**
077: * sets the evaluation mode to identity comparison.
078: * @return this {@link Constraint} to allow the chaining of method calls.
079: */
080: public Constraint identity();
081:
082: /**
083: * sets the evaluation mode to "like" comparison.
084: * @return this {@link Constraint} to allow the chaining of method calls.
085: */
086: public Constraint like();
087:
088: /**
089: * sets the evaluation mode to containment comparison.
090: * <br><br>
091: * Evaluation is dependant on the constrained query node:
092: * <dl>
093: * <dt><code>String</code></dt>
094: * <dd>the persistent object is tested to contain a substring.</dd>
095: * <dt>arrays, {@linkplain java.util.Collection collections}</dt>
096: * <dd>the persistent object is tested to contain all elements of
097: * the constraining object.</dt>
098: * </dl>
099: * @return this {@link Constraint} to allow the chaining of method calls.
100: */
101: public Constraint contains();
102:
103: /**
104: * turns on not() comparison.
105: * @return this {@link Constraint} to allow the chaining of method calls.
106: */
107: public Constraint not();
108:
109: /**
110: * returns the Object the query graph was constrained with to
111: * create this {@link Constraint}.
112: * @return Object the constraining object.
113: */
114: public Object getObject();
115:
116: }
|