org.apache.commons.scaffold.sql
Class StorageBeanBase

java.lang.Object
  org.apache.commons.scaffold.util.ProcessBeanBase
      org.apache.commons.scaffold.sql.StorageBeanBase

All Implemented Interfaces:

ProcessBean, Storable, StorageBean

Direct Known Subclasses:

ScrollerBeanBase

public class StorageBeanBase
extends ProcessBeanBase
implements StorageBean

Implements StorageBean interface using StatementUtils and ResultSetUtils in this package. Specialty operations may be added using the same utilities.

To use this class, the developer must:

• Declare a subclass adding the properties to be stored.
• Provide in a set of standard SQL queries naming the properties to be stored as columns in the command
• Override getStorageKey to return the property used as the primary or unique key in the SQL commands.
• Override getParameters to return an array of properties as needed by object's insert and update SQL commands.
• Override getPrefix to set a unique prefix for each StorageBean class. Include the prefix in the resource file, but not in the Java code.
• Provide keys.next and keys.inc SQL commands to obtain a new primary key or override createKey to use some other method.

To specify a connection pool and load the SQL commands:

• Load the ConnectionAdaptor for your database connection pool
• Load the Properties file with your commands and pass it to the StorageBeanBase init method.

The ConnectionServlet in this package is designed to load ConnectionAdapters and resource (Properties) files.

Regarding the queries:

• 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].
• See the command.properties.sample file in this package for a starter file.
• All the subclass share the same Properties file. The prefix property lets you use the same standard query names for more than one StorageBean.
• The standard queries are insert, update, retrieve, delete, and recycle, and restore.
• The insert and update commands should use same columns in same order.
• The retrieve, delete, recycle, and restore command should use the storageKey property for selection.
• Hint: If columns cannot follow property naming conventions, rename column in command
• Hint: You can use the same object for more than one table or resultset if you like

Version:

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

Author:

Ted Husted, OK State DEQ

Field Summary

protected static Properties	commands Our command string properties.
static String	DELETE [:TODO: Javadoc] purge
static String	DOT [:TODO: Javadoc]
static String	INSERT [:TODO: Javadoc]
static String	KEYS_INC [:TODO: Javadoc]
static String	KEYS_NEXT [:TODO: Javadoc]
static String	PARAM_SEP Default separator character for list of parameters [","] (comma).
static String	PARAMS [:TODO: Javadoc]
static String	RECYCLE [:TODO: Javadoc] delete
static String	RESTORE [:TODO: Javadoc]
static String	RETRIEVE [:TODO: Javadoc]
static String	TABLE [:TODO: Javadoc]
static String	UPDATE [:TODO: Javadoc]

Fields inherited from interface org.apache.commons.scaffold.util.ProcessBean

USER_PROFILE_KEY

Constructor Summary

StorageBeanBase()

Method Summary

