org.apache.commons.scaffold.util
Interface StorageBean

All Superinterfaces:
ProcessBean, Storable
All Known Implementing Classes:
ScrollerBeanBase, StorageBeanBase

public interface StorageBean
extends Storable, ProcessBean

Describes an implementation of standard Store, Retrieve, and Delete operations using the command pattern.

Developers or Database Administrators may define data access commands, such as SQL queries, in an external resource.

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].

The parameters required by each command may be specified in the external resource [TODO] or in the Java code (or both).

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.

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.

[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.

StorageBean differs from other approaches 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.

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

Version:
$Revision: 155464 $ $Date: 2005-02-26 13:26:54 +0000 (Sat, 26 Feb 2005) $
Author:
Ted Husted, OK State DEQ, WXXI Public Broadcasting Council

Field Summary
 
Fields inherited from interface org.apache.commons.scaffold.util.ProcessBean
USER_PROFILE_KEY
 
Method Summary
 int count(String command, Object parameter)
          Count of matching entries.
 Object createKey(String keyName)
          Returns next sequential key for given set of keys.
 Object delete(Object parameters)
          Permanently delete this object from data storage.
 void executeUpdate(String command)
          Lookup command and execute "update" query to create a table, seed it with data, et cetera.
 void executeUpdateRoot(String command)
          Lookup command (sans prefix) and execute "update" query to create a table, seed it with data, et cetera.
 Collection findByProperty(Object target, String property, String value)
          Select entries from data storage by indexed property..
 Collection findCollection(Object target, String command, Object[] parameters)
          Retrieve a collection of beans from data storage.
 boolean findElement(Object target, String command, Object key)
          Retrieve object from data storage.
 Object[] getParameters(String command)
          [:TODO: Javadoc]
 List getParamList(String command)
          [:TODO: Javadoc]
 String getPrefix()
          [:TODO: Javadoc]
 boolean isNew()
          Return whether this is a new record, or one that has already been stored.
 void populate(Map parameters)
          Populate this bean from the entries on the provided map.
 Object recycle(Object parameters)
          Mark this object for deletion.
 Object restore(Object parameters)
          Unmake this object for deletion.
 Object retrieve(Object parameters)
          Retrieve this object from storage.
 void setParameters(Object[] parameters)
          [:TODO: Javadoc]
 void setParamList(List parameters)
          [:TODO: Javadoc]
 void setPrefix(String prefix)
          [:TODO: Javadoc]
 Object store(Object parameters)
          Commit this object to storage.
 
Methods inherited from interface org.apache.commons.scaffold.util.Storable
allocateKey, delete, getResult, getResultCode, getStorageKey, recycle, restore, retrieve, setResult, setResultCode, setStorageKey, store
 
Methods inherited from interface org.apache.commons.scaffold.util.ProcessBean
execute, execute, getLocale, getParameter, getRemoteNode, getRemoteServer, setLocale, setParameter, setRemoteNode, setRemoteServer
 

Method Detail

getPrefix

String getPrefix()
[:TODO: Javadoc]


setPrefix

void setPrefix(String prefix)
[:TODO: Javadoc]


getParameters

Object[] getParameters(String command)
                       throws ResourceException
[:TODO: Javadoc]

Throws:
ResourceException

setParameters

void setParameters(Object[] parameters)
[:TODO: Javadoc]


getParamList

List getParamList(String command)
                  throws ResourceException
[:TODO: Javadoc]

Throws:
ResourceException

setParamList

void setParamList(List parameters)
[:TODO: Javadoc]


populate

void populate(Map parameters)
              throws Exception
Populate this bean from the entries on the provided map. The base implementation uses BeanUtils to efficiently populate the bean through reflection.

Specified by:
populate in interface Storable
Throws:
Subclasses - can throw any Exception
Exception

count

int count(String command,
          Object parameter)
          throws ResourceException
Count of matching entries.

Parameters:
command - Name of command to execute
parameter - A parameter to be used with command, if any
Returns:
Count of matching entries
Throws:
Resource - exception if data access error occurs
ResourceException

executeUpdate

void executeUpdate(String command)
                   throws ResourceException
Lookup command and execute "update" query to create a table, seed it with data, et cetera.

Parameters:
command - Name of command to execute
Throws:
Resource - exception if data access error occurs
ResourceException

executeUpdateRoot

void executeUpdateRoot(String command)
                       throws ResourceException
Lookup command (sans prefix) and execute "update" query to create a table, seed it with data, et cetera.

Parameters:
command - Name of command to execute
Throws:
Resource - exception if data access error occurs
ResourceException

findElement

boolean findElement(Object target,
                    String command,
                    Object key)
                    throws ResourceException
Retrieve object from data storage.

NOTE that the precursor to this inteface, the AccessBase 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.

Parameters:
target - Object to use as factory when populating (e.g. this)
key - The primary key of the entry
command - The name of the data access command collection
Returns:
True if object is found
Throws:
ResourceException - if SQL error occurs

findCollection

Collection findCollection(Object target,
                          String command,
                          Object[] parameters)
                          throws ResourceException
Retrieve a collection of beans from data storage.

Parameters:
target - Object to use as factory when populating (e.g. this)
command - Name of the data access command collection
parameters - An array of parameters to be used with command
Returns:
Collection with entry or empty collection
Throws:
throws - ResourceException if data access error occurs
ResourceException

findByProperty

Collection findByProperty(Object target,
                          String property,
                          String value)
                          throws ParameterException,
                                 PopulateException,
                                 ResourceException
Select entries from data storage by indexed property..

Parameters:
target - Object to use as factory when populating collection (e.g. this)
property - Field to search
value - Term to match
Returns:
Collection with record or empty Collection
Throws:
Throws - ParameterException if value is not a search term for property
Throws - PopulateExeception if result cannot be set to target
throws - PropertiesException, ResourceException on SQL, IO, or other data access error occurs.
ParameterException
PopulateException
ResourceException

isNew

boolean isNew()
Return whether this is a new record, or one that has already been stored.

Returns:
"new" status for this object.

createKey

Object createKey(String keyName)
                 throws ResourceException
Returns next sequential key for given set of keys.

Parameters:
keyName - The name of the key set to use to generate the key
Returns:
An object representing the allocated key
Throws:
ResourceException - if data access error occurs

store

Object store(Object parameters)
             throws Exception
Commit this object to storage.

This signature is designed for compatibilty with the Executable interface.

Throws:
Exception

retrieve

Object retrieve(Object parameters)
                throws Exception
Retrieve this object from storage.

This signature is designed for compatibilty with the Executable interface.

Throws:
Exception

recycle

Object recycle(Object parameters)
               throws Exception
Mark this object for deletion.

This signature is designed for compatibilty with the Executable interface.

Throws:
Exception

restore

Object restore(Object parameters)
               throws Exception
Unmake this object for deletion.

This signature is designed for compatibilty with the Executable interface.

Throws:
Exception

delete

Object delete(Object parameters)
              throws Exception
Permanently delete this object from data storage.

This signature is designed for compatibilty with the Executable interface.

Throws:
Exception


Copyright © 2001-2010 The Apache Software Foundation. All Rights Reserved.