1 /*
2 * EL4J, the Extension Library for the J2EE, adds incremental enhancements to
3 * the spring framework, http://el4j.sf.net
4 * Copyright (C) 2006 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.persistence.generic.dao;
18
19 import java.util.Collection;
20 import java.util.List;
21
22 import org.springframework.dao.DataAccessException;
23 import org.springframework.dao.DataIntegrityViolationException;
24 import org.springframework.dao.DataRetrievalFailureException;
25 import org.springframework.dao.OptimisticLockingFailureException;
26
27 import ch.elca.el4j.services.persistence.generic.dao.annotations.ReturnsUnchangedParameter;
28 import ch.elca.el4j.services.search.QueryObject;
29
30 /**
31 *
32 * Interface for generic DAOs. It is the interface that implements
33 * the DDD-Book's (http://www.domaindrivendesign.org/) Repository pattern.
34 * This interface is implemented generically and it can be extended in case
35 * you need more specific methods. Based on an idea from the Hibernate website.
36 *
37 * This is the canonical form of this interface. We recommend it when a generic
38 * DAO is used in tools (to make the contract minimal).
39 * For direct programmer-usage we recommend to use the convenience subclasses
40 * (@link ConvenienceGenericDao).
41 *
42 * @svnLink $Revision: 3902 $;$Date: 2009-08-17 14:34:48 +0200 (Mo, 17. 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/persistence/generic/dao/GenericDao.java $
43 *
44 * @param <T>
45 * The generic type of the domain class the DAO is responsible for
46 *
47 * @author Philipp Oser (POS)
48 * @author Alex Mathey (AMA)
49 * @author Adrian Moos (AMS)
50 * @author Martin Zeltner (MZE)
51 */
52 public interface GenericDao<T> {
53 /**
54 * Needed because the Java generics throw away this type
55 * information.
56 * @return Returns the domain class this DAO is responsible for.
57 */
58 public Class<T> getPersistentClass();
59
60 /**
61 * New: this callback is in general no longer required (the constructor
62 * should figure the type out itself).
63 *
64 * @param c Mandatory. The domain class this DAO is responsible for.
65 */
66 public void setPersistentClass(Class<T> c);
67
68 /**
69 * Executes a query based on a given query object.
70 * This method may also support paging (see javadoc
71 * of implementing class).
72 *
73 * @param q The search query object
74 * @throws DataAccessException
75 * If general data access problem occurred
76 * @return A list containing 0 or more domain objects
77 */
78 List<T> findByQuery(QueryObject q) throws DataAccessException;
79
80
81 /**
82 * Count number of results of a search.
83 *
84 * @param query The search query object
85 * @return the number of results that this query could at most
86 * return.
87 * @throws DataAccessException
88 */
89 int findCountByQuery(final QueryObject query) throws DataAccessException;
90
91
92 /**
93 * Re-reads the state of the given domain object from the underlying
94 * store.
95 *
96 * @param entity
97 * The domain object to re-read the state of
98 * @throws DataAccessException
99 * If general data access problem occurred
100 * @throws DataRetrievalFailureException
101 * If domain object could not be re-read
102 * @return The refreshed entity
103 */
104 T refresh(T entity) throws DataAccessException,
105 DataRetrievalFailureException;
106
107 /**
108 * Re-reads the state of the given domain object from the undermost
109 * store (eg. the database).
110 *
111 * @param entity
112 * The domain object to re-load the state of
113 * @throws DataAccessException
114 * If general data access problem occurred
115 * @throws DataRetrievalFailureException
116 * If domain object could not be re-loaded
117 * @return The reloaded entity
118 */
119 T reload(T entity) throws DataAccessException,
120 DataRetrievalFailureException;
121
122 /**
123 * Saves or updates the given domain object.
124 *
125 * @param entity
126 * The domain object to save or update
127 * @throws DataAccessException
128 * If general data access problem occurred
129 * @throws DataIntegrityViolationException
130 * If domain object could not be inserted due to a data
131 * integrity violation
132 * @throws OptimisticLockingFailureException
133 * If domain object has been modified/deleted in the meantime
134 * @return The saved or updated domain object
135 */
136 @ReturnsUnchangedParameter
137 T saveOrUpdate(T entity) throws DataAccessException,
138 DataIntegrityViolationException, OptimisticLockingFailureException;
139
140 /**
141 * Deletes the given domain objects. This method executed in a single
142 * transaction (by default with the Required semantics).
143 *
144 * @param entities
145 * The domain objects to delete.
146 * @throws DataAccessException
147 * If general data access problem occurred
148 * @throws OptimisticLockingFailureException
149 * If domain object has been modified/deleted in the meantime
150 */
151 void delete(Collection<T> entities)
152 throws OptimisticLockingFailureException, DataAccessException;
153 }