/*
    * 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.sql;
  
  
  import java.sql.SQLException;
  import java.sql.Timestamp;
  import java.util.Collection;
  import java.util.Iterator;
  import java.util.List;
  import java.util.Map;
  import java.util.Properties;
  
  import org.apache.commons.beanutils.BeanUtils;
  import org.apache.commons.scaffold.lang.ParameterException;
  import org.apache.commons.scaffold.lang.PopulateException;
  import org.apache.commons.scaffold.lang.PropertiesException;
  import org.apache.commons.scaffold.lang.ResourceException;
  import org.apache.commons.scaffold.lang.Tokens;
  import org.apache.commons.scaffold.lucene.Engine;
  import org.apache.commons.scaffold.lucene.SearchUtils;
  import org.apache.commons.scaffold.text.ConvertUtils;
  import org.apache.commons.scaffold.util.ProcessBeanBase;
  import org.apache.commons.scaffold.util.ProcessResult;
  import org.apache.commons.scaffold.util.ProcessResultBase;
  import org.apache.commons.scaffold.util.StorageBean;
  
  // ------------------------------------------------------------------------ 78
  
  /**
   * Implements StorageBean interface using
   * <code>StatementUtils</code> and <code>ResultSetUtils</code> in
   * this package. Specialty operations may be added using the same
   * utilities.
   * <P>
   * <B>To use this class, the developer must:</B>
   * <UL>
   * <LI>Declare a subclass adding the properties to be stored.
   * <LI>Provide in a set of standard SQL queries naming the properties
   * to be stored as columns in the command
   * <LI>Override <code>getStorageKey</code> to return the property used
   * as the primary or unique key in the SQL commands.
   * <LI>Override <code>getParameters</code> to return an array of
   * properties as needed by object's insert and update SQL commands.
   * <LI>Override <code>getPrefix</code> to set a unique prefix
   * for each StorageBean class.
   * Include the prefix in the resource file, but not in the Java code.
   * <LI>Provide keys.next and keys.inc SQL commands to obtain a new
   * primary key or override createKey to use some other method.
   * </UL>
   * <P>
   * <B>To specify a connection pool and load the SQL commands:</B>
   * <UL>
   * <LI>Load the <code>ConnectionAdaptor</code> for your database
   * connection pool
   * <LI>Load the <code>Properties</code> file with your commands and
   * pass it to the StorageBeanBase <code>init</code> method.
   * </UL>
   * <P>The <code>ConnectionServlet</code> in this package is designed
   * to load <code>ConnectionAdapters<code> and resource
   * (<code>Properties</code>) files.
   * <P>
   * Regarding the queries:
   * <UL>
   * <LI>The SQL commands are given in a standard Properties file
   * (e.g, user.retrieve=SELECT name,address FROM userTable).
   * The default runtime location is
   * [WEB-INF/classes/resources/command.properties].
   * <LI>See the command.properties.sample file in this package
   * for a starter file.
   * <LI>All the subclass share the same Properties file.
   * The prefix property lets you use the same standard query names for
   * more than one StorageBean.
   * <LI>The standard queries are insert, update, retrieve, delete, and
   * recycle, and restore.
   * <LI>The insert and update commands should use same columns in same
   * order.
   * <LI>The retrieve, delete, recycle, and restore command should use
   * the storageKey property for selection.
   * <LI>Hint: If columns cannot follow property naming conventions,
   * rename column in command
   * <LI>Hint: You can use the same object for more than one table or
   * resultset if you like
   * </UL>
   *
  * @todo Refactor recycle,restore,delete to use common util method
  * @todo Javadocs for new classes
  * @todo Use reflection to read parameter key and make array from
  * that.
  * @todo Check for key.paramlist then paramlist.
  * @todo Permit each subclass to have its own properties (collection
  * of properties, like Struts Actions).
  * @todo Switch to CommandStore (or eliminate that object if not
  * needed).
  * @todo Add properties to manage optimistic locking
  * @todo Change from BeanUtil.populate to copyProperties in 1.1
  * version.
  * @author Ted Husted
  * @author OK State DEQ
  * @version $Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
  */
 public class StorageBeanBase extends ProcessBeanBase implements StorageBean {
 
 
     /**
      * Convenience method to check for null, empty String.
      */
     protected boolean blank(String s) {
         return ConvertUtils.blank(s);
     }
 
     /**
      * Convenience method to check for null, empty String,
      * or "0" String.
      */
     protected boolean blankValue(String s) {
         return ConvertUtils.blankValue(s);
     }
 
     /**
      * Returns true if null or zero.
      */
     public static boolean blank(Number key) {
       return ConvertUtils.blank(key);
     }
 
 
 
 // ------------------------------------------------------------------ Commands
 // TODO: Refactor this to use a CommandStore
 
 
     /**
      * [:TODO: Javadoc]
      */
     public final static String like(String parameter) {
         return StatementUtils.like(parameter);
     }
 
 
     /**
      * [:TODO: Javadoc]
      */
     public final static String DOT = ".";
 
 
     /**
      * Our command string properties.
      * Can be loaded from an external properties file at startup.
      */
     protected static Properties commands;
 
 
     /**
      * Retrieve command from <code>commands</code> Properties
      */
     protected String lookup(String key)
         throws PropertiesException {
 
         if (null==commands) throw new PropertiesException(
             PropertiesException.MESSAGE + key);
 
         String command = null;
         String prefix = getPrefix();
         if (null!=prefix) {
             StringBuffer sb = new StringBuffer(prefix);
             sb.append(DOT);
             sb.append(key);
             command = sb.toString();
         }
         else command = key;
 
         return commands.getProperty(command);
     }
 
 
     /**
      * Retrieve command from <code>commands</code> Properties
      */
     protected String lookupRoot(String key)
         throws PropertiesException {
 
         if (null==commands) throw new PropertiesException(
             PropertiesException.MESSAGE + key);
 
         return commands.getProperty(key);
 
     }
 
 
     /**
      * Set the Properties file to be used for SQL commands.
      * This can be called by main or in a servlet.init
      * method at startup. If called more than once, the
      * new commands are added to the existing store.
      * If  keys clash,the last one wins.
      */
     public static final void init(Properties _commands) {
 
         if (null==commands) {
             commands = _commands;
         }
         else {
             commands.putAll(_commands);
         }
     }
 
 
 // ----------------------------------------------------------- Base Properties
 
     /**
      * [:TODO: Javadoc]
      */
     public final static String INSERT = "insert";
 
 
     /**
      * [:TODO: Javadoc]
      */
     public final static String UPDATE = "update";
 
 
     /**
      * [:TODO: Javadoc]
      */
     public final static String RETRIEVE = "retrieve";
 
 
     /**
      * [:TODO: Javadoc] purge
      */
     public final static String DELETE = "delete";
 
 
     /**
      * [:TODO: Javadoc]
      */
     public final static String RESTORE = "restore";
 
 
     /**
      * [:TODO: Javadoc] delete
      */
     public final static String RECYCLE = "recycle";
 
 
     /**
      * [:TODO: Javadoc]
      */
     public final static String TABLE = "table";
 
 
     /**
      * [:TODO: Javadoc]
      */
     public final static String PARAMS = DOT + "params";
 
 
     /**
      * A unique identifier for this StorageBean's
      * commands.
      */
     private String prefix = null;
 
 
      // See interface for Javadoc
     public String getPrefix() {
         return prefix;
     }
 
 
      // See interface for Javadoc
     public void setPrefix(String prefix) {
         this.prefix = prefix;
     }
 
 
     /**
      * The array of parameters required by the
      * insert and update commands for this object.
      */
     private Object[] parameters = null;
 
 
     /**
      * Return the runtime parameters for the given command.
      *
      * The comma-delimited list of parameter properties can be provided
      * as a ${command}.params element in the command resource. 
      * <code>getParameters</code> will automatically retrieve the *.params element 
      * and use it to create an array of the runtime values for each parameter. 
      * The sequence of runtime values can then be merged with a prepared 
      * statement (the command).
      * Since the parameters are inserted into the command by position, 
      * the column names and parameter names do not need to match. 
      * @exception ResourceException if the command resource or command cannot 
      * be found.
      */
     public Object[] getParameters(String command) throws ResourceException {
         
         if (null==command) {
             if ((null==parameters) && (null!=paramList)) {
                 return paramList.toArray();
             }       
             return parameters;
         }
         
         // Lookup parameters for command ( * + .params)        
         String paramToken = command + PARAMS;        
         String params = lookup(paramToken);
 
         if (null==params) { 
             throw new PropertiesException(
                 PropertiesException.MESSAGE + paramToken);
         } 
         else {
             String[] tokens = ConvertUtils.tokensToArray(params,PARAM_SEP);
             Object[] values = new Object[tokens.length];
             try {
                 for (int i=0; i<values.length; i++) {
                     values[i] = BeanUtils.getProperty(this,tokens[i]);
                 }
             }
             catch (Exception e) {
                 throw new PropertiesException(
                     PropertiesException.MESSAGE + params);
             }
             
             return values;
         }       
     }
 
 
      // See interface for Javadoc
     public void setParameters(Object[] parameters) {
         this.parameters = parameters;
     }
 
 
     /**
      * The list of parameters required by the
      * insert and update commands for this object.
      */
     private List paramList = null;
 
 
     /**
      * Return the vparamList or parameters field. 
      * If both are null, return an empty list.
      */
     private List paramListDefault() throws ResourceException {
         
         List list = paramList;
         if (null==list) { 
                 // Start with empty list
             list = new java.util.ArrayList();
                 // Add array parameters, if any
             Object[] array = getParameters(null);
             if (null!=array) {
                 for (int i =0; i<array.length; i++) {
                     list.add(array[i]);
                 }
             }
         }
         return list;
 
     }
 
 
     /**
      * Default separator character for list of parameters [","] (comma).
      */
     public static final String PARAM_SEP = ",";
 
 
     /**
      * Return the runtime parameters for the given command.
      *
      * The comma-delimited list of parameter properties can be provided
      * as a ${command}.params element in the command resource. 
      * <code>getParameters</code> will automatically retrieve the *.params element 
      * and use it to create a list of the runtime values for each parameter. 
      * The sequence of runtime values can then be merged with a prepared 
      * statement (the command).
      * Since the parameters are inserted into the command by position, 
      * the column names and parameter names do not need to match. 
      * @exception ResourceException if the command resource or command cannot 
      * be found.
      */
     public List getParamList(String command) throws ResourceException {
         
         // If no command, return the list or array field
         if (null==command) return paramListDefault();
         
         List values = new java.util.ArrayList();
         // Lookup parameters for command ( * + .params)        
         String paramToken = command + PARAMS;        
         String params = lookup(paramToken);
         if (null==params) {
             throw new PropertiesException(
                 PropertiesException.MESSAGE + paramToken);
         }
         else {           
             // Tokenize into list/iterator (:TODO: Cache?) (:FIXME: List better than array?)
             Iterator tokens = ConvertUtils.tokensToList(params,PARAM_SEP).iterator();
             // Get the runtime property for each parameter (token)
             try {
                 while (tokens.hasNext()) { 
                     values.add(BeanUtils.getProperty(this,(String)tokens.next()));
                 }
             }
             catch (Exception e) {
                 throw new PropertiesException(
                     PropertiesException.MESSAGE + params);
             }
         }
        return values;
     }
 
 
      // See interface for Javadoc
     public void setParamList(List paramList) {
         this.paramList = paramList;
     }
 
 
     /**
      * The marked status of the record.
      * <p>
      * Records to be deleted are marked and may be
      * restored before they are removed from the
      * database.
      * The default value is "1" - nominal.
      */
     private Short marked = ConvertUtils.SHORT_ONE;
 
 
     /**
      * Return the marked status.
      * <p>
      * @return the marked status
      */
     public Short getMarked() {
         return (this.marked);
     }
 
 
     /**
      * Set the marked status.
      * @param marked The new marked status
      */
     public void setMarked(Short marked) {
         this.marked = marked;
     }
 
 
 // ------------------------------------------------------------ Public Methods
 
 
         // See interface for JavaDoc
     public void populate(Map parameters) throws Exception {
 
         if (parameters!=null) {
             BeanUtils.copyProperties(this,parameters);
         }
 
     } // end populate
 
 
 // ------------------------------------------------------------ Create Methods
 
 
         // See interface for JavaDoc
     public void executeUpdate(String command)
             throws ResourceException {
 
         try {
 
              int result = StatementUtils.executeUpdate(
                  null,lookup(command),getParameters(command));
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
 
     } // end executeUpdate
 
 
     public void executeUpdateRoot(String command)
             throws ResourceException {
 
         try {
 
              int result = StatementUtils.executeUpdate(
                  null,lookupRoot(command));
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
 
     } // end executeUpdate
 
 // ----------------------------------------------------------- Retrieval Methods
 
 
         // Convenience method
     public int count(
             String command)
             throws ResourceException {
 
         Integer result = null;
         try {
             result = (Integer) StatementUtils.getColumn(
                 null,
                 1,
                 lookup(command)
             );
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
         return result.intValue();
     }
 
 
         // See interface for JavaDoc
     public int count(
             String command,
             Object parameter)
             throws ResourceException {
 
         Integer result = null;
         try {
             result = (Integer) StatementUtils.getColumn(
                 null,
                 1,
                 lookup(command),
                 parameter
             );
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
         return result.intValue();
     }
 
 
 
         // See interface for JavaDoc
     public boolean findElement(
             Object target,
             String command,
             Object key) throws ResourceException {
 
         boolean found = false;
 
         try {
 
             found = StatementUtils.getElement(null,target,
                 lookup(command),key);
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
 
         return found;
 
    } // end findElement
 
 
     /**
      * Convenience method that calls
      * <code>findCollection(Object,String,Object[])</code>
      * with appropriate parameters.
      */
     public Collection findCollection(Object target,
         String command) throws ResourceException {
 
         try {
 
             return StatementUtils.getCollection(null,
                 target,lookup(command));
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
 
     } // end findCollection
 
 
     /**
      * Convenience method that calls
      * <code>findCollection(Object,String,Object[])</code>
      * with appropriate parameters.
      */
     protected final Collection findCollection(Object target,
         String command, int parameter) throws ResourceException {
 
 
         try {
 
             return StatementUtils.getCollection(null,
                 target,lookup(command),parameter);
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
     } // end findCollection
 
 
 
     /**
      * Convenience method that calls
      * <code>findCollection(Object,String,Object[])</code>
      * with appropriate parameters.
      */
     protected final Collection findCollection(Object target,
         String command, Object parameter) throws ResourceException {
 
         try {
 
             return StatementUtils.getCollection(null,
                 target,lookup(command),parameter);
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
 
     } // end findCollection
 
 
         // See interface for JavaDoc
     public Collection findCollection(Object target,
         String command, Object[] parameters) throws ResourceException {
 
         try {
 
             return StatementUtils.getCollection(null,
                 target,lookup(command),parameters);
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
 
     } // end findCollection
 
 
         // See interface for JavaDoc
     public Collection findByProperty(
             Object target,
             String property,
             String value) throws ParameterException, PopulateException,
             ResourceException {
 
          return SearchUtils.getCollection(target,
             Engine.getHits(
                 Engine.getQuery(value,property)));
 
     } // end findByProperty
 
 
 // ================================================================ UD Methods
 
     /**
      * The storageKey field, if needed.
      * <p>
      * Many subclasses may choose to ingore this field and
      * use the storageKey property as a wrapper around
      * their own field of a specific type (e.g. 
      * an Integer primaryKey property).
      */
     private Object storageKey = null;
 
 
         // See interface for JavaDoc
     public Object getStorageKey() {
         return this.storageKey;
     }
 
 
         // See interface for JavaDoc
     public void setStorageKey(Object storageKey) {
         this.storageKey = storageKey;
     }
 
     /**
      * The timestamp of the last edit.
      * <p>
      * This can be checked against the edited
      * timestamp on the record in storage
      * to see if anyone else has alreaded
      * edited the record.
      */
     private Timestamp modified = ConvertUtils.NULL_TIMESTAMP;
 
     /**
      * Return the edited timestamp.
      * <p>
      * @return the edited timestamp.
      */
     public Timestamp getModified() {
         return (this.modified);
     }
 
 
     /**
      * Set the edited timestamp.
      * @param edited The new edited timestamp.
      */
     public void setModified(Timestamp modified) {
         this.modified = modified;
     }
 
 
     /**
      * Check to see if another modified timetamp
      * matches the one for this instance.
      * Returns true if the timestamps match.
      * @returns true if the timestamps match.
      * @param edited The new edited timestamp.
      */
     public boolean isCurrent(Timestamp modified) {
         return (modified!=getModified());
     }
 
 
     /**
      * [:TODO: Javadoc]
      */
     private int resultCode = 0;
 
 
         // See interface for JavaDoc
     public int getResultCode() {
         return resultCode;
     }
 
 
         // See interface for JavaDoc
     public void setResultCode(int resultCode) {
         this.resultCode = resultCode;
     }
 
 
     /**
      * [:TODO: Javadoc]
      */
     private Object result = this;
 
 
         // See interface for JavaDoc
     public Object getResult() {
         return result;
     }
 
 
         // See interface for JavaDoc
     public void setResult(Object result) {
         this.result = result;
     }
 
 
 // --------------------------------------------------------------------- store
 
 
     /**
      * If timestamp is null (or ConvertUtils.NULL_TIMESTAMP), 
      * set our modified property to the current time. 
      * This emulates how MySQL treats the first null Timestamp in a record.
      */
    public void fixModified() {   
        Timestamp modified = getModified();
        if ((null==modified) || (ConvertUtils.NULL_TIMESTAMP==modified)) {
            setModified(new Timestamp(System.currentTimeMillis()));
        }
    }
            
    
    public int updateResultCode(String command) throws ResourceException {     
        
         int result = 0;
         try {
 
             result = StatementUtils.executeUpdate(
                 null,lookup(command),getParameters(command));
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
         
         return result;
    }
 
         // see interface for Javadoc
     public Object update(Object parameters) throws Exception {
         
         populate((Map) parameters);
         
         String command = getParameter();
 
         fixModified();
         setResultCode(updateResultCode(command));
 
         String message = null;
         if (isNew()) message = Tokens.DATA_RECORD_INSERTED;
         else message = Tokens.DATA_RECORD_UPDATED;
 
         ProcessResult result = new ProcessResultBase(getResult());
             result.addMessage(message);
             result.addMessage(getStorageKey());
             result.setSingleForm(true);
         return result;
     }
 
 
     public ProcessResult elementResult(String command) throws Exception {
 
         boolean found = false;
         try {
 
             found = StatementUtils.getElement(null,this,
                 lookup(command),getParameters(command));
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
 
         if (found) {
 
             setResult(this);
             setResultCode(1);
 
         }
         else {
             setResultCode(0);
         }
 
         ProcessResult result = new ProcessResultBase(this);
             result.setSingleForm(true);
          return result;         
     }
 
 
     /**
      * Retrieve an element (record) from storage.
      * The element is retrieved is determined by what command 
      * has been set to the parameter property.
      * <P>
      * This signature is designed for compatibilty with
      * the Executable interface.
      */
     public Object element(Object command) throws Exception {
 
         populate((Map) command);
         
         return elementResult(getParameter());       
         
     }
 
 
     public Object collectionResult(String command) throws Exception {
         
         Collection result = null;
 
         try {
 
             result = StatementUtils.getCollection(null,
                 this,lookup(command),getParameters(command));
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
 
         setResult(result);
 
         return new ProcessResultBase(result);
         
     }
 
         
     /**
      * Retrieve a collection of objects from storage.
      * The objects retrieved is determined by what command 
      * has been set to the parameter property.
      * <P>
      * This signature is designed for compatibilty with
      * the Executable interface.
      */
     public Object collection(Object parameters) throws Exception {
 
         populate((Map) parameters);
         
         return collectionResult(getParameter());
 
     }
 
 // --------------------------------------------------------------------- store
 
     /**
      * [:TODO: Javadoc]
      */
     public static String KEYS_NEXT = "keys.next";
 
 
     /**
      * [:TODO: Javadoc]
      */
     public static String KEYS_INC = "keys.inc";
 
 
         // See interface for JavaDoc
     public boolean isNew() {
         Object key = getStorageKey();
         return ((null==key) || (blankValue(key.toString())));
     }
 
 
         // See interface for JavaDoc
         // @todo Refactor to use fixed-length high/low String as key.
     public Object createKey(String keyName)
             throws ResourceException {
 
         Object result = null;
 
         try {
 
             result = StatementUtils.createKey(
                 null,
                 1,
                 lookupRoot(KEYS_NEXT),
                 lookup(keyName),
                 lookupRoot(KEYS_INC)
             );
         }
 
         catch (SQLException e) {
             throw new ResourceException(e);
         }
 
         return result;
 
     } // end createKey()
 
 
         // See interface for JavaDoc
     public void allocateKey() throws Exception {
 
         setStorageKey(createKey(TABLE));
 
     }
 
 
         // see interface for Javadoc
         // INSERT The name of the insert command
         // UPDATE The name of the delete command
     public void store() throws Exception {
 
         boolean isInsert = isNew();
         String token = null;
         if (isInsert) { 
             token = INSERT; 
             allocateKey();
         }
         else {
             token = UPDATE;
         }
 
         String command = lookup(token);
 
         Timestamp modified = getModified();
         if ((null==modified) || (ConvertUtils.NULL_TIMESTAMP==modified)) {
             setModified(new Timestamp(System.currentTimeMillis()));
         }
         
         // :FIXME: Way to get remoteNode
 
         int result = 0;
         try {
 
             result = StatementUtils.executeUpdate(
                 null,command,getParameters(token));
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
         setResultCode(result);
 
     }
 
 
     /**
      * Commit record to storage.
      * If storageKey is null, new storage for this object is created.
      * Otherwise, an existing object is updated.
      * @return ProcessResult with messages and this object as data
      * @exception ResourceException if data access error occurs
      @ @parameters The properties to use with operation
      *
      */
     public Object store(Object parameters) throws Exception {
 
         populate((Map) parameters);
 
         String message = null;
         if (isNew()) message = Tokens.DATA_RECORD_INSERTED;
         else message = Tokens.DATA_RECORD_UPDATED;
 
         store();
 
         ProcessResult result = new ProcessResultBase(getResult());
             result.addMessage(message);
             result.addMessage(getStorageKey());
             result.setSingleForm(true);
         return result;
     }
 
 
 // ------------------------------------------------------------------ retrieve
 
         // see interface for Javadoc
     public void retrieve() throws Exception {
 
         boolean found = findElement(this,RETRIEVE,getStorageKey());
 
         if (found) {
 
             setResult(this);
             setResultCode(1);
 
         }
         else {
             setResultCode(0);
         }
 
     }
 
         // see interface for Javadoc
     public Object retrieve(Object parameters) throws Exception {
 
         populate((Map) parameters);
         Object key = getStorageKey();
         if (null==key) {
             throw new ParameterException();
         }
 
         retrieve();
         int resultCode = getResultCode();
 
         ProcessResult result = new ProcessResultBase(this);
             if (0==resultCode) {
                 result.addMessage(Tokens.DATA_ACCESS_EMPTY);
             }
             else {
                 result.addMessage(Tokens.DATA_RECORD_RETRIEVED);
             }
             result.addMessage(key);
             result.setSingleForm(true);
 
         return result;
 
     } // end retrieve
 
 
 // -------------------------------------------------------------------- delete
 
 
         // see interface for Javadoc
     public void delete() throws Exception {
 
         retrieve();
         int result = getResultCode();
 
         if (0!=result) {
 
             try {
 
                 // Mark as deleted
                 result = StatementUtils.executeUpdate(null,
                     lookup(DELETE),getStorageKey());
             }
 
             catch (SQLException e) {
                 throw new ResourceException(e);
             }
 
             setResultCode(result);
         }
 
     }
 
 
     /**
      * [:TODO: Javadoc]
      */
     public Object delete(Object parameters) throws Exception {
 
         populate((Map) parameters);
         Object key = getStorageKey();
         if (null==key) {
             throw new ParameterException();
         }
 
         delete();
         int resultCode = getResultCode();
 
         ProcessResult result = new ProcessResultBase(this);
            if (0==resultCode) {
                 result.addMessage(Tokens.DATA_ACCESS_EMPTY);
             }
             else {
                 result.addMessage(Tokens.DATA_RECORD_DELETED);
             }
             result.addMessage(key);
             result.setSingleForm(true);
 
         return result;
 
     } // end delete
 
 
 // -------------------------------------------------------------------- recycle
 
 
         // see interface for Javadoc
     public void recycle() throws Exception {
 
         retrieve();
         int result = getResultCode();
 
         if (0!=result) {
 
             try {
 
                 // Mark as recycled
                 result = StatementUtils.executeUpdate(null,
                     lookup(RECYCLE),getStorageKey());
             }
 
             catch (SQLException e) {
                 throw new ResourceException(e);
             }
 
             setResultCode(result);
         }
 
     }
 
 
         // see interface for Javadoc
     public Object recycle(Object parameters) throws Exception {
 
         populate((Map) parameters);
         Object key = getStorageKey();
         if (null==key) {
             throw new ParameterException();
         }
 
         recycle();
         int resultCode = getResultCode();
 
         ProcessResult result = new ProcessResultBase(this);
            if (resultCode==0) {
                 result.addMessage(Tokens.DATA_ACCESS_EMPTY);
             }
             else {
                 result.addMessage(Tokens.DATA_RECORD_RECYCLED);
             }
             result.addMessage(key);
             result.setSingleForm(true);
 
         return result;
 
     } // end recycle
 
 
 // ------------------------------------------------------------------- restore
 
     /**
      * Unmark entry for deletion.
      * Returns copy of restored entry in target parameter.
      *
      * @return 0 if fails
      * @exception ResourceException if data access error occurs
      * @param target Bean to hold copy of record being unmarked
      * @param article Primary key of record to unmark
      */
     public void restore() throws Exception {
 
         int result = 0;
 
         try {
 
             result = StatementUtils.executeUpdate(null,
                 lookup(RESTORE),getStorageKey());
 
         }
         catch (SQLException e) {
             throw new ResourceException(e);
         }
 
         setResultCode(result);
 
     } // end restore
 
 
    /**
      * Update indicated entry in data storage.
      * Return confirmation message in a ProcessResult object.
      *
      * @param parameters The map or other object to use with this
      * operation
      * @throws ParameterException if article not found in parameters
      * @throws ResourceException if SQLException or other data exception
      */
     public Object restore(Object parameters) throws Exception {
 
         populate((Map) parameters);
         Object key = getStorageKey();
         if (null==key) {
             throw new ParameterException();
         }
 
         restore();
         int resultCode = getResultCode();
 
         ProcessResult result = new ProcessResultBase(this);
            if (0==resultCode) {
                 result.addMessage(Tokens.DATA_ACCESS_EMPTY);
             }
             else {
                 result.addMessage(Tokens.DATA_RECORD_RESTORED);
             }
             result.addMessage(key);
             result.setSingleForm(true);
 
         return result;
 
     } // end restore
 
 } // end StorageBeanBase