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.util;
018
019
020 import java.util.Collection;
021 import java.util.List;
022 import java.util.Map;
023
024 import org.apache.commons.scaffold.lang.ParameterException;
025 import org.apache.commons.scaffold.lang.PopulateException;
026 import org.apache.commons.scaffold.lang.ResourceException;
027
028
029 // ------------------------------------------------------------------------ 78
030
031 /**
032 * Describes an implementation of standard Store, Retrieve, and Delete
033 * operations using the command pattern.
034 * <P>
035 * Developers or Database Administrators may define data access
036 * commands, such as SQL queries, in an external resource.
037 * <P>
038 * The Java code refers to these commands by name. Commands may be
039 * changed in the external resource without changing the Java
040 * source code. A named command may include a sequence of queries
041 * if needed [TODO].
042 * <P>
043 * The parameters required by each command may be specified in the
044 * external resource [TODO] or in the Java code (or both).
045 * <P>
046 * The columns referenced by a command are represented as
047 * JavaBean properties. The result of the command may be applied
048 * against the instant StorageBean, returned as a collection of
049 * bean, or returned as an arbitrary result object. If no
050 * data is returned, a result code may be set.
051 * <P>
052 * Each subclass may specify its own command prefix so that
053 * like-named commands can be stored in the same resource,
054 * or the prefix may represent separate resources.
055 * <P>
056 * [TODO] The external resources are defined as CommandStore
057 * objects, which may be maintained as Properties files, XML
058 * documents, or some other type of resource file.
059 * <P>
060 * <B>StorageBean differs from other approaches</B> to persistence
061 * in that it does presume that SQL will be generated
062 * dynamically.
063 * Rather than model the database in XML and the SQL as
064 * "criteria" objects, developers or DBAs can provide the
065 * appropriate data access commands (SQL).
066 * Since the commands are referenced using a logical name, and
067 * loaded from an external file, coupling between the Java
068 * code and data access code is minimized.
069 * <P>
070 * The SQL/JDBC implementations of StorageBean use reflection
071 * to populate a JavaBean from a ResultSet.
072 * This avoids defining the columns and properties by hand.
073 * All developers need to provide is the SQL that will
074 * obtain the desired properties (columns) as one or more
075 * SQL commands.
076 *
077 * TODO: Multiple queries in a command
078 * TODO: Parameters in command file
079 * TODO: CommandStore objects
080 * @author Ted Husted
081 * @author OK State DEQ
082 * @author WXXI Public Broadcasting Council
083 * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
084 */
085 public interface StorageBean extends Storable,ProcessBean {
086
087
088 /*
089
090 NOTES:
091
092 util.OptimisticStorage
093
094 public Object getTimestamp();
095 public void setTimestamp(Timestamp timestamp);
096
097 public void checkEdited(boolean check);
098
099 public boolean lockResource(boolean lock);
100
101 public Object getEdited();
102
103 public Object getEditor();
104 public void setEditor(Object editor);
105
106
107 sql.JdbcStorageBean implements ProcessBean, StorageBean, OptimisticStorage (StorageBeanBase)
108
109 util.CommandStore;
110 util.CommandStoreProperties;
111 util.CommandStoreDocument;
112
113 prefix.param
114 prefix.command=query;query;
115 prefix.command.param=parm,param;param
116 prefix.command.success=message;message
117 prefix.command.failure=message;message
118 prefix.command.empy=message;message
119
120 util.CommandStoreDocument (XML)
121
122 <prefix id="prefix">
123 <param></param>
124 <command id="command">
125 <query id="#">query</query>
126 <param id="#">param,param</param>
127 </command>
128 </prefix>
129
130 */
131
132 // --------------------------------------------------------------------
133
134
135 /**
136 * [:TODO: Javadoc]
137 */
138 public String getPrefix();
139
140
141 /**
142 * [:TODO: Javadoc]
143 */
144 public void setPrefix(String prefix);
145
146
147 /**
148 * [:TODO: Javadoc]
149 */
150 public Object[] getParameters(String command) throws ResourceException;
151
152
153 /**
154 * [:TODO: Javadoc]
155 */
156 public void setParameters(Object[] parameters);
157
158
159 /**
160 * [:TODO: Javadoc]
161 */
162 public List getParamList(String command) throws ResourceException;
163
164
165 /**
166 * [:TODO: Javadoc]
167 */
168 public void setParamList(List parameters);
169
170
171 /**
172 * Populate this bean from the entries on the
173 * provided map.
174 * The base implementation uses BeanUtils to
175 * efficiently populate the bean through reflection.
176 * @exception Subclasses can throw any Exception
177 */
178 public void populate(Map parameters) throws Exception;
179
180
181 // -------------------------------------------------- Retrieval Methods
182
183
184 /**
185 * Count of matching entries.
186 * @param command Name of command to execute
187 * @param parameter A parameter to be used with command, if any
188 * @return Count of matching entries
189 * @exception Resource exception if data access error occurs
190 */
191 public int count(
192 String command,
193 Object parameter)
194 throws ResourceException;
195
196
197 /**
198 * Lookup command and execute "update" query to create a table,
199 * seed it with data, et cetera.
200 * <p>
201 * @param command Name of command to execute
202 * @exception Resource exception if data access error occurs
203 */
204 public void executeUpdate(String command)
205 throws ResourceException;
206
207
208 /**
209 * Lookup command (sans prefix) and execute "update" query to create a table,
210 * seed it with data, et cetera.
211 * <p>
212 * @param command Name of command to execute
213 * @exception Resource exception if data access error occurs
214 */
215 public void executeUpdateRoot(String command)
216 throws ResourceException;
217
218
219 /**
220 * Retrieve object from data storage.
221 * <P>
222 * <B>NOTE</B> that the precursor to this inteface,
223 * the <CODE>AccessBase</CODE> class reversed the
224 * command and key parameters.
225 * This was inconsistent with how the parameters were
226 * used elsewhere.
227 * If you are converting from AccessBase, be sure to
228 * submit the parameters in the correct order.
229 * @return True if object is found
230 * @exception ResourceException if SQL error occurs
231 * @param target Object to use as factory when populating
232 * (e.g. this)
233 * @param key The primary key of the entry
234 * @param command The name of the data access command
235 * collection
236 */
237 public boolean findElement(
238 Object target,
239 String command,
240 Object key) throws ResourceException;
241
242
243 /**
244 * Retrieve a collection of beans from data storage.
245 * <p>
246 * @return Collection with entry or empty collection
247 * @exception throws ResourceException if data access error occurs
248 * @param target Object to use as factory when populating
249 * (e.g. this)
250 * @param command Name of the data access command
251 * collection
252 * @param parameters An array of parameters to be used with command
253 */
254 public Collection findCollection(
255 Object target,
256 String command,
257 Object[] parameters) throws ResourceException;
258
259
260
261 /**
262 * Select entries from data storage by indexed property..
263 * <p>
264 * @return Collection with record or empty Collection
265 * @param target Object to use as factory when populating
266 * collection (e.g. this)
267 * @param property Field to search
268 * @param value Term to match
269 * @exception Throws ParameterException if value is not a search
270 * term for property
271 * @exception Throws PopulateExeception if result cannot be set
272 * to target
273 * @exception throws PropertiesException, ResourceException on
274 * SQL, IO, or other data access error occurs.
275 */
276 public Collection findByProperty(
277 Object target,
278 String property,
279 String value) throws ParameterException,
280 PopulateException, ResourceException;
281
282
283 // ------------------------------------------------------------- store
284
285
286 /**
287 * Return whether this is a new record,
288 * or one that has already been stored.
289 * @return "new" status for this object.
290 */
291 public boolean isNew();
292
293
294 /**
295 * Returns next sequential key for given set of keys.
296 *
297 * @return An object representing the allocated key
298 * @exception ResourceException if data access error occurs
299 * @param keyName The name of the key set to use to generate
300 * the key
301 */
302 public Object createKey(String keyName)
303 throws ResourceException;
304
305
306 /**
307 * Commit this object to storage.
308 * <P>
309 * This signature is designed for compatibilty with
310 * the Executable interface.
311 */
312 public Object store(Object parameters) throws Exception;
313
314
315 /**
316 * Retrieve this object from storage.
317 * <P>
318 * This signature is designed for compatibilty with
319 * the Executable interface.
320 */
321 public Object retrieve(Object parameters) throws Exception;
322
323
324 /**
325 * Mark this object for deletion.
326 * <P>
327 * This signature is designed for compatibilty with
328 * the Executable interface.
329 */
330 public Object recycle(Object parameters) throws Exception;
331
332
333 /**
334 * Unmake this object for deletion.
335 * <P>
336 * This signature is designed for compatibilty with
337 * the Executable interface.
338 */
339 public Object restore(Object parameters) throws Exception;
340
341
342 /**
343 * Permanently delete this object from data storage.
344 * <P>
345 * This signature is designed for compatibilty with
346 * the Executable interface.
347 */
348 public Object delete(Object parameters) throws Exception;
349
350
351 } // end StorageBean