001: /*
002: * ====================================================================
003: * JAFFA - Java Application Framework For All
004: *
005: * Copyright (C) 2002 JAFFA Development Group
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation; either
010: * version 2.1 of the License, or (at your option) any later version.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: *
017: * You should have received a copy of the GNU Lesser General Public
018: * License along with this library; if not, write to the Free Software
019: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
020: *
021: * Redistribution and use of this software and associated documentation ("Software"),
022: * with or without modification, are permitted provided that the following conditions are met:
023: * 1. Redistributions of source code must retain copyright statements and notices.
024: * Redistributions must also contain a copy of this document.
025: * 2. Redistributions in binary form must reproduce the above copyright notice,
026: * this list of conditions and the following disclaimer in the documentation
027: * and/or other materials provided with the distribution.
028: * 3. The name "JAFFA" must not be used to endorse or promote products derived from
029: * this Software without prior written permission. For written permission,
030: * please contact mail to: jaffagroup@yahoo.com.
031: * 4. Products derived from this Software may not be called "JAFFA" nor may "JAFFA"
032: * appear in their names without prior written permission.
033: * 5. Due credit should be given to the JAFFA Project (http://jaffa.sourceforge.net).
034: *
035: * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED
036: * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
037: * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
038: * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
039: * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
040: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
041: * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
042: * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
043: * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
044: * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
045: * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
046: * SUCH DAMAGE.
047: * ====================================================================
048: */
049:
050: package org.jaffa.persistence;
051:
052: import java.io.Serializable;
053: import java.util.*;
054:
055: /** This object is used by the persistence layer to query the underlying store.
056: */
057: public class Criteria implements Serializable {
058:
059: /** The static to be used in OrderBy declarations to indicate an ascending sort*/
060: public final static int ORDER_BY_ASC = 0x01;
061:
062: /** The static to be used in OrderBy declarations to indicate an descending sort*/
063: public final static int ORDER_BY_DESC = 0x02;
064:
065: /** The static to be used in criteria declarations to indicate an = operator */
066: public final static int RELATIONAL_EQUALS = 0x03;
067:
068: /** The static to be used in criteria declarations to indicate a != operator */
069: public final static int RELATIONAL_NOT_EQUALS = 0x04;
070:
071: /** The static to be used in criteria declarations to indicate an > operator */
072: public final static int RELATIONAL_GREATER_THAN = 0x05;
073:
074: /** The static to be used in criteria declarations to indicate an < operator */
075: public final static int RELATIONAL_SMALLER_THAN = 0x06;
076:
077: /** The static to be used in criteria declarations to indicate an >= operator */
078: public final static int RELATIONAL_GREATER_THAN_EQUAL_TO = 0x07;
079:
080: /** The static to be used in criteria declarations to indicate an <= operator */
081: public final static int RELATIONAL_SMALLER_THAN_EQUAL_TO = 0x08;
082:
083: /** The static to be used in criteria declarations to indicate an 'is not null' operator */
084: public final static int RELATIONAL_IS_NOT_NULL = 0x09;
085:
086: /** The static to be used in criteria declarations to indicate an 'is null' operator */
087: public final static int RELATIONAL_IS_NULL = 0x0A;
088:
089: /** The static to be used in criteria declarations to create a construct of the type "like 'Abc%'"*/
090: public final static int RELATIONAL_BEGINS_WITH = 0x0B;
091:
092: /** The static to be used in criteria declarations to create a construct of the type "like '%Abc'"*/
093: public final static int RELATIONAL_ENDS_WITH = 0x0C;
094:
095: /** The static to be used in criteria declarations to create a construct of the type "like '%Abc%'"*/
096: public final static int RELATIONAL_LIKE = 0x0D;
097:
098: /** Use this static to indicate optimistic locking on a query.
099: * The record in the database will be locked, only when the persistent object is added to the database.
100: * This is the default locking strategy.
101: */
102: public static final int LOCKING_OPTIMISTIC = 0x0E;
103:
104: /** Use this static to indicate pessimistic locking on a query.
105: * The record in the database will be locked, whenever a field is updated on the object.
106: */
107: public static final int LOCKING_PESSIMISTIC = 0x0F;
108:
109: /** Use this static to indicate paranoid locking on a query.
110: * The record in the database will be locked, at the instant it is read.
111: */
112: public static final int LOCKING_PARANOID = 0x10;
113:
114: /** Use this static to indicate that the persistent object cannot be modified.
115: */
116: public static final int LOCKING_READ_ONLY = 0x11;
117:
118: private String m_table = null;
119: private int m_locking = LOCKING_OPTIMISTIC;
120: private Collection m_criteriaEntries = new ArrayList();
121: private Collection m_aggregates = null;
122: private Collection m_innerCriteriaEntries = null;
123: private Collection m_orderBy = null;
124: private UOW m_uow = null;
125:
126: /** Returns the UOW against which the query is to be performed.
127: * @return the UOW against which the query is to be performed.
128: */
129: public UOW getUow() {
130: return m_uow;
131: }
132:
133: /** Sets the UOW on the criteria. This is mainly used by the DataSource to assign the UOW on the persistent objects.
134: * @param uow The UOW.
135: */
136: void setUow(UOW uow) {
137: m_uow = uow;
138: }
139:
140: /** Returns the name of the persistent class on which the query is to be performed.
141: * @return the name of the persistent class.
142: */
143: public String getTable() {
144: return m_table;
145: }
146:
147: /** Set the persistent class name. This will determine the database-table on which the query is to be performed.
148: * @param table The name of the persistent class.
149: */
150: public void setTable(String table) {
151: m_table = table;
152: }
153:
154: /** Returns the locking strategy for a query.
155: * @return the locking strategy for a query.
156: */
157: public int getLocking() {
158: return m_locking;
159: }
160:
161: /** Set the locking strategy for a query.
162: * @param locking the locking strategy.
163: */
164: public void setLocking(int locking) {
165: m_locking = locking;
166: }
167:
168: /** Add a criteria entry. The operator '=' is used.
169: * @param name The name of the field.
170: * @param value The value to be assigned to the field.
171: */
172: public void addCriteria(String name, Object value) {
173: m_criteriaEntries.add(new CriteriaEntry(name, value));
174: }
175:
176: /** Add a criteria entry.
177: * @param name The name of the field.
178: * @param operator The operator to be used in the assignment.
179: * @param value The value to be assigned to the field.
180: */
181: public void addCriteria(String name, int operator, Object value) {
182: m_criteriaEntries.add(new CriteriaEntry(name, operator, value));
183: }
184:
185: /** Add a criteria entry. This method is to be used for unary operator like 'null' and 'not null'.
186: * @param name The name of the field.
187: * @param operator The operator to be used in the assignment.
188: */
189: public void addCriteria(String name, int operator) {
190: m_criteriaEntries.add(new CriteriaEntry(name, operator));
191: }
192:
193: /** Add an OR criteria entry. The operator '=' is used.
194: * @param name The name of the field.
195: * @param value The value to be assigned to the field.
196: */
197: public void addOrCriteria(String name, Object value) {
198: CriteriaEntry criteriaEntry = new CriteriaEntry(name, value);
199: criteriaEntry.setLogic(CriteriaEntry.LOGICAL_OR);
200: m_criteriaEntries.add(criteriaEntry);
201: }
202:
203: /** Add an OR criteria entry.
204: * @param name The name of the field.
205: * @param operator The operator to be used in the assignment.
206: * @param value The value to be assigned to the field.
207: */
208: public void addOrCriteria(String name, int operator, Object value) {
209: CriteriaEntry criteriaEntry = new CriteriaEntry(name, operator,
210: value);
211: criteriaEntry.setLogic(CriteriaEntry.LOGICAL_OR);
212: m_criteriaEntries.add(criteriaEntry);
213: }
214:
215: /** Add an OR criteria entry. This method is to be used for unary operator like 'null' and 'not null'.
216: * @param name The name of the field.
217: * @param operator The operator to be used in the assignment.
218: */
219: public void addOrCriteria(String name, int operator) {
220: CriteriaEntry criteriaEntry = new CriteriaEntry(name, operator);
221: criteriaEntry.setLogic(CriteriaEntry.LOGICAL_OR);
222: m_criteriaEntries.add(criteriaEntry);
223: }
224:
225: /** Add a dual criteria entry. The operator '=' is used.
226: * @param name The name of the first field.
227: * @param name2 The name of the second field.
228: */
229: public void addDualCriteria(String name, String name2) {
230: m_criteriaEntries.add(new CriteriaEntry(name, name2, true));
231: }
232:
233: /** Add a dual criteria entry.
234: * @param name The name of the first field.
235: * @param operator The operator to be used in the assignment.
236: * @param name2 The name of the second field.
237: */
238: public void addDualCriteria(String name, int operator, String name2) {
239: m_criteriaEntries.add(new CriteriaEntry(name, operator, name2,
240: true));
241: }
242:
243: /** Add a criteria entry to signify a join condition between 2 persistent classes. The operator '=' is used.
244: * @param name The field of the persistent class which corresponds to this Criteria object.
245: * @param name2 The field of the persistent class, against which the join is to be made.
246: */
247: public void addInnerCriteria(String name, String name2) {
248: if (m_innerCriteriaEntries == null)
249: m_innerCriteriaEntries = new ArrayList();
250: m_innerCriteriaEntries
251: .add(new CriteriaEntry(name, name2, true));
252: }
253:
254: /** Add a criteria entry to signify a join condition between 2 persistent classes.
255: * @param name The field of the persistent class which corresponds to this Criteria object.
256: * @param operator The operator to be used in the assignment.
257: * @param name2 The field of the persistent class, against which the join is to be made.
258: */
259: public void addInnerCriteria(String name, int operator, String name2) {
260: if (m_innerCriteriaEntries == null)
261: m_innerCriteriaEntries = new ArrayList();
262: m_innerCriteriaEntries.add(new CriteriaEntry(name, operator,
263: name2, true));
264: }
265:
266: /** Clears the inner criteria entries.
267: */
268: public void clearInnerCriteria() {
269: if (m_innerCriteriaEntries != null)
270: m_innerCriteriaEntries.clear();
271: }
272:
273: /** Add another criteria object to indicate a join.
274: * @param criteria The criteria object.
275: */
276: public void addAggregate(Criteria criteria) {
277: if (m_aggregates == null)
278: m_aggregates = new ArrayList();
279: m_aggregates.add(criteria);
280: }
281:
282: /** Add an atomic criteria object. This is used to create combinations of AND/OR clauses.
283: * @param atomicCriteria The atomic criteria object
284: */
285: public void addAtomic(AtomicCriteria atomicCriteria) {
286: AtomicCriteriaEntry atomicCriteriaEntry = new AtomicCriteriaEntry(
287: atomicCriteria);
288: atomicCriteriaEntry.setLogic(CriteriaEntry.LOGICAL_AND);
289: m_criteriaEntries.add(atomicCriteriaEntry);
290: }
291:
292: /** Add an OR-ed atomic criteria object. This is used to create combinations of AND/OR clauses.
293: * @param atomicCriteria The atomic criteria object
294: */
295: public void addOrAtomic(AtomicCriteria atomicCriteria) {
296: atomicCriteria.setOrLogic(true);
297: AtomicCriteriaEntry atomicCriteriaEntry = new AtomicCriteriaEntry(
298: atomicCriteria);
299: atomicCriteriaEntry.setLogic(CriteriaEntry.LOGICAL_OR);
300: m_criteriaEntries.add(atomicCriteriaEntry);
301: }
302:
303: /** Add an order by element, specifying the ordering type to be used.
304: * @param orderByElement The name of the field to be used in the order by clause.
305: * @param ordering indicates an ascending or a descending sort.
306: */
307: public void addOrderBy(String orderByElement, int ordering) {
308: if (m_orderBy == null)
309: m_orderBy = new ArrayList();
310: m_orderBy.add(new OrderBy(orderByElement, ordering));
311: }
312:
313: /** Clear the order by entries.
314: */
315: public void clearOrderBy() {
316: if (m_orderBy != null)
317: m_orderBy.clear();
318: }
319:
320: /** Returns the criteria entries.
321: * @return A collection of Criteria.CriteriaEntry objects.
322: */
323: public Collection getCriteriaEntries() {
324: return m_criteriaEntries;
325: }
326:
327: /** Returns a collection of Criteria objects, indicating the joins to be performed.
328: * @return A collection of Criteria objects.
329: */
330: public Collection getAggregates() {
331: return m_aggregates;
332: }
333:
334: /** Returns a collection of criteria entries to signify the join conditions.
335: * @return A collection of Criteria.CriteriaEntry objects.
336: */
337: public Collection getInners() {
338: return m_innerCriteriaEntries;
339: }
340:
341: /** Returns a collection of order by elements.
342: * @return A collection of Criteria.OrderBy objects.
343: */
344: public Collection getOrderBys() {
345: return m_orderBy;
346: }
347:
348: /** This class is used by the Criteria for each order by element.
349: */
350: public class OrderBy implements Serializable {
351: private String m_orderByElement = null;
352: private int m_ordering = ORDER_BY_ASC;
353:
354: private OrderBy(String orderByElement, int ordering) {
355: m_orderByElement = orderByElement;
356: m_ordering = ordering;
357: }
358:
359: /** Returns the name of the field.
360: * @return the name of the field.
361: */
362: public String getOrderByElement() {
363: return m_orderByElement;
364: }
365:
366: /** Returns the type of ordering.
367: * @return either Ascending or Descending.
368: */
369: public int getOrdering() {
370: return m_ordering;
371: }
372: }
373:
374: /** This class is used by the Criteria for each criteria entry.
375: */
376: public class CriteriaEntry implements Serializable {
377: /** A static indicating the criteria entry is to be AND-ed */
378: public final static int LOGICAL_AND = 0x01;
379:
380: /** A static indicating the criteria entry is to be OR-ed */
381: public final static int LOGICAL_OR = 0x02;
382:
383: private String m_name = null;
384: private Object m_value = null;
385: private int m_operator;
386: private int m_logic;
387: private boolean m_dual = false;
388:
389: private CriteriaEntry(String name, Object value) {
390: this (name, RELATIONAL_EQUALS, value, false);
391: }
392:
393: private CriteriaEntry(String name, int operator, Object value) {
394: this (name, operator, value, false);
395: }
396:
397: private CriteriaEntry(String name, int operator) {
398: this (name, operator, null, false);
399: }
400:
401: private CriteriaEntry(String name, Object value, boolean dual) {
402: this (name, RELATIONAL_EQUALS, value, dual);
403: }
404:
405: private CriteriaEntry(String name, int operator, Object value,
406: boolean dual) {
407: m_name = name;
408: m_operator = operator;
409: m_value = value;
410: m_dual = dual;
411: m_logic = LOGICAL_AND;
412: }
413:
414: CriteriaEntry() {
415: }
416:
417: void setLogic(int logic) {
418: m_logic = logic;
419: }
420:
421: /** Returns an int indicating AND or OR condition.
422: * @return an int indicating AND or OR condition.
423: */
424: public int getLogic() {
425: return m_logic;
426: }
427:
428: /** A true is returned, if this criteria entry will be AND-ed.
429: * @return a true is returned, if this criteria entry will be AND-ed.
430: */
431: public boolean isLogicAND() {
432: return m_logic == LOGICAL_AND ? true : false;
433: }
434:
435: /** Returns the name of the field.
436: * @return the name of the field.
437: */
438: public String getName() {
439: return m_name;
440: }
441:
442: /** Returns the value to be assigned to the field. For a dual criteria entry, the name of the second field is returned.
443: * @return the value to be assigned to the field. For a dual criteria entry, the name of the second field is returned.
444: */
445: public Object getValue() {
446: return m_value;
447: }
448:
449: /** Returns the operator to be used in the assignment.
450: * @return the operator to be used in the assignment.
451: */
452: public int getOperator() {
453: return m_operator;
454: }
455:
456: /** A true is returned for a dual criteria entry.
457: * @return true for a dual criteria entry.
458: */
459: public boolean getDual() {
460: return m_dual;
461: }
462: }
463:
464: /** The class is used by the Criteria to add an AtomicCriteria object to its collection of criteria entries.
465: */
466: public class AtomicCriteriaEntry extends CriteriaEntry {
467: private AtomicCriteria m_atomic;
468:
469: private AtomicCriteriaEntry(AtomicCriteria atomic) {
470: m_atomic = atomic;
471: }
472:
473: /** Returns the AtomicCriteria object encapsulated by this criteria entry.
474: * @return the AtomicCriteria object encapsulated by this criteria entry.
475: */
476: public AtomicCriteria getEntry() {
477: return m_atomic;
478: }
479: }
480: }
|