/*

  * 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.util.Collection;

 import java.util.Properties;

 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.lucene.SearchUtils;

 import org.apache.commons.scaffold.lucene.Engine;

 import org.apache.commons.scaffold.sql.StatementUtils;

 /**

  * Common data access methods.

  *

  * @author Ted Husted

  * @author OK State DEQ

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

  * @deprecated Use StorageBean instead.

  */

 public class AccessBase {

     /**

      * [:TODO: Javadoc]

      */

     public static String KEYS_NEXT = "keys.next";

     /**

      * [:TODO: Javadoc]

      */

     public static String KEYS_INC = "keys.inc";

 // ----------------------------------------------------------- Commands

     /**

      * Our command string properties.

      * Can be loaded from an external properties file at startup.

      */

     private static Properties commands;

     /**

      * Retrieve command from <code>commands</code> Properties for

      * <code>key</code>.

      *

      * @fixme Could use a merge feature to reuse common substrings,

      * like table names ["SELECT ${searchFields} FROM ${articleTable}"]

      */

     public static final String getCommand(String key)

             throws PropertiesException {

             // MissingResourceException ?

         if (null==commands) throw new PropertiesException();

         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);

         }

     }

 // ================================================================ API

 // ----------------------------------------------------- Create Methods

     /**

      * 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

      * @author Ted Husted

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

      */

     public static final void executeUpdate(String command)

             throws ResourceException {

         try {

              int result = StatementUtils.executeUpdate(

                  null,getCommand(command));

         }

         catch (SQLException e) {

             throw new ResourceException(e);

         }

     } // end createTables()

     /**

      * Returns next sequential key for given set of keys.

      * Expects KEYS_NET nd KEYS_INC commands to be defined.

      *

      * @return A String 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 static final Integer createKey(String keyName)

             throws ResourceException {

         Integer result = null;

         try {

                 // createKey is syncronized

             result = (Integer) StatementUtils.createKey(

                 null,

                 1,

                 getCommand(KEYS_NEXT),

                 getCommand(keyName),

                 getCommand(KEYS_INC)

             );

         }

         catch (SQLException e) {

             throw new ResourceException(e);

         }

         return result;

    } // end createKey()

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

     /**

      * Retrieve entry from data storage.

      * <P>

      * <B>NOTE</B> that the key and command parameters to this utility

      * should have been swapped for consistency with other

      * methods in this package. But since this class is deprecated,

      * a fix has not been made.

      * @return Collection with record or empty collection

      * @exception ResourceException if SQL error occurs

      * @param key The primary key of the entry

      * @param target Bean to hold copy of entry being retrieved

      * @param command The name of the data access command

      * collection

      */

     public static boolean findElement(

             Object target,

             Object key,

             String command) throws ResourceException {

         boolean found = false;

         try {

             found = StatementUtils.getElement(null,target,

                 getCommand(command),key);

         }

         catch (SQLException e) {

             throw new ResourceException(e);

         }

         return found;

    } // end findElement

     /**

      * Retrieve a collection of beans from data stoarge.

      * <p>

      * @return Collection with entry or empty collection

      * @exception throws PropertiesException, ResourceException

      * if data access error occurs

      * @param target Object to use as factory when populating

      * @param command Name of the data access command

      * collection

      */

     public static final Collection findCollection(Object target,

         String command) throws ResourceException {

         try {

             return StatementUtils.getCollection(null,

                 target,getCommand(command));

         }

         catch (SQLException e) {

             throw new ResourceException(e);

         }

     } // end findCollection

     /**

      * Retrieve a collection of beans from data stoarge.

      * <p>

      * @return Collection with entry or empty collection

      * @exception throws PropertiesException, ResourceException

      * if data access error occurs

      * @param target Object to use as factory when populating

      * @param command Name of the data access command

      * collection

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

      */

     public static final Collection findCollection(Object target,

         String command, Object[] parameters) throws ResourceException {

         try {

             return StatementUtils.getCollection(null,

                 target,getCommand(command),parameters);

         }

         catch (SQLException e) {

             throw new ResourceException(e);

         }

     } // end findCollection

     /**

      * Retrieve a collection of beans from data stoarge.

      * <p>

      * @return Collection with entry or empty collection

      * @exception throws PropertiesException, ResourceException

      * if data access error occurs

      * @param target Object to use as factory when populating

      * @param command Name of the data access command

      * collection

      * @param parameter A String parameter to be used with command

      */

     public static final Collection findCollection(Object target,

         String command, Object parameter) throws ResourceException {

         try {

             return StatementUtils.getCollection(null,

                 target,getCommand(command),parameter);

         }

         catch (SQLException e) {

             throw new ResourceException(e);

         }

     } // end findCollection

     /**

      * Retrieve a collection of beans from data stoarge.

      * <p>

      * @return Collection with entry or empty collection

      * @exception throws PropertiesException, ResourceException

      * if data access error occurs

      * @param target Object to use as factory when populating

      * @param command Name of the data access command

      * collection

      * @param parameter An int parameter to be used with command

      */

     public static final Collection findCollection(Object target,

         String command, int parameter) throws ResourceException {

         return findCollection(target,command,new Integer(parameter));

     } // end findCollection

     /**

      * Retrieve a collection of beans from data stoarge.

      * <p>

      * @return Collection with entry or empty collection

      * @exception throws PropertiesException, ResourceException

      * if data access error occurs

      * @param target Object to use as factory when populating

      * @param command Name of the data access command

      * collection

      * @param parameter A String parameter to be used with command

      */

     public static final Collection findCollectionLike(Object target,

         String command, String parameter) throws ResourceException {

         try {

             return StatementUtils.getCollection(null,

                 target,getCommand(command),StatementUtils.like(parameter));

         }

         catch (SQLException e) {

             throw new ResourceException(e);

         }

     } // end findCollectionLike

     /**

      * Select entries from data storage by indexed property..

      * <p>

      * @return Collection with record or empty Collection

      * @param value Term to match

      * @param property Field to search

      * @param target Object to use as factory when populating

      * collection

      * @exception Throws ParameterException if value is not a search

      * term for property

      * @exception Throws PopulateExecption if result cannot be set to

      * target

      * @exception throws PropertiesException, ResourceException is SQL, IO, or other

      * data access error occurs.

      */

     public static final 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

     /**

      * Commit record to storage.

      * If create is true, entry is created.

      * Otherwise, an existing entry is updated.

      * @return 0 if fails

      * @exception ResourceException if SQL error occurs

      * @param insert True to insert, false to update.

      * @insert The name of the insert command

      * @update The name of the delete command

      @ @parameters The parameters to use with either command

      *

      */

     public static final int store (

             boolean isInsert,

             String insert,

             String update,

             Object[] parameters) throws ResourceException {

         String command = null;

         if (isInsert) {

             command = getCommand(insert);

         }

         else {

             command = getCommand(update);

         }

         int result = 0;

         try {

             result = StatementUtils.executeUpdate(null,command,parameters);

         }

         catch (SQLException e) {

             throw new ResourceException(e);

         }

         return result;

     } // end store

     /**

      * Mark entry for deletion.

      * Returns copy of entry before update in target parameter.

      *

      * @return 0 if fails

      * @exception ResourceException if SQL or other data-access error occurs

      * @exception runtime Null Pointer Exception if either parameter is null

      * @param target Bean to hold copy of record being marked

      * @param article Primary key of record to mark

      */

     public static final int delete(Object target, Integer key, String command)

             throws ResourceException {

         int result = 0;

         try {

             // Mark as deleted

             result = StatementUtils.executeUpdate(null,

                 getCommand(command),key);

         }

         catch (SQLException e) {

             throw new ResourceException(e);

         }

         return result;

     } // end delete

     /**

      * 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 static final int restore(Object target, Integer key, String command)

             throws ResourceException {

         int result = 0;

         try {

             result = StatementUtils.executeUpdate(null,

                 getCommand(command),key);

         }

         catch (SQLException e) {

             throw new ResourceException(e);

         }

         return result;

     } // end restore

 } // end Access