/*

  * Copyright 2001,2004 The Apache Software Foundation.

  * 

  * Licensed under the Apache License, Version 2.0 (the "License");

  * you may not use this file except in compliance with the License.

  * You may obtain a copy of the License at

  * 

  *      http://www.apache.org/licenses/LICENSE-2.0

  * 

  * Unless required by applicable law or agreed to in writing, software

  * distributed under the License is distributed on an "AS IS" BASIS,

  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  * See the License for the specific language governing permissions and

  * limitations under the License.

  */

 package org.apache.commons.scaffold.util;

 import java.util.Collection;

 import java.util.List;

 import java.util.Map;

 import org.apache.commons.scaffold.lang.ParameterException;

 import org.apache.commons.scaffold.lang.PopulateException;

 import org.apache.commons.scaffold.lang.ResourceException;

 // ------------------------------------------------------------------------ 78

 /**

  * Describes an implementation of standard Store, Retrieve, and Delete

  * operations using the command pattern.

  * <P>

  * Developers or Database Administrators may define data access

  * commands, such as SQL queries, in an external resource.

  * <P>

  * The Java code refers to these commands by name. Commands may be

  * changed in the external resource without changing the Java

  * source code. A named command may include a sequence of queries

  * if needed [TODO].

  * <P>

  * The parameters required by each command may be specified in the

  * external resource [TODO] or in the Java code (or both).

  * <P>

  * The columns referenced by a command are represented as

  * JavaBean properties. The result of the command may be applied

  * against the instant StorageBean, returned as a collection of

  * bean, or returned as an arbitrary result object. If no

  * data is returned, a result code may be set.

  * <P>

  * Each subclass may specify its own command prefix so that

  * like-named commands can be stored in the same resource,

  * or the prefix may represent separate resources.

  * <P>

  * [TODO] The external resources are defined as CommandStore

  * objects, which may be maintained as Properties files, XML

  * documents, or some other type of resource file.

  * <P>

  * <B>StorageBean differs from other approaches</B> to persistence

  * in that it does presume that SQL will be generated

  * dynamically.

  * Rather than model the database in XML and the SQL as

  * "criteria" objects, developers or DBAs can provide the

  * appropriate data access commands (SQL).

  * Since the commands are referenced using a logical name, and

  * loaded from an external file, coupling between the Java

  * code and data access code is minimized.

  * <P>

  * The SQL/JDBC implementations of StorageBean use reflection

  * to populate a JavaBean from a ResultSet.

  * This avoids defining the columns and properties by hand.

  * All developers need to provide is the SQL that will

  * obtain the desired properties (columns) as one or more

  * SQL commands.

  *

  * TODO: Multiple queries in a command

  * TODO: Parameters in command file

  * TODO: CommandStore objects

  * @author Ted Husted

  * @author OK State DEQ

  * @author WXXI Public Broadcasting Council

  * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $

  */

 public interface StorageBean extends Storable,ProcessBean {

 /*

 NOTES:

 util.OptimisticStorage

     public Object getTimestamp();

     public void setTimestamp(Timestamp timestamp);

     public void checkEdited(boolean check);

     public boolean lockResource(boolean lock);

     public Object getEdited();

     public Object getEditor();

     public void setEditor(Object editor);

 sql.JdbcStorageBean implements ProcessBean, StorageBean, OptimisticStorage (StorageBeanBase)

 util.CommandStore;

     util.CommandStoreProperties;

     util.CommandStoreDocument;

 prefix.param

 prefix.command=query;query;

 prefix.command.param=parm,param;param

 prefix.command.success=message;message

 prefix.command.failure=message;message

 prefix.command.empy=message;message

 util.CommandStoreDocument (XML)

 <prefix id="prefix">

 <param></param>

 <command id="command">

 <query id="#">query</query>

 <param id="#">param,param</param>

 </command>

 </prefix>

 */

 // --------------------------------------------------------------------

     /**

      * [:TODO: Javadoc]

      */

     public String getPrefix();

     /**

      * [:TODO: Javadoc]

      */

     public void setPrefix(String prefix);

     /**

      * [:TODO: Javadoc]

      */

     public Object[] getParameters(String command) throws ResourceException;

     /**

      * [:TODO: Javadoc]

      */

     public void setParameters(Object[] parameters);

     /**

      * [:TODO: Javadoc]

      */

     public List getParamList(String command) throws ResourceException;

     /**

      * [:TODO: Javadoc]

      */

     public void setParamList(List parameters);

     /**

      * Populate this bean from the entries on the

      * provided map.

      * The base implementation uses BeanUtils to

      * efficiently populate the bean through reflection.

      * @exception Subclasses can throw any Exception

      */

     public void populate(Map parameters) throws Exception;

 // -------------------------------------------------- Retrieval Methods

     /**

      * Count of matching entries.

      * @param command Name of command to execute

      * @param parameter A parameter to be used with command, if any

      * @return Count of matching entries

      * @exception Resource exception if data access error occurs

      */

     public int count(

             String command,

             Object parameter)

             throws ResourceException;

     /**

      * Lookup command and execute "update" query to create a table,

      * seed it with data, et cetera.

      * <p>

      * @param command Name of command to execute

      * @exception Resource exception if data access error occurs

      */

     public void executeUpdate(String command)

             throws ResourceException;

     /**

      * Lookup command (sans prefix) and execute "update" query to create a table,

      * seed it with data, et cetera.

      * <p>

      * @param command Name of command to execute

      * @exception Resource exception if data access error occurs

      */

     public void executeUpdateRoot(String command)

             throws ResourceException;

     /**

      * Retrieve object from data storage.

      * <P>

      * <B>NOTE</B> that the precursor to this inteface,

      * the <CODE>AccessBase</CODE> class reversed the

      * command and key parameters.

      * This was inconsistent with how the parameters were

      * used elsewhere.

      * If you are converting from AccessBase, be sure to

      * submit the parameters in the correct order.

      * @return True if object is found

      * @exception ResourceException if SQL error occurs

      * @param target Object to use as factory when populating

      * (e.g. this)

      * @param key The primary key of the entry

      * @param command The name of the data access command

      * collection

      */

     public boolean findElement(

             Object target,

             String command,

             Object key) throws ResourceException;

     /**

      * Retrieve a collection of beans from data storage.

      * <p>

      * @return Collection with entry or empty collection

      * @exception throws ResourceException if data access error occurs

      * @param target Object to use as factory when populating

      * (e.g. this)

      * @param command Name of the data access command

      * collection

      * @param parameters An array of parameters to be used with command

      */

     public Collection findCollection(

             Object target,

             String command,

             Object[] parameters) throws ResourceException;

     /**

      * Select entries from data storage by indexed property..

      * <p>

      * @return Collection with record or empty Collection

      * @param target Object to use as factory when populating

      * collection (e.g. this)

      * @param property Field to search

      * @param value Term to match

      * @exception Throws ParameterException if value is not a search

      * term for property

      * @exception Throws PopulateExeception if result cannot be set

      * to target

      * @exception throws PropertiesException, ResourceException on

      * SQL, IO, or other data access error occurs.

      */

     public Collection findByProperty(

             Object target,

             String property,

             String value) throws ParameterException,

             PopulateException, ResourceException;

 // ------------------------------------------------------------- store

     /**

      * Return whether this is a new record,

      * or one that has already been stored.

      * @return "new" status for this object.

      */

     public boolean isNew();

     /**

      * Returns next sequential key for given set of keys.

      *

      * @return An object representing the allocated key

      * @exception ResourceException if data access error occurs

      * @param keyName The name of the key set to use to generate

      * the key

      */

     public Object createKey(String keyName)

             throws ResourceException;

     /**

      * Commit this object to storage.

      * <P>

      * This signature is designed for compatibilty with

      * the Executable interface.

      */

     public Object store(Object parameters) throws Exception;

     /**

      * Retrieve this object from storage.

      * <P>

      * This signature is designed for compatibilty with

      * the Executable interface.

      */

     public Object retrieve(Object parameters) throws Exception;

     /**

      * Mark this object for deletion.

      * <P>

      * This signature is designed for compatibilty with

      * the Executable interface.

      */

     public Object recycle(Object parameters) throws Exception;

     /**

      * Unmake this object for deletion.

      * <P>

      * This signature is designed for compatibilty with

      * the Executable interface.

      */

     public Object restore(Object parameters) throws Exception;

     /**

      * Permanently delete this object from data storage.

      * <P>

      * This signature is designed for compatibilty with

      * the Executable interface.

      */

     public Object delete(Object parameters) throws Exception;

 } // end StorageBean