You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by hu...@apache.org on 2002/08/20 00:33:02 UTC
cvs commit: jakarta-commons-sandbox/scaffold/src/java/org/apache/commons/scaffold/util StorageBean.java Storable.java
husted 2002/08/19 15:33:02
Added: scaffold/src/java/org/apache/commons/scaffold/util
StorageBean.java Storable.java
Log:
+ StorageBeanBase: update to implement StorageBean
+ StorageBean: add interface to utils
Revision Changes Path
1.1 jakarta-commons-sandbox/scaffold/src/java/org/apache/commons/scaffold/util/StorageBean.java
Index: StorageBean.java
===================================================================
package org.apache.commons.scaffold.util;
import java.util.Collection;
import java.util.Map;
import org.apache.commons.scaffold.lang.ParameterException;
import org.apache.commons.scaffold.lang.PopulateException;
import org.apache.commons.scaffold.lang.ResourceException;
// --------------------------------------------------------------------
/**
* Describes an implementation of standard Store, Retrieve, and Delete
* operations using the command pattern.
* <P>
* Developers or Database Administrators may define data access
* commands, such as SQL queries, in an external resource.
* <P>
* 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].
* <P>
* The parameters required by each command may be specified in the
* external resource [TODO] or in the Java code (or both).
* <P>
* 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.
* <P>
* 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.
* <P>
* [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.
* <P>
* <B>StorageBean differs from other approaches</B> 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.
* <P>
* 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
* @author Ted Husted
* @author OK State DEQ
* @version $Revision: 1.1 $ $Date: 2002/08/19 22:33:01 $
*/
public interface StorageBean extends Storable,ProcessBean {
/*
NOTES:
util.OptimisticStorage
public Object getTimestamp();
public void setTimestamp(Timestamp timestamp);
public void checkEdited(boolean check);
public boolean lockResource(boolean lock);
public Object getEdited();
public Object getEditor();
public void setEditor(Object editor);
sql.JdbcStorageBean implements ProcessBean, StorageBean, OptimisticStorage (StorageBeanBase)
util.CommandStore;
util.CommandStoreProperties;
util.CommandStoreDocument;
prefix.param
prefix.command=query;query;
prefix.command.param=parm,param;param
prefix.command.success=message;message
prefix.command.failure=message;message
prefix.command.empy=message;message
util.CommandStoreDocument (XML)
<prefix id="prefix">
<param></param>
<command id="command">
<query id="#">query</query>
<param id="#">param,param</param>
</command>
</prefix>
*/
// --------------------------------------------------------------------
/**
* [:TODO: Javadoc]
*/
public String getPrefix();
/**
* [:TODO: Javadoc]
*/
public void setPrefix(String prefix);
/**
* [:TODO: Javadoc]
*/
public Object[] getParameters(String command);
/**
* [:TODO: Javadoc]
*/
public void setParameters(Object[] parameters);
/**
* Populate this bean from the entries on the
* provided map.
* The base implementation uses BeanUtils to
* efficiently populate the bean through reflection.
* @exception Subclasses can throw any Exception
*/
public void populate(Map parameters) throws Exception;
// ---------------------------------------------------- Storage 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: 1.1 $ $Date: 2002/08/19 22:33:01 $
*/
public void executeUpdate(String command)
throws ResourceException;
/**
* Retrieve object from data storage.
* <p>
* @return True if object is found
* @exception ResourceException if SQL error occurs
* @param target Object to use as factory when populating
* (e.g. this)
* @param key The primary key of the entry
* @param command The name of the data access command
* collection
*/
public boolean findElement(
Object target,
Object key,
String command) throws ResourceException;
/**
* Retrieve a collection of beans from data stoarge.
* <p>
* @return Collection with entry or empty collection
* @exception throws ResourceException if data access error occurs
* @param target Object to use as factory when populating
* (e.g. this)
* @param command Name of the data access command
* collection
* @param parameters An array of parameters to be used with command
*/
public Collection findCollection(Object target,
String command, Object[] parameters) throws ResourceException;
/**
* 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
* (e.g. this).
* @param command Name of the data access command
* collection
* @param parameter A String parameter to be used with command
*/
public Collection findCollectionLike(Object target,
String command, String parameter) throws ResourceException;
/**
* Select entries from data storage by indexed property..
* <p>
* @return Collection with record or empty Collection
* @param target Object to use as factory when populating
* collection (e.g. this)
* @param property Field to search
* @param value Term to match
* @exception Throws ParameterException if value is not a search
* term for property
* @exception Throws PopulateExeception if result cannot be set
* to target
* @exception throws PropertiesException, ResourceException on
* SQL, IO, or other data access error occurs.
*/
public Collection findByProperty(
Object target,
String property,
String value) throws ParameterException,
PopulateException, ResourceException;
// ------------------------------------------------------------- store
/**
* Returns next sequential key for given set of keys.
*
* @return An object 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 Object createKey(String keyName)
throws ResourceException;
/**
* Commit this object to storage.
* <P>
* This signature is designed for compatibilty with
* the Executable interface.
*/
public Object store(Object parameters) throws Exception;
/**
* Retrieve this object from storage.
* <P>
* This signature is designed for compatibilty with
* the Executable interface.
*/
public Object retrieve(Object parameters) throws Exception;
/**
* Mark this object for deletion.
* <P>
* This signature is designed for compatibilty with
* the Executable interface.
*/
public Object recycle(Object parameters) throws Exception;
/**
* Unmake this object for deletion.
* <P>
* This signature is designed for compatibilty with
* the Executable interface.
*/
public Object restore(Object parameters) throws Exception;
/**
* Permanently delete this object from data storage.
* <P>
* This signature is designed for compatibilty with
* the Executable interface.
*/
public Object delete(Object parameters) throws Exception;
} // end StorageBean
/*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this Collection of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this Collection of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Tomcat", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
*/
1.1 jakarta-commons-sandbox/scaffold/src/java/org/apache/commons/scaffold/util/Storable.java
Index: Storable.java
===================================================================
package org.apache.commons.scaffold.util;
import java.util.Map;
/**
* Simple interface to describe public methods on a
* data access object.
*
* @author Ted Husted
* @version $Revision: 1.1 $ $Date: 2002/08/19 22:33:01 $
*/
public interface Storable {
/**
* Commit record to storage.
*/
public void store() throws Exception;
/**
* Retrieve record from storage.
*/
public void retrieve() throws Exception;
/**
* Permenantly delete record.
*/
public void delete() throws Exception;
/**
* Mark entry for deletion.
*/
public void recycle() throws Exception;
/**
* Unmark entry for deletion.
*/
public void restore() throws Exception;
/**
* Return this object's primary key.
*/
public Object getPrimaryKey();
/**
* Set this object's primary key.
*/
public void setPrimaryKey(Object key);
/**
* Obtain a new primary key for this object.
*/
public void allocateKey() throws Exception;
/**
* Cache the result object of an operation.
*/
public void setResult(Object result);
/**
* Return the result object of an operation.
*/
public Object getResult();
/**
* Set a result code for an operation.
*/
public void setResultCode(int resultCode);
/**
* Return the result code from an operation.
*/
public int getResultCode();
/**
* Populate this object from a Map.
*/
public void populate(Map parameters) throws Exception;
}
/*
* ====================================================================
*
* The Apache Software License, Version 1.1
*
* Copyright (c) 2001 The Apache Software Foundation. All rights
* reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* 1. Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* 2. Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
* any, must include the following acknowlegement:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
* Alternately, this acknowlegement may appear in the software itself,
* if and wherever such third-party acknowlegements normally appear.
*
* 4. The names "The Jakarta Project", "Scaffold", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
* from this software without prior written permission. For written
* permission, please contact apache@apache.org.
*
* 5. Products derived from this software may not be called "Apache"
* nor may "Apache" appear in their names without prior written
* permission of the Apache Group.
*
* THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
* WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
* OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
* DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
* ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
* ====================================================================
*
* This software consists of voluntary contributions made by many
* individuals on behalf of the Apache Software Foundation. For more
* information on the Apache Software Foundation, please see
* <http://www.apache.org/>.
*
*/
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>