void	allocateKey() Obtain a new primary key for this object.
static boolean	blank(Number key) Returns true if null or zero.
protected boolean	blank(String s) Convenience method to check for null, empty String.
protected boolean	blankValue(String s) Convenience method to check for null, empty String, or "0" String.
Object	collection(Object parameters) Retrieve a collection of objects from storage.
Object	collectionResult(String command)
int	count(String command)
int	count(String command, Object parameter) Count of matching entries.
Object	createKey(String keyName) Returns next sequential key for given set of keys.
void	delete() Permenantly delete record.
Object	delete(Object parameters) [:TODO: Javadoc]
Object	element(Object command) Retrieve an element (record) from storage.
ProcessResult	elementResult(String command)
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) Convenience method that calls findCollection(Object,String,Object[]) with appropriate parameters.
protected Collection	findCollection(Object target, String command, int parameter) Convenience method that calls findCollection(Object,String,Object[]) with appropriate parameters.
protected Collection	findCollection(Object target, String command, Object parameter) Convenience method that calls findCollection(Object,String,Object[]) with appropriate parameters.
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.
void	fixModified() If timestamp is null (or ConvertUtils.NULL_TIMESTAMP), set our modified property to the current time.
Short	getMarked() Return the marked status.
Timestamp	getModified() Return the edited timestamp.
Object[]	getParameters(String command) Return the runtime parameters for the given command.
List	getParamList(String command) Return the runtime parameters for the given command.
String	getPrefix() [:TODO: Javadoc]
Object	getResult() Return the result object of an operation.
int	getResultCode() Return the result code from an operation.
Object	getStorageKey() Return this object's primary key.
static void	init(Properties _commands) Set the Properties file to be used for SQL commands.
boolean	isCurrent(Timestamp modified) Check to see if another modified timetamp matches the one for this instance.
boolean	isNew() Return whether this is a new record, or one that has already been stored.
static String	like(String parameter) [:TODO: Javadoc]
protected String	lookup(String key) Retrieve command from commands Properties
protected String	lookupRoot(String key) Retrieve command from commands Properties
void	populate(Map parameters) Populate this bean from the entries on the provided map.
void	recycle() Mark entry for deletion.
Object	recycle(Object parameters) Mark this object for deletion.
void	restore() Unmark entry for deletion.
Object	restore(Object parameters) Update indicated entry in data storage.
void	retrieve() Retrieve record from storage.
Object	retrieve(Object parameters) Retrieve this object from storage.
void	setMarked(Short marked) Set the marked status.
void	setModified(Timestamp modified) Set the edited timestamp.
void	setParameters(Object[] parameters) [:TODO: Javadoc]
void	setParamList(List paramList) [:TODO: Javadoc]
void	setPrefix(String prefix) [:TODO: Javadoc]
void	setResult(Object result) Cache the result object of an operation.
void	setResultCode(int resultCode) Set a result code for an operation.
void	setStorageKey(Object storageKey) Set this object's primary key.
void	store() Commit record to storage.
Object	store(Object parameters) Commit record to storage.
Object	update(Object parameters)
int	updateResultCode(String command)

Methods inherited from class org.apache.commons.scaffold.util.ProcessBeanBase

execute, execute, getLocale, getParameter, getRemoteAddr, getRemoteNode, getRemoteServer, setLocale, setParameter, setRemoteAddr, setRemoteNode, setRemoteServer

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.apache.commons.scaffold.util.ProcessBean

execute, execute, getLocale, getParameter, getRemoteNode, getRemoteServer, setLocale, setParameter, setRemoteNode, setRemoteServer

Field Detail

DOT

public static final String DOT

[:TODO: Javadoc]

See Also:

Constant Field Values

commands

protected static Properties commands

Our command string properties. Can be loaded from an external properties file at startup.

INSERT

public static final String INSERT

[:TODO: Javadoc]

See Also:

Constant Field Values

UPDATE

public static final String UPDATE

[:TODO: Javadoc]

See Also:

Constant Field Values

RETRIEVE

public static final String RETRIEVE

[:TODO: Javadoc]

See Also:

Constant Field Values

DELETE

public static final String DELETE

[:TODO: Javadoc] purge

See Also:

Constant Field Values

RESTORE

public static final String RESTORE

[:TODO: Javadoc]

See Also:

Constant Field Values

RECYCLE

public static final String RECYCLE

[:TODO: Javadoc] delete

See Also:

Constant Field Values

TABLE

public static final String TABLE

[:TODO: Javadoc]

See Also:

Constant Field Values

PARAMS

public static final String PARAMS

[:TODO: Javadoc]

See Also:

Constant Field Values

PARAM_SEP

public static final String PARAM_SEP

Default separator character for list of parameters [","] (comma).

See Also:

Constant Field Values

KEYS_NEXT

public static String KEYS_NEXT

[:TODO: Javadoc]

KEYS_INC

public static String KEYS_INC

[:TODO: Javadoc]

Constructor Detail

StorageBeanBase

public StorageBeanBase()

Method Detail

blank

protected boolean blank(String s)

Convenience method to check for null, empty String.

blankValue

protected boolean blankValue(String s)

Convenience method to check for null, empty String, or "0" String.

blank

public static boolean blank(Number key)

Returns true if null or zero.

like

public static final String like(String parameter)

[:TODO: Javadoc]

lookup

protected String lookup(String key)
                 throws PropertiesException

Retrieve command from commands Properties

Throws:

PropertiesException

lookupRoot

protected String lookupRoot(String key)
                     throws PropertiesException

Retrieve command from commands Properties

Throws:

PropertiesException

init

public static final void init(Properties _commands)

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.

getPrefix

public String getPrefix()

Description copied from interface: StorageBean

[:TODO: Javadoc]

Specified by:

getPrefix in interface StorageBean

setPrefix

public void setPrefix(String prefix)

