1 /***
2 * License Agreement.
3 *
4 * JSPA (POJO-SP)
5 *
6 * Copyright (C) 2009 HRX Pty Ltd
7 *
8 * This file is part of JSPA.
9 *
10 * JSPA is free software: you can redistribute it and/or modify it under the
11 * terms of the GNU Lesser General Public License version 3 as published by the
12 * Free Software Foundation.
13 *
14 * JSPA is distributed in the hope that it will be useful, but WITHOUT ANY
15 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
16 * A PARTICULAR PURPOSE. See the Lesser General Public License for more details.
17 *
18 * You should have received a copy of the GNU Lesser General Public License
19 * along with JSPA. If not, see <http://www.gnu.org/licenses/>.
20 */
21 package com.hrx.rasp.util.dao;
22
23 import java.sql.SQLException;
24 import java.util.List;
25
26 import com.hrx.rasp.util.dao.exception.InvalidStoredProcedureException;
27 import com.hrx.rasp.util.dao.exception.OperationNotSupportedException;
28 import com.hrx.rasp.util.dao.exception.RecordNotFoundException;
29 import com.hrx.rasp.util.dao.exception.StoredProcedureException;
30 import com.hrx.rasp.util.dao.exception.StoredProcedurePrepareException;
31 import com.hrx.rasp.util.dao.exception.StoredProcedureProccessResultException;
32
33 /***
34 *
35 * The DAOManager is used to create, remove and update persistent DAO instances.
36 * Also it can be used to find entities by their primary key, and to query over
37 * the records stored in the database. It is responsible to manage the DAO life
38 * cycle calling the SQL operations for their instances. The DAO manager defines
39 * and implements the methods that are used to interact with the stored DAO.
40 * Removed and find operations require the primary key of the DAO to be set. Any
41 * other properties except the primary key will be ignored and they should not
42 * be used by Remove or find Stored Procedures.
43 *
44 * The DAO is expected to have public setters and getters for all OUT or INOUT
45 * parameters and public getters for all methods IN parameters.
46 *
47 * The OUT and INOUT parameters can not be final.
48 *
49 * The first two parameters of the database Stored Procedures executing the DAO
50 * operations (CREATE, DELETE, UPDATE, FIND, SELECT) are reserved for the
51 * application error code and the error message. These parameters should not be
52 * defined by your DAO. If the DAO overwrites any of these two parameters, the
53 * DAOManager will throw an StoredProcedureReservedIndexException. The only
54 * exception is the SELECT operations that is using a database functions that
55 * returns a ResultSet. For this function the reserved parameters are 1, 2 and
56 * 3.
57 *
58 * Return code 0 (ZERO) = successful
59 *
60 * Any error code (<>0) returned by stored procedures will automatic be
61 * converted by DAOManager to a Java StoredProcedureException.
62 *
63 *
64 * @author dan.stoica <dan.stoica@acslink.net.au>
65 *
66 */
67 public interface DAOManager
68 {
69
70 /***
71 * The DAOManager create(Object daoBean) API is used to insert a new
72 * instance into the Database. It must only be called on new Entities.
73 *
74 * It Creates a database record given the stored procedure name and the
75 * fields to be inserted for the record in the database.
76 *
77 * @param storedProcBean
78 * @throws StoredProcedureException
79 * @throws SQLException
80 * @throws StoredProcedurePrepareException
81 * @throws InvalidStoredProcedureException
82 * @throws StoredProcedureProccessResultException
83 */
84 public abstract <T> T create(final T daoBean) throws StoredProcedureException, SQLException, StoredProcedurePrepareException,
85 InvalidStoredProcedureException, StoredProcedureProccessResultException;
86
87 /***
88 * Remove a record from the database. To delete a bean from the database use
89 * the remove(Object entityBean) API.
90 *
91 *
92 * @param daoBean -
93 * the bean object describing the record we remove from the
94 * database. The primary key of this object will be used for
95 * remove operation. Other properties will just be ignored.
96 *
97 * @throws SQLException
98 * @throws StoredProcedureException
99 * @throws StoredProcedurePrepareException
100 * @throws StoredProcedureProccessResultException
101 * @throws InvalidStoredProcedureException
102 *
103 */
104 public abstract void delete(final Object daoBean) throws SQLException, StoredProcedureException, StoredProcedurePrepareException,
105 StoredProcedureProccessResultException, InvalidStoredProcedureException;
106
107 /***
108 * The DAOManager update(Object daoBean) API is used to update a database
109 * record given the procedure and the fields to be updated.
110 *
111 * The updated objects state overrides the persistent DAO state in the
112 * database, if one is already present without consideration of the current
113 * state of the database record.
114 *
115 * @param <T>
116 * @param daoBean -
117 * the object containing the details for the record we store in
118 * the database
119 * @throws StoredProcedurePrepareException
120 * @throws SQLException
121 * @throws StoredProcedureException
122 * @throws InvalidStoredProcedureException
123 * @throws StoredProcedureProccessResultException
124 */
125 public abstract <T> void update(final T daoBean) throws StoredProcedurePrepareException, SQLException, StoredProcedureException,
126 InvalidStoredProcedureException, StoredProcedureProccessResultException;
127
128 /***
129 * Load a record from the database given the lookup fields and a mapping of
130 * the result set items to the fields (in order to populate the DAO)
131 *
132 * The DAO '@ID' annotated properties will be used as IN parameters. The OUT
133 * properties. Any other properties including INOUT are ignored.
134 *
135 * Stored Procedure signature - PROCEDURE_NAME(ReturnCode OUT NUMBER,
136 * ReturnText OUT VARCHAR2, arg1 IN TYPE, arg2 IN TYPE, arg3 OUT TYPE, ...);
137 *
138 * @param daoPk
139 * The DAO bean that stores the primary key used by the finder
140 * stored procedure and the return values. The same bean will be
141 * updated and returned.
142 *
143 * @return A list of DAOs containing the results of the find request
144 * @throws StoredProcedurePrepareException
145 * @throws SQLException
146 * @throws StoredProcedureException
147 * @throws StoredProcedureProccessResultException
148 * @throws InvalidStoredProcedureException
149 */
150 public abstract <T> T find(final T daoWithPk) throws SQLException, StoredProcedureException, StoredProcedurePrepareException,
151 StoredProcedureProccessResultException, InvalidStoredProcedureException;
152
153 /***
154 * Find a collection of records using the given search criteria and a
155 * database FUNCTION. The IN parameters of the POJO are used as a query
156 * Criteria. 'Id' annotations will be ignored. All IN parameters of this DAO
157 * are set as IN parameters to the Oracle FUNCTION that executes the
158 * operation. Any OUT, INOUT or Primary Key parameters will be ignored.
159 *
160 * The operation does not supports database STORED PROCEDURES.
161 *
162 *
163 * @return A list of DAOs containing the results of the select request
164 * @param daoBean
165 * @throws SQLException
166 * @throws StoredProcedureException
167 * @throws RecordNotFoundException
168 * @throws StoredProcedurePrepareException
169 * @throws StoredProcedureProccessResultException
170 * @throws InvalidStoredProcedureException
171 */
172 public abstract <T> List<T> select(final T daoBean) throws SQLException, StoredProcedureException, RecordNotFoundException,
173 StoredProcedurePrepareException, StoredProcedureProccessResultException, InvalidStoredProcedureException;
174
175 /***
176 * The same as select(final T daoBean) but is restricting the number of the
177 * returned results.
178 *
179 * @param <T>
180 * @param daoBean
181 * @param startPosition
182 * The start position of the first result, numbered from 0. e. A
183 * positive number indicates the row number counting from the
184 * beginning of the result set; a negative number indicates the
185 * row number counting from the end of the result set
186 * @param maxResult
187 * The maximum number of results to retrieve.
188 * @return A Java Collection containing the data.
189 * @throws SQLException
190 * @throws StoredProcedureException
191 * @throws RecordNotFoundException
192 * @throws StoredProcedurePrepareException
193 * @throws StoredProcedureProccessResultException
194 * @throws InvalidStoredProcedureException
195 */
196 public abstract <T> List<T> select(final T daoBean, int startPosition, int maxResult) throws SQLException, StoredProcedureException,
197 RecordNotFoundException, StoredProcedurePrepareException, StoredProcedureProccessResultException, InvalidStoredProcedureException;
198
199 /***
200 *
201 * Find a collection of records using the given search criteria and an
202 * database FUNCTION. The Search criteria is specified using a queryBean DAO
203 * object. The IN parameters of this object are set as IN parameters to the
204 * Oracle Function that executes the operation. Any OUT, INOUT or Primary
205 * Key parameters will be ignored.
206 *
207 * The operation does not supports database stored procedures.
208 *
209 * @param queryBean
210 * is a DAO that contains the IN parameters for the query.
211 * @param returnType
212 * The type of the POJO objects returned in the result List
213 * @return A list of POJO Object containing the results of the select
214 * request
215 * @throws SQLException
216 * @throws StoredProcedureException
217 * @throws RecordNotFoundException
218 * @throws StoredProcedurePrepareException
219 * @throws StoredProcedureProccessResultException
220 * @throws InvalidStoredProcedureException
221 */
222 public <T> List<T> select(final Object queryBean, Class<T> returnType) throws SQLException, StoredProcedureException, RecordNotFoundException,
223 StoredProcedurePrepareException, StoredProcedureProccessResultException, InvalidStoredProcedureException;
224
225 public <T> List<T> select(final Object queryBean, Class<T> returnType, int startPosition, int maxResult) throws SQLException,
226 StoredProcedureException, RecordNotFoundException, StoredProcedurePrepareException, StoredProcedureProccessResultException,
227 InvalidStoredProcedureException;
228
229 /***
230 * Execute the database Stored Procedure associated with the Stored
231 * Procedure Java Bean
232 *
233 * @param daoBean -
234 * generic Java Bean associated with a database Stored Procedure
235 * @return
236 * @throws StoredProcedureException
237 * @throws SQLException
238 * @throws StoredProcedurePrepareException
239 * @throws OperationNotSupportedException
240 * @throws InvalidStoredProcedureException
241 * @throws StoredProcedureProccessResultException
242 *
243 */
244 public abstract <T> T execute(final T daoBean) throws StoredProcedureException, SQLException, StoredProcedurePrepareException,
245 OperationNotSupportedException, InvalidStoredProcedureException, StoredProcedureProccessResultException;
246
247 /***
248 * Execute the database Stored Procedure associated with the Stored
249 * Procedure Java Bean restricting the number of the results return by
250 * ResultSet OUT parameters.
251 *
252 * @param <T>
253 * @param daoBean
254 * @param startPosition
255 * The start position of the first result, numbered from 0. e. A
256 * positive number indicates the row number counting from the
257 * beginning of the result set; a negative number indicates the
258 * row number counting from the end of the result set
259 * @param maxResult
260 * The maximum number of results to retrieve.
261 * @return
262 * @throws StoredProcedureException
263 * @throws SQLException
264 * @throws StoredProcedurePrepareException
265 * @throws OperationNotSupportedException
266 * @throws InvalidStoredProcedureException
267 * @throws StoredProcedureProccessResultException
268 */
269 public abstract <T> T execute(final T daoBean, int startPosition, int maxResult) throws StoredProcedureException, SQLException,
270 StoredProcedurePrepareException, OperationNotSupportedException, InvalidStoredProcedureException,
271 StoredProcedureProccessResultException;
272
273 }