1 /*
2 * Copyright 2001,2004 The Apache Software Foundation.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package org.apache.commons.scaffold.sql;
18
19
20 import java.sql.SQLException;
21 import java.util.Collection;
22 import java.util.Properties;
23
24
25 import org.apache.commons.scaffold.lang.ParameterException;
26 import org.apache.commons.scaffold.lang.PopulateException;
27 import org.apache.commons.scaffold.lang.PropertiesException;
28 import org.apache.commons.scaffold.lang.ResourceException;
29
30 import org.apache.commons.scaffold.lucene.SearchUtils;
31 import org.apache.commons.scaffold.lucene.Engine;
32
33 import org.apache.commons.scaffold.sql.StatementUtils;
34
35
36 /**
37 * Common data access methods.
38 *
39 * @author Ted Husted
40 * @author OK State DEQ
41 * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
42 * @deprecated Use StorageBean instead.
43 */
44 public class AccessBase {
45
46
47 /**
48 * [:TODO: Javadoc]
49 */
50 public static String KEYS_NEXT = "keys.next";
51
52 /**
53 * [:TODO: Javadoc]
54 */
55 public static String KEYS_INC = "keys.inc";
56
57
58
59 // ----------------------------------------------------------- Commands
60
61 /**
62 * Our command string properties.
63 * Can be loaded from an external properties file at startup.
64 */
65 private static Properties commands;
66
67
68 /**
69 * Retrieve command from <code>commands</code> Properties for
70 * <code>key</code>.
71 *
72 * @fixme Could use a merge feature to reuse common substrings,
73 * like table names ["SELECT ${searchFields} FROM ${articleTable}"]
74 */
75 public static final String getCommand(String key)
76 throws PropertiesException {
77
78 // MissingResourceException ?
79 if (null==commands) throw new PropertiesException();
80
81 return commands.getProperty(key);
82 }
83
84
85 /**
86 * Set the Properties file to be used for SQL commands.
87 * This can be called by main or in a servlet.init
88 * method at startup. If called more than once, the
89 * new commands are added to the existing store.
90 * If keys clash,the last one wins.
91 */
92 public static final void init(Properties _commands) {
93
94 if (null==commands) {
95 commands = _commands;
96 }
97 else {
98 commands.putAll(_commands);
99 }
100 }
101
102
103 // ================================================================ API
104
105
106
107 // ----------------------------------------------------- Create Methods
108
109 /**
110 * Lookup command and execute "update" query to create a table,
111 * seed it with data, et cetera.
112 * <p>
113 * @param command Name of command to execute
114 * @exception Resource exception if data access error occurs
115 * @author Ted Husted
116 * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
117 */
118 public static final void executeUpdate(String command)
119 throws ResourceException {
120
121 try {
122
123 int result = StatementUtils.executeUpdate(
124 null,getCommand(command));
125
126 }
127 catch (SQLException e) {
128 throw new ResourceException(e);
129 }
130
131 } // end createTables()
132
133
134 /**
135 * Returns next sequential key for given set of keys.
136 * Expects KEYS_NET nd KEYS_INC commands to be defined.
137 *
138 * @return A String representing the allocated key
139 * @exception ResourceException if data access error occurs
140 * @param keyName The name of the key set to use to generate the key
141 */
142 public static final Integer createKey(String keyName)
143 throws ResourceException {
144
145 Integer result = null;
146
147 try {
148
149 // createKey is syncronized
150 result = (Integer) StatementUtils.createKey(
151 null,
152 1,
153 getCommand(KEYS_NEXT),
154 getCommand(keyName),
155 getCommand(KEYS_INC)
156 );
157 }
158
159 catch (SQLException e) {
160 throw new ResourceException(e);
161 }
162
163 return result;
164
165 } // end createKey()
166
167
168
169 // -------------------------------------------------- Retrieval Methods
170
171
172 /**
173 * Retrieve entry from data storage.
174 * <P>
175 * <B>NOTE</B> that the key and command parameters to this utility
176 * should have been swapped for consistency with other
177 * methods in this package. But since this class is deprecated,
178 * a fix has not been made.
179 * @return Collection with record or empty collection
180 * @exception ResourceException if SQL error occurs
181 * @param key The primary key of the entry
182 * @param target Bean to hold copy of entry being retrieved
183 * @param command The name of the data access command
184 * collection
185 */
186 public static boolean findElement(
187 Object target,
188 Object key,
189 String command) throws ResourceException {
190
191 boolean found = false;
192
193 try {
194
195 found = StatementUtils.getElement(null,target,
196 getCommand(command),key);
197
198 }
199 catch (SQLException e) {
200 throw new ResourceException(e);
201 }
202
203 return found;
204
205 } // end findElement
206
207
208 /**
209 * Retrieve a collection of beans from data stoarge.
210 * <p>
211 * @return Collection with entry or empty collection
212 * @exception throws PropertiesException, ResourceException
213 * if data access error occurs
214 * @param target Object to use as factory when populating
215 * @param command Name of the data access command
216 * collection
217 */
218 public static final Collection findCollection(Object target,
219 String command) throws ResourceException {
220
221 try {
222
223 return StatementUtils.getCollection(null,
224 target,getCommand(command));
225
226 }
227 catch (SQLException e) {
228 throw new ResourceException(e);
229 }
230
231 } // end findCollection
232
233
234 /**
235 * Retrieve a collection of beans from data stoarge.
236 * <p>
237 * @return Collection with entry or empty collection
238 * @exception throws PropertiesException, ResourceException
239 * if data access error occurs
240 * @param target Object to use as factory when populating
241 * @param command Name of the data access command
242 * collection
243 * @param parameters An array of parameters to be used with command
244 */
245 public static final Collection findCollection(Object target,
246 String command, Object[] parameters) throws ResourceException {
247
248 try {
249
250 return StatementUtils.getCollection(null,
251 target,getCommand(command),parameters);
252
253 }
254 catch (SQLException e) {
255 throw new ResourceException(e);
256 }
257
258 } // end findCollection
259
260
261 /**
262 * Retrieve a collection of beans from data stoarge.
263 * <p>
264 * @return Collection with entry or empty collection
265 * @exception throws PropertiesException, ResourceException
266 * if data access error occurs
267 * @param target Object to use as factory when populating
268 * @param command Name of the data access command
269 * collection
270 * @param parameter A String parameter to be used with command
271 */
272 public static final Collection findCollection(Object target,
273 String command, Object parameter) throws ResourceException {
274
275 try {
276
277 return StatementUtils.getCollection(null,
278 target,getCommand(command),parameter);
279
280 }
281 catch (SQLException e) {
282 throw new ResourceException(e);
283 }
284
285 } // end findCollection
286
287
288 /**
289 * Retrieve a collection of beans from data stoarge.
290 * <p>
291 * @return Collection with entry or empty collection
292 * @exception throws PropertiesException, ResourceException
293 * if data access error occurs
294 * @param target Object to use as factory when populating
295 * @param command Name of the data access command
296 * collection
297 * @param parameter An int parameter to be used with command
298 */
299 public static final Collection findCollection(Object target,
300 String command, int parameter) throws ResourceException {
301
302 return findCollection(target,command,new Integer(parameter));
303
304 } // end findCollection
305
306
307 /**
308 * Retrieve a collection of beans from data stoarge.
309 * <p>
310 * @return Collection with entry or empty collection
311 * @exception throws PropertiesException, ResourceException
312 * if data access error occurs
313 * @param target Object to use as factory when populating
314 * @param command Name of the data access command
315 * collection
316 * @param parameter A String parameter to be used with command
317 */
318 public static final Collection findCollectionLike(Object target,
319 String command, String parameter) throws ResourceException {
320
321 try {
322
323 return StatementUtils.getCollection(null,
324 target,getCommand(command),StatementUtils.like(parameter));
325
326 }
327 catch (SQLException e) {
328 throw new ResourceException(e);
329 }
330
331 } // end findCollectionLike
332
333
334 /**
335 * Select entries from data storage by indexed property..
336 * <p>
337 * @return Collection with record or empty Collection
338 * @param value Term to match
339 * @param property Field to search
340 * @param target Object to use as factory when populating
341 * collection
342 * @exception Throws ParameterException if value is not a search
343 * term for property
344 * @exception Throws PopulateExecption if result cannot be set to
345 * target
346 * @exception throws PropertiesException, ResourceException is SQL, IO, or other
347 * data access error occurs.
348 */
349 public static final Collection findByProperty(
350 Object target,
351 String property,
352 String value) throws ParameterException, PopulateException,
353 ResourceException {
354
355 return SearchUtils.getCollection(target,
356 Engine.getHits(
357 Engine.getQuery(value,property)));
358
359 } // end findByProperty
360
361
362 // -------------------------------------------------------- UD Methods
363
364 /**
365 * Commit record to storage.
366 * If create is true, entry is created.
367 * Otherwise, an existing entry is updated.
368 * @return 0 if fails
369 * @exception ResourceException if SQL error occurs
370 * @param insert True to insert, false to update.
371 * @insert The name of the insert command
372 * @update The name of the delete command
373 @ @parameters The parameters to use with either command
374 *
375 */
376 public static final int store (
377 boolean isInsert,
378 String insert,
379 String update,
380 Object[] parameters) throws ResourceException {
381
382 String command = null;
383 if (isInsert) {
384 command = getCommand(insert);
385 }
386 else {
387 command = getCommand(update);
388 }
389
390 int result = 0;
391 try {
392
393 result = StatementUtils.executeUpdate(null,command,parameters);
394
395 }
396 catch (SQLException e) {
397 throw new ResourceException(e);
398 }
399
400 return result;
401
402 } // end store
403
404
405 /**
406 * Mark entry for deletion.
407 * Returns copy of entry before update in target parameter.
408 *
409 * @return 0 if fails
410 * @exception ResourceException if SQL or other data-access error occurs
411 * @exception runtime Null Pointer Exception if either parameter is null
412 * @param target Bean to hold copy of record being marked
413 * @param article Primary key of record to mark
414 */
415 public static final int delete(Object target, Integer key, String command)
416 throws ResourceException {
417
418 int result = 0;
419
420 try {
421
422 // Mark as deleted
423 result = StatementUtils.executeUpdate(null,
424 getCommand(command),key);
425 }
426
427 catch (SQLException e) {
428 throw new ResourceException(e);
429 }
430
431 return result;
432
433 } // end delete
434
435
436 /**
437 * Unmark entry for deletion.
438 * Returns copy of restored entry in target parameter.
439 *
440 * @return 0 if fails
441 * @exception ResourceException if data access error occurs
442 * @param target Bean to hold copy of record being unmarked
443 * @param article Primary key of record to unmark
444 */
445 public static final int restore(Object target, Integer key, String command)
446 throws ResourceException {
447
448 int result = 0;
449
450 try {
451
452 result = StatementUtils.executeUpdate(null,
453 getCommand(command),key);
454
455 }
456 catch (SQLException e) {
457 throw new ResourceException(e);
458 }
459
460 return result;
461
462 } // end restore
463
464
465 } // end Access
466