Description copied from interface: StorageBean

[:TODO: Javadoc]

Specified by:

setPrefix in interface StorageBean

getParameters

public Object[] getParameters(String command)
                       throws ResourceException

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

Specified by:

getParameters in interface StorageBean

Throws:

ResourceException - if the command resource or command cannot be found.

setParameters

public void setParameters(Object[] parameters)

Description copied from interface: StorageBean

[:TODO: Javadoc]

Specified by:

setParameters in interface StorageBean

getParamList

public List getParamList(String command)
                  throws ResourceException

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

Specified by:

getParamList in interface StorageBean

Throws:

ResourceException - if the command resource or command cannot be found.

setParamList

public void setParamList(List paramList)

Description copied from interface: StorageBean

[:TODO: Javadoc]

Specified by:

setParamList in interface StorageBean

getMarked

public Short getMarked()

Return the marked status.

Returns:

the marked status

setMarked

public void setMarked(Short marked)

Set the marked status.

Parameters:

marked - The new marked status

populate

public void populate(Map parameters)
              throws Exception

Description copied from interface: StorageBean

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

Specified by:

populate in interface StorageBean

Throws:

Exception

executeUpdate

public void executeUpdate(String command)
                   throws ResourceException

Description copied from interface: StorageBean

Lookup command and execute "update" query to create a table, seed it with data, et cetera.

Specified by:

executeUpdate in interface StorageBean

Parameters:

command - Name of command to execute

Throws:

ResourceException

executeUpdateRoot

public void executeUpdateRoot(String command)
                       throws ResourceException

Description copied from interface: StorageBean

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

Specified by:

executeUpdateRoot in interface StorageBean

Parameters:

command - Name of command to execute

Throws:

ResourceException

count

public int count(String command)
          throws ResourceException

Throws:

ResourceException

count

public int count(String command,
                 Object parameter)
          throws ResourceException

Description copied from interface: StorageBean

Count of matching entries.

Specified by:

count in interface StorageBean

Parameters:

command - Name of command to execute

parameter - A parameter to be used with command, if any

Returns:

Count of matching entries

Throws:

ResourceException

findElement

public boolean findElement(Object target,
                           String command,
                           Object key)
                    throws ResourceException

Description copied from interface: StorageBean

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.

Specified by:

findElement in interface StorageBean

Parameters:

target - Object to use as factory when populating (e.g. this)

command - The name of the data access command collection

key - The primary key of the entry

Returns:

True if object is found

Throws:

ResourceException - if SQL error occurs

findCollection

public Collection findCollection(Object target,
                                 String command)
                          throws ResourceException

Convenience method that calls findCollection(Object,String,Object[]) with appropriate parameters.

Throws:

ResourceException

findCollection

protected final Collection findCollection(Object target,
                                          String command,
                                          int parameter)
                                   throws ResourceException

Convenience method that calls findCollection(Object,String,Object[]) with appropriate parameters.

Throws:

ResourceException

findCollection

protected final Collection findCollection(Object target,
                                          String command,
                                          Object parameter)
                                   throws ResourceException

Convenience method that calls findCollection(Object,String,Object[]) with appropriate parameters.

Throws:

ResourceException

findCollection

public Collection findCollection(Object target,
                                 String command,
                                 Object[] parameters)
                          throws ResourceException

Description copied from interface: StorageBean

Retrieve a collection of beans from data storage.

Specified by:

findCollection in interface StorageBean

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:

ResourceException

findByProperty

public Collection findByProperty(Object target,
                                 String property,
                                 String value)
                          throws ParameterException,
                                 PopulateException,
                                 ResourceException

Description copied from interface: StorageBean

Select entries from data storage by indexed property..

Specified by:

findByProperty in interface StorageBean

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:

ParameterException

PopulateException

ResourceException

getStorageKey

public Object getStorageKey()

Description copied from interface: Storable

Return this object's primary key.

Specified by:

getStorageKey in interface Storable

setStorageKey

public void setStorageKey(Object storageKey)

Description copied from interface: Storable

Set this object's primary key.

Specified by:

setStorageKey in interface Storable

getModified

public Timestamp getModified()

Return the edited timestamp.

Returns:

the edited timestamp.

setModified

public void setModified(Timestamp modified)

Set the edited timestamp.

Parameters:

edited - The new edited timestamp.

isCurrent

public boolean isCurrent(Timestamp modified)

Check to see if another modified timetamp matches the one for this instance. Returns true if the timestamps match.

Parameters:

edited - The new edited timestamp.

getResultCode

public int getResultCode()

Description copied from interface: Storable

Return the result code from an operation.

Specified by:

getResultCode in interface Storable

setResultCode

public void setResultCode(int resultCode)

Description copied from interface: Storable

Set a result code for an operation.

Specified by:

setResultCode in interface Storable

getResult

public Object getResult()

Description copied from interface: Storable

Return the result object of an operation.

Specified by:

getResult in interface Storable

setResult

public void setResult(Object result)

Description copied from interface: Storable

Cache the result object of an operation.

Specified by:

setResult in interface Storable

fixModified

public void fixModified()

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.

updateResultCode

public int updateResultCode(String command)
                     throws ResourceException

Throws:

ResourceException

update

public Object update(Object parameters)
              throws Exception

Throws:

Exception

elementResult

public ProcessResult elementResult(String command)
                            throws Exception

Throws:

Exception

element

public Object element(Object command)
               throws Exception

Retrieve an element (record) from storage. The element is retrieved is determined by what command has been set to the parameter property.

This signature is designed for compatibilty with the Executable interface.

Throws:

Exception

collectionResult

public Object collectionResult(String command)
                        throws Exception

Throws:

Exception

collection

public Object collection(Object parameters)
                  throws Exception

Retrieve a collection of objects from storage. The objects retrieved is determined by what command has been set to the parameter property.

This signature is designed for compatibilty with the Executable interface.

Throws:

Exception

isNew

public boolean isNew()

Description copied from interface: StorageBean

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

Specified by:

isNew in interface StorageBean

Returns:

"new" status for this object.

createKey

public Object createKey(String keyName)
                 throws ResourceException

Description copied from interface: StorageBean

Returns next sequential key for given set of keys.

Specified by:

createKey in interface StorageBean

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

allocateKey

public void allocateKey()
                 throws Exception

Description copied from interface: Storable

Obtain a new primary key for this object.

Specified by:

allocateKey in interface Storable

Throws:

Exception

store

public void store()
           throws Exception

Description copied from interface: Storable

Commit record to storage.

Specified by:

store in interface Storable

Throws:

Exception

store

public Object store(Object parameters)
             throws Exception

Commit record to storage. If storageKey is null, new storage for this object is created. Otherwise, an existing object is updated.

Specified by:

store in interface StorageBean

Returns:

ProcessResult with messages and this object as data

Throws:

ResourceException - if data access error occurs

Exception

retrieve

public void retrieve()
              throws Exception

Description copied from interface: Storable

Retrieve record from storage.

Specified by:

retrieve in interface Storable

Throws:

Exception

retrieve

public Object retrieve(Object parameters)
                throws Exception

Description copied from interface: StorageBean

Retrieve this object from storage.

This signature is designed for compatibilty with the Executable interface.

Specified by:

retrieve in interface StorageBean

Throws:

Exception

delete

public void delete()
            throws Exception

Description copied from interface: Storable

Permenantly delete record.

Specified by:

delete in interface Storable

Throws:

Exception

delete

public Object delete(Object parameters)
              throws Exception

[:TODO: Javadoc]

Specified by:

delete in interface StorageBean

Throws:

Exception

recycle

public void recycle()
             throws Exception

Description copied from interface: Storable

Mark entry for deletion.

Specified by:

recycle in interface Storable

Throws:

Exception

recycle

public Object recycle(Object parameters)
               throws Exception

Description copied from interface: StorageBean

Mark this object for deletion.

This signature is designed for compatibilty with the Executable interface.

Specified by:

recycle in interface StorageBean

Throws:

Exception

restore

public void restore()
             throws Exception

Unmark entry for deletion. Returns copy of restored entry in target parameter.

Specified by:

restore in interface Storable

Parameters:

target - Bean to hold copy of record being unmarked

article - Primary key of record to unmark

Throws:

ResourceException - if data access error occurs

Exception

restore

public Object restore(Object parameters)
               throws Exception

Update indicated entry in data storage. Return confirmation message in a ProcessResult object.

Specified by:

restore in interface StorageBean

Parameters:

parameters - The map or other object to use with this operation

Throws:

ParameterException - if article not found in parameters

ResourceException - if SQLException or other data exception

Exception