/*

  * 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