1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package org.acegisecurity.domain.dao;
17
18 import org.acegisecurity.domain.PersistableEntity;
19
20 import java.io.Serializable;
21
22 import java.util.Collection;
23 import java.util.List;
24
25 /***
26 * Provides fundamental DAO capabilities for a single concrete {@link
27 * PersistableEntity}, using JDK 1.5 generics.
28 *
29 * <P>
30 * This interface provides a portable approach to Data Access Object (DAO)
31 * functionality across various object relational persistance solutions.
32 * </p>
33 *
34 * <p>
35 * It is not envisioned that this interface will provide <b>all</b> data access
36 * requirements for applications, however it should provide all of the
37 * standard create, read, update, delete (CRUD) and finder functions that are
38 * routinely needed. Specialized subclasses (that provide finer-grained
39 * functionality) of the <code>Dao</code> interface are encouraged.
40 * </p>
41 *
42 * <P>
43 * A <code>Dao</code> implementation (or a subclass of <code>Dao</code>) should
44 * be the sole entry point into the persistance layer of an application. The
45 * persistence layer should only respond to requests from the services layer.
46 * The services layer is where all transaction demarcation, security
47 * authorization, casting to and from concrete {@link
48 * org.acegisecurity.domain.PersistableEntity}s, workflow and business
49 * logic should take place.
50 * </p>
51 *
52 * <p>
53 * Each <code>Dao</code> implementation will support one
54 * <code>PersistableEntity</code> classes only. The supported
55 * <code>PersistableEntity</code> class must be indicated via the {@link
56 * #supports(Class)} method.
57 * </p>
58 *
59 * @author Ben Alex
60 * @version $Id: Dao.java,v 1.7 2005/11/17 00:55:47 benalex Exp $
61 */
62 public interface Dao<E extends PersistableEntity> {
63
64
65 /***
66 * Create a new object, with the current {@link
67 * PersistableEntity#getInternalId()} value being ignored.
68 *
69 * @param value (without the identity property initialized)
70 *
71 * @return the value created (with the identity property initialised)
72 */
73 public E create(E value);
74
75 /***
76 * Delete an object.
77 *
78 * @param value the value to delete
79 */
80 public void delete(E value);
81
82 /***
83 * Return all persistent instances, including subclasses.
84 *
85 * @return all persistence instances (an empty <code>List</code> will be
86 * returned if no matches are found)
87 */
88 public List<E> findAll();
89
90 /***
91 * Find a <code>List</code> of <code>PersistableEntity</code>s, searched by
92 * their identifiers.
93 *
94 * @param ids collection of identifiers to locate
95 *
96 * @return the values with those identifiers (an empty <code>List</code>
97 * will be returned if no matches are found)
98 */
99 public List<E> findId(Collection<Serializable> ids);
100
101 /***
102 * Load a persistent instance by its identifier, although some properties
103 * may be lazy loaded depending on the underlying DAO implementation and/or
104 * persistence engine mapping document.
105 *
106 * @param id the identifier of the persistent instance desired to be
107 * retrieved
108 *
109 * @return the request item, or <code>null</code> if not found
110 */
111 public E readId(Serializable id);
112
113 /***
114 * Loads a persistent instance by its identifier, along with any
115 * lazy loaded properties associated with that instance.
116 *
117 * @param id the identifier of the persistent instance desired to be
118 * retrieved
119 *
120 * @return the request item, or <code>null</code> if not found
121 */
122 public E readPopulatedId(Serializable id);
123
124 /***
125 * Find persistent instances with properties matching those of the passed
126 * <code>PersistableEntity</code>.
127 *
128 * <P>
129 * Persistent instances are matched on the basis of query by example.
130 * Properties whose value is <code>null</code>, empty
131 * <code>String</code>s, and any <code>Collection</code>s are ignored in
132 * the query by example evaluation.
133 * </p>
134 *
135 * @param value parameters to filter on (the class of this object will
136 * be added to the filter)
137 * @param firstElement the first result (start at zero to obtain all
138 * results)
139 * @param maxElements the maximum number of results desired for this page
140 * of the result set
141 * @param orderByAsc the property name of the
142 * <code>PersistableEntity</code> that should be used to order the
143 * results
144 *
145 * @return the requested page of the result list (a properly formed
146 * <code>PaginatedList</code> is returned if no results match)
147 */
148 public PaginatedList<E> scroll(E value, int firstElement,
149 int maxElements, String orderByAsc);
150
151 /***
152 * Find persistent instances with properties matching those of the passed
153 * <code>PersistableEntity</code>, with a guarantee the returned results
154 * will have each of the <code>value</code> class' immediate properties
155 * initialized.
156 *
157 * <P>
158 * Persistent instances are matched on the basis of query by example.
159 * Properties whose value is <code>null</code>, empty
160 * <code>String</code>s, and any <code>Collection</code>s are ignored in
161 * the query by example evaluation.
162 * </p>
163 *
164 * @param value parameters to filter on (the class of this object will
165 * be added to the filter)
166 * @param firstElement the first result (start at zero to obtain all
167 * results)
168 * @param maxElements the maximum number of results desired for this page
169 * of the result set
170 * @param orderByAsc the property name of the
171 * <code>PersistableEntity</code> that should be used to order the
172 * results
173 *
174 * @return the requested page of the result list (a properly formed
175 * <code>PaginatedList</code> is returned if no results match)
176 */
177 public PaginatedList<E> scrollPopulated(E value, int firstElement,
178 int maxElements, String orderByAsc);
179
180 /***
181 * Find persistent instances with properties matching those of the passed
182 * <code>PersistableEntity</code>, ignoring the class of the passed
183 * <code>PersistableEntity</code> (useful if you pass a superclass, as you
184 * want to find all subclass instances which match).
185 *
186 * @param value parameters to filter on (the class of this object will
187 * NOT be added to the filter)
188 * @param firstElement the first result (start at zero to obtain all
189 * results)
190 * @param maxElements the maximum number of results desired for this page
191 * of the result set
192 * @param orderByAsc the property name of the
193 * <code>PersistableEntity</code> that should be used to order the
194 * results
195 *
196 * @return the requested page of the result list (a properly formed
197 * <code>PaginatedList</code> is returned if no results match)
198 */
199 public PaginatedList<E> scrollWithSubclasses(E value, int firstElement,
200 int maxElements, String orderByAsc);
201
202 /***
203 * Find persistent instances with properties matching those of the passed
204 * <code>PersistableEntity</code>, ignoring the class of the passed
205 * <code>PersistableEntity</code> (useful if you pass a superclass, as you
206 * want to find all subclass instances which match). Guarantees the returned
207 * results will have each of the DAO's <code>supports</code> class' immediate
208 * properties initialized.
209 *
210 * @param value parameters to filter on (the class of this object will
211 * NOT be added to the filter)
212 * @param firstElement the first result (start at zero to obtain all
213 * results)
214 * @param maxElements the maximum number of results desired for this page
215 * of the result set
216 * @param orderByAsc the property name of the
217 * <code>PersistableEntity</code> that should be used to order the
218 * results
219 *
220 * @return the requested page of the result list (a properly formed
221 * <code>PaginatedList</code> is returned if no results match)
222 */
223 public PaginatedList<E> scrollPopulatedWithSubclasses(E value, int firstElement,
224 int maxElements, String orderByAsc);
225
226 /***
227 * Indicates whether the DAO instance provides persistence services for the
228 * specified class.
229 *
230 * @param clazz to test, which should be an implementation of
231 * <code>PersistableEntity</code>
232 *
233 * @return <code>true</code> or <code>false</code>, indicating whether or
234 * not the passed class is supported by this DAO instance
235 */
236 public boolean supports(Class clazz);
237
238 /***
239 * Update an object.
240 *
241 * @param value to update, with the <code>PersistableEntity</code> having a
242 * non-<code>null</code> identifier
243 *
244 * @return the updated value
245 */
246 public E update(E value);
247 }