1 /*
2 * EL4J, the Extension Library for the J2EE, adds incremental enhancements to
3 * the spring framework, http://el4j.sf.net
4 * Copyright (C) 2005 by ELCA Informatique SA, Av. de la Harpe 22-24,
5 * 1000 Lausanne, Switzerland, http://www.elca.ch
6 *
7 * EL4J is published under the GNU Lesser General Public License (LGPL)
8 * Version 2.1. See http://www.gnu.org/licenses/
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU Lesser General Public License for more details.
14 *
15 * For alternative licensing, please contact info@elca.ch
16 */
17 package ch.elca.el4j.services.search;
18
19 import java.io.Serializable;
20 import java.util.ArrayList;
21 import java.util.List;
22
23 import ch.elca.el4j.services.persistence.generic.dao.GenericDao;
24 import ch.elca.el4j.services.search.criterias.AndCriteria;
25 import ch.elca.el4j.services.search.criterias.Criteria;
26 import ch.elca.el4j.services.search.criterias.CriteriaHelper;
27 import ch.elca.el4j.services.search.criterias.Order;
28 import ch.elca.el4j.util.codingsupport.Reject;
29
30 /**
31 * Object to holds criterias to execute queries. A query object can be specified
32 * for exactly one class. A query object is an AND-joined set of Criteria
33 * objects. <a>
34 *
35 * Features: <br>
36 * <ul>
37 * <li> OR-criterias, NOT-criterias, AND-criterias refer to
38 * {@link CriteriaHelper} for some convenience support.
39 * <li> paging support (see methods {@link setFirstResult}
40 * {@link setMaxResults} and {@link setDefaultMaxResults}
41 * <li> ordering support (often required when doing paging)
42 * </ul>
43 *
44 * Example on how to use this (with paging, ordering and criteria): <br> <br>
45 *
46 * <code>
47 * <pre>
48 * // code fragments taken from HibernateKeywordDaoTest
49 *
50 * query = new QueryObject();
51 *
52 * // criteria is deliberately a bit noisy
53 * query.addCriteria(
54 * or(and(not(new ComparisonCriteria("name","Ghost","!=","String")),
55 * (or(not(like("name", "%host%")),
56 * like("name", "%host%"))))));
57 *
58 * query.addOrder(Order.desc("name"));
59 * query.setMaxResults(2);
60 * query.setFirstResult(4);
61 *
62 * // dao is typically a generic dao implementation
63 * list = dao.findByQuery(query);
64 * </pre>
65 * </code>
66 * <a>
67 * Sample uses in EL4J: {@link GenericDao}, {@link CriteriaTransformer} <br> <br>
68 *
69 * @svnLink $Revision: 3883 $;$Date: 2009-08-04 15:35:01 +0200 (Di, 04. Aug 2009) $;$Author: swismer $;$URL: https://el4j.svn.sourceforge.net/svnroot/el4j/branches/el4j_3_1/el4j/framework/modules/core/src/main/java/ch/elca/el4j/services/search/QueryObject.java $
70 *
71 * @author Martin Zeltner (MZE)
72 * @author Philipp Oser (POS)
73 */
74 public class QueryObject implements Serializable {
75 /**
76 * The bean class the query object is for.
77 */
78 private Class<?> m_beanClass;
79
80 /**
81 * The criterias for this query. (They are logically connected with
82 * AND).
83 */
84 private AndCriteria m_criterias = new AndCriteria();
85
86 /**
87 * Specifies a general query object.
88 */
89 public QueryObject() {
90 this(null);
91 }
92
93 /**
94 * Specifies the query object for a specific class.
95 *
96 * @param beanClass Is the bean class this query object is made for.
97 */
98 public QueryObject(Class<?> beanClass) {
99 m_beanClass = beanClass;
100 }
101
102 /**
103 * @return Returns the bean class this query object is made for.
104 */
105 public Class<?> getBeanClass() {
106 return m_beanClass;
107 }
108
109 /**
110 * Adds the given criteria. The criterias are combined via
111 * "AND" (it's a logical conjunction of Criterias).
112 * This method can be used with one or n Criteria(s).
113 *
114 * @param criteria Is the criteria to add.
115 */
116 public void addCriteria(Criteria... criteria) {
117 Reject.ifNull(criteria);
118 if (criteria != null) {
119 for (Criteria c : criteria) {
120 m_criterias.add(c);
121 }
122 }
123 }
124
125 /**
126 * Adds the given criterias.
127 *
128 * @param criterias Are the criterias to add. The criterias are combined via
129 * "AND" (it's a logical conjunction of Criterias).
130 * @deprecated please use the more versatile {@link addCriteria} method
131 */
132 public void addCriterias(Criteria... criterias) {
133 Reject.ifNull(criterias);
134 for (int i = 0; i < criterias.length; i++) {
135 Criteria criteria = criterias[i];
136 m_criterias.add(criteria);
137 }
138 }
139
140 /**
141 * @return Returns a list of criterias (all criterias must be valid
142 * for this query object (they are combined with AND)).
143 */
144 public List<Criteria> getCriteriaList() {
145 return m_criterias.getCriterias();
146 }
147
148 /**
149 * @return Returns an array of criterias. (all criterias must be true
150 * for this query (they are combined with AND)).
151 */
152 public Criteria[] getCriterias() {
153 List<Criteria> crits = getCriteriaList();
154 return crits.toArray(new Criteria[0]);
155 }
156
157 /**
158 * {@inheritDoc}
159 */
160 @Override
161 public String toString(){
162 return "QueryObject [Type: "+getBeanClass()+
163 " Query: "+m_criterias.getSqlWhereCondition()+"]";
164 }
165
166 public AndCriteria getAndCriterias () {
167 return m_criterias;
168 }
169
170 ///////// paging support ////////////////////
171
172 /**
173 * Constant (=-1) to use for property firstResult.
174 * NO_CONSTRAINT means we do not constrain anything
175 */
176 public static final int NO_CONSTRAINT = -1;
177
178 /**
179 * Default can be updated via static setter
180 * {@link setDefaultMaxResults}
181 */
182 static int s_defaultMaxResults = 100;
183
184 protected int m_firstResult;
185
186
187 /**
188 * Default value is s_defaultMaxResults
189 */
190 protected int m_maxResults = s_defaultMaxResults;
191
192 List<Order> m_orderConstraints = new ArrayList<Order>();
193
194 /**
195 * What is the id of the first result we want to get back?
196 * By default there is no constraint on the first result.
197 * The counting starts at 0 (i.e. the first result is 0)!
198 * @param firstResult
199 */
200 public void setFirstResult(int firstResult) {
201 m_firstResult = firstResult;
202 }
203
204 /**
205 * How many results do we want to get back at most?
206 * (The default can be set via the {@link setDefaultMaxResults}
207 * method). It defaults to 100. -1 means there is no constraint.
208 * @param maxResults
209 */
210 public void setMaxResults(int maxResults) {
211 m_maxResults = maxResults;
212 }
213
214 /**
215 * @see setFirstResult
216 * @return
217 */
218 public int getFirstResult() {
219 return m_firstResult;
220 }
221
222 /**
223 * @see setMaxResults
224 * @return
225 */
226 public int getMaxResults() {
227 return m_maxResults;
228 }
229
230 /**
231 * @see setDefaultMaxResults
232 * @return
233 */
234 public static int getDefaultMaxResults() {
235 return s_defaultMaxResults;
236 }
237
238 /**
239 * How many results shall we return by default?
240 * Defaults to 100. -1 stands for no constraint.
241 * @param defaultMaxResults
242 */
243 public static void setDefaultMaxResults(int defaultMaxResults) {
244 s_defaultMaxResults = defaultMaxResults;
245 }
246
247 /**
248 * Add an ordering constraint (particularly useful
249 * when doing paging) <br> <br>
250 * Example usage: <br>
251 * <code> query.addOrder(Order.desc("name")); </code>
252 * @param order
253 */
254 public void addOrder(Order order){
255 m_orderConstraints.add(order);
256 }
257
258 /**
259 * Get the list of all defined ordering constraints.
260 * @return
261 */
262 public List<Order> getOrderConstraints() {
263 return m_orderConstraints;
264 }
265
266 }