001 /*
002 * Copyright 2001,2004 The Apache Software Foundation.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017 package org.apache.commons.scaffold.sql;
018
019
020 import java.sql.SQLException;
021 import java.util.Collection;
022 import java.util.Properties;
023
024
025 import org.apache.commons.scaffold.lang.ParameterException;
026 import org.apache.commons.scaffold.lang.PopulateException;
027 import org.apache.commons.scaffold.lang.PropertiesException;
028 import org.apache.commons.scaffold.lang.ResourceException;
029
030 import org.apache.commons.scaffold.lucene.SearchUtils;
031 import org.apache.commons.scaffold.lucene.Engine;
032
033 import org.apache.commons.scaffold.sql.StatementUtils;
034
035
036 /**
037 * Common data access methods.
038 *
039 * @author Ted Husted
040 * @author OK State DEQ
041 * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
042 * @deprecated Use StorageBean instead.
043 */
044 public class AccessBase {
045
046
047 /**
048 * [:TODO: Javadoc]
049 */
050 public static String KEYS_NEXT = "keys.next";
051
052 /**
053 * [:TODO: Javadoc]
054 */
055 public static String KEYS_INC = "keys.inc";
056
057
058
059 // ----------------------------------------------------------- Commands
060
061 /**
062 * Our command string properties.
063 * Can be loaded from an external properties file at startup.
064 */
065 private static Properties commands;
066
067
068 /**
069 * Retrieve command from <code>commands</code> Properties for
070 * <code>key</code>.
071 *
072 * @fixme Could use a merge feature to reuse common substrings,
073 * like table names ["SELECT ${searchFields} FROM ${articleTable}"]
074 */
075 public static final String getCommand(String key)
076 throws PropertiesException {
077
078 // MissingResourceException ?
079 if (null==commands) throw new PropertiesException();
080
081 return commands.getProperty(key);
082 }
083
084
085 /**
086 * Set the Properties file to be used for SQL commands.
087 * This can be called by main or in a servlet.init
088 * method at startup. If called more than once, the
089 * new commands are added to the existing store.
090 * If keys clash,the last one wins.
091 */
092 public static final void init(Properties _commands) {
093
094 if (null==commands) {
095 commands = _commands;
096 }
097 else {
098 commands.putAll(_commands);
099 }
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