001: /*
002: * Copyright 2001-2007 Geert Bevin <gbevin[remove] at uwyn dot com> and
003: * JR Boyens <gnu-jrb[remove] at gmx dot net>
004: * Distributed under the terms of either:
005: * - the common development and distribution license (CDDL), v1.0; or
006: * - the GNU Lesser General Public License, v2.1 or later
007: * $Id: GenericQueryManager.java 3634 2007-01-08 21:42:24Z gbevin $
008: */
009: package com.uwyn.rife.database.querymanagers.generic;
010:
011: import com.uwyn.rife.database.DbRowProcessor;
012: import com.uwyn.rife.database.exceptions.DatabaseException;
013: import com.uwyn.rife.database.queries.CreateTable;
014: import com.uwyn.rife.site.ValidationContext;
015: import java.util.List;
016:
017: /**
018: * A <code>GenericQueryManager</code> provides features that make it easy to
019: * persist and retrieve beans in a database with single method calls. An
020: * instance of the manager can by obtained by using the {@link
021: * GenericQueryManagerFactory} class.
022: * <p>Callbacks are also supported to make it possible to interact with the
023: * persistence actions in a bean-centric way. More information can be found in
024: * the {@link Callbacks} interface.
025: *
026: * @author Geert Bevin (gbevin[remove] at uwyn dot com)
027: * @version $Revision: 3634 $
028: * @see
029: * com.uwyn.rife.database.querymanagers.generic.GenericQueryManagerFactory
030: * @see com.uwyn.rife.database.querymanagers.generic.Callbacks
031: * @since 1.0
032: */
033: public interface GenericQueryManager<BeanType> extends
034: ValidationContext {
035: /**
036: * Get the handled class
037: *
038: * @return the handled class
039: * @since 1.0
040: */
041: Class getBaseClass();
042:
043: /**
044: * Get the managed database table name
045: *
046: * @return the table name
047: * @since 1.0
048: */
049: String getTable();
050:
051: /**
052: * Get the name of the property defined as the identifier.
053: * <p>Defaults to "id".
054: *
055: * @return the name of the property defined as the identifier
056: * @since 1.0
057: */
058: String getIdentifierName();
059:
060: /**
061: * Get the value of the property defined as the identifier.
062: * <p>The property defaults to "id".
063: *
064: * @param bean the bean to retrieve the identifier value for
065: * @return the value of the property defined as the identifier
066: * @since 1.0
067: */
068: int getIdentifierValue(BeanType bean) throws DatabaseException;
069:
070: /**
071: * Install the database structure into the database.
072: * <p>This method will cause the structure needed to persist the bean to
073: * be installed into the database. This includes any validatity checks
074: * that the database supports and that have already been defined.
075: * Including (but not limited to): length, notNull, notEmpty, etc. etc.
076: * This method will fail semi-gracefully if the installation fails.
077: * Generally it's best to catch the {@link DatabaseException} and assume
078: * that the database is already installed.
079: *
080: * @see #remove()
081: * @since 1.0
082: */
083: void install() throws DatabaseException;
084:
085: /**
086: * Install the database structure into the database using a custom query.
087: * <p>This method will cause the structure needed to persist the bean to
088: * be installed into the database using the provided custom query. The
089: * custom query is usually obtained by using {@link
090: * #getInstallTableQuery()}. This includes any validatity checks that the
091: * database supports and that have already been defined. Including (but
092: * not limited to): length, notNull, notEmpty, etc. etc. This method will
093: * fail semi-gracefully if the installation fails. Generally it's best to
094: * catch the {@link DatabaseException} and assume that the database is
095: * already installed.
096: *
097: * @param query the {@link CreateTable} query to use to create the table
098: * @see #install()
099: * @see #remove()
100: * @since 1.0
101: */
102: void install(CreateTable query) throws DatabaseException;
103:
104: /**
105: * Remove the database structure
106: * <p>This method will cause the database structure to be removed from the
107: * database deleting all saved beans in the process. No new beans of this
108: * type can be persisted until the database structure is reinstalled.
109: *
110: * @see #install()
111: * @since 1.0
112: */
113: void remove() throws DatabaseException;
114:
115: /**
116: * Persist a bean.
117: * <p>This method allows a person to persist a bean to a DB to be later
118: * restored. A bean to be persisted must have at least one integer
119: * identifier and one bean property both with accessors. If the identifier
120: * value is greater than or equal to 0, the bean is attempted to be
121: * updated first, if this fails (or the identifier is -1) the bean is
122: * assumed to be a new bean and a new sequential identifier is generated
123: * by the database.
124: *
125: * @param bean the bean to be saved
126: * @return the identifier assigned to the new/updated bean
127: * @since 1.0
128: */
129: int save(BeanType bean) throws DatabaseException;
130:
131: /**
132: * Insert a bean in the database.
133: * <p>This method specifically forces insertion of the bean into the
134: * database. This method is only recommended for use when you know what
135: * you are doing. The {@link #save(Object bean)} method is safer because
136: * it can detect whether to insert or update the bean in that database,
137: * leading to safer, simpler code. Bean restrictions mirror {@link
138: * #save(Object bean)}.
139: *
140: * @param bean the bean to be inserted
141: * @return the indentier assigned to the new bean
142: * @see #save(Object bean)
143: * @since 1.0
144: */
145: int insert(BeanType bean) throws DatabaseException;
146:
147: /**
148: * Update an existing bean in the database.
149: * <p>This method specifically forces the updating of the bean into the
150: * database. This method is only recommended for use when you know what
151: * you are doing. The {@link #save(Object bean)} method is safer because
152: * it can detect whether to insert or update the bean in that database,
153: * leading to safer, simpler code. Bean restrictions mirror {@link
154: * #save(Object bean)}.
155: *
156: * @param bean the bean to be updated
157: * @return the indentier assigned to the new bean
158: * @see #save(Object bean)
159: * @since 1.0
160: */
161: int update(BeanType bean) throws DatabaseException;
162:
163: /**
164: * Restore all the beans persisted under this manager.
165: * <p>This method will return a {@link List} of all the beans persisted
166: * under this manager.
167: *
168: * @return a {@link List} of all the persisted beans
169: * @since 1.0
170: */
171: List<BeanType> restore() throws DatabaseException;
172:
173: /**
174: * Restore a single bean using the identifier.
175: * <p>This method will return a single bean having the provided
176: * identifier. Since the identifier is unique, you can be assured of a
177: * single bean with a persistent id. This id is never changed under normal
178: * circumstances.
179: *
180: * @param objectId the identifier to identify the bean to restore
181: * @return the bean that matches the identifier provided
182: * @since 1.0
183: */
184: BeanType restore(int objectId) throws DatabaseException;
185:
186: /**
187: * Restore all beans using the row processor provided.
188: * <p>This method will return all beans using a {@link DbRowProcessor} for
189: * reduced memory requirements as opposed to the full {@link List} version
190: * of {@link #restore()}.
191: *
192: * @param rowProcessor the DbRowProcessor each row should be passed to
193: * @return true if beans were restored, false if not
194: * @see #restore()
195: * @since 1.0
196: */
197: boolean restore(DbRowProcessor rowProcessor)
198: throws DatabaseException;
199:
200: /**
201: * Restore the first bean that matches the {@link RestoreQuery}.
202: * <p>This method will return the first bean that matches the {@link
203: * RestoreQuery}. Especially useful for selecting the first returned bean
204: * from a complex query.
205: *
206: * @param query the query the bean should be restored from
207: * @return the first bean that matches the {@link RestoreQuery}
208: * @see #restore(RestoreQuery)
209: * @since 1.0
210: */
211: BeanType restoreFirst(RestoreQuery query) throws DatabaseException;
212:
213: /**
214: * Restore a list of beans that match the provided {@link RestoreQuery}.
215: * <p>This method will return a list of beans that match the provided
216: * {@link RestoreQuery}. This can be used for more complex queries, or for
217: * exclusion of certain beans from the results.
218: *
219: * @param query the query the beans should be restored from
220: * @return a list containing all the restored beans
221: * @see #restore()
222: * @since 1.0
223: */
224: List<BeanType> restore(RestoreQuery query) throws DatabaseException;
225:
226: /**
227: * Restore a list of beans that match the provided {@link RestoreQuery}
228: * and process with the {@link DbRowProcessor}.
229: * <p>This method will return a list of beans that match the provided
230: * RestoreQuery and process these matches with the provided {@link
231: * DbRowProcessor}. This can be used for more memory-intensive (or larger
232: * result sets) complex queries or for the exclusion of certain beans from
233: * the results.
234: *
235: * @param query the query the beans should be restored from
236: * @param rowProcessor the row processor that should be used to process
237: * each matched bean row
238: * @return true if beans were processed, false if not
239: * @since 1.0
240: */
241: boolean restore(RestoreQuery query, DbRowProcessor rowProcessor)
242: throws DatabaseException;
243:
244: /**
245: * Get the query that would be used to install the table.
246: * <p>This method will return the query that would be used to install the
247: * database structure. Can be used to modify the structure if i custom
248: * structure is needed. Mostly likely to be passed into {@link
249: * #install(CreateTable)}
250: *
251: * @return the query that would be used to install the database structure
252: * @since 1.0
253: */
254: CreateTable getInstallTableQuery() throws DatabaseException;
255:
256: /**
257: * Get the base query used to restore beans.
258: * <p>This method will return the base query that would be used to restore
259: * beans with {@link #restore()}. This can be used to restrict the query
260: * so that less beans are returned or certain beans are returned.
261: *
262: * @return the query that would be used to restore a number of beans
263: * @since 1.0
264: */
265: RestoreQuery getRestoreQuery();
266:
267: /**
268: * Get the base query used to restore a single identifed bean.
269: * <p>This method will return the base query that would be used to restore
270: * a single bean with {@link #restore(int)}. This can be used to restrict
271: * the query so that a bean not matching the query will not be returned.
272: *
273: * @return the query that would be used to restore a single identified
274: * bean
275: * @since 1.0
276: */
277: RestoreQuery getRestoreQuery(int objectId);
278:
279: /**
280: * Count the number of beans persisted.
281: * <p>This method will count the total number of beans persisted under
282: * this manager.
283: *
284: * @since 1.0
285: * @return the number of beans persisted under this manager
286: * @since 1.0
287: */
288: int count() throws DatabaseException;
289:
290: /**
291: * Count the number of beans persisted with a custom {@link CountQuery}.
292: * <p>This method will count the total number of beans persisted under
293: * this manager that match the provided {@link CountQuery}.
294: *
295: * @param query the query that will be used to determine which beans to
296: * count
297: * @return the number of beans persisted under this manager that match the
298: * provided query
299: * @since 1.0
300: */
301: int count(CountQuery query) throws DatabaseException;
302:
303: /**
304: * Get the base {@link CountQuery} used to count the number of beans
305: * persisted under this manager
306: *
307: * @return the query that would be used to count the total number of beans
308: * persisted under this managerù
309: * @since 1.0
310: */
311: CountQuery getCountQuery();
312:
313: /**
314: * Delete a single identified bean
315: * <p>This method will delete the bean identifed by the passed in
316: * identifier.
317: *
318: * @param objectId the identifier of the bean
319: * @return true if the deletion suceeded, false if it did not
320: * @since 1.0
321: */
322: boolean delete(int objectId) throws DatabaseException;
323:
324: /**
325: * Delete beans selected by the passed in {@link DeleteQuery}
326: * <p>This method will delete all beans identified by the passed in {@link
327: * DeleteQuery}.
328: *
329: * @param query the query to select the beans
330: * @return true if the deletion suceeded, false if it did not
331: * @since 1.0
332: */
333: boolean delete(DeleteQuery query) throws DatabaseException;
334:
335: /**
336: * Return the base {@link DeleteQuery} that would be used to delete beans
337: *
338: * @return the base {@link DeleteQuery}
339: * @since 1.0
340: */
341: DeleteQuery getDeleteQuery();
342:
343: /**
344: * Return the base {@link DeleteQuery} that would be used to delete a
345: * single bean
346: *
347: * @param objectId the identifier to fill into the base {@link DeleteQuery}
348: * @return the base {@link DeleteQuery}
349: * @since 1.0
350: */
351: DeleteQuery getDeleteQuery(int objectId);
352:
353: /**
354: * Add the listener to the manager to get notifications when actions
355: * were successful.
356: *
357: * @param listener the listener that has to be added
358: * @since 1.5
359: */
360: void addListener(GenericQueryManagerListener listener);
361:
362: /**
363: * Remove all the listeners that are registered to the manager.
364: *
365: * @since 1.5
366: */
367: void removeListeners();
368:
369: /**
370: * Create a new generic query manager of the same kind but for another
371: * bean class.
372: *
373: * @param beanClass the class of the bean for which the new generic query
374: * manager has to be created
375: * @return a new generic query manager instance
376: * @since 1.6
377: */
378: <OtherBeanType> GenericQueryManager<OtherBeanType> createNewManager(
379: Class<OtherBeanType> beanClass);
380: }
|