net.sourceforge.pbeans
Class Store

java.lang.Object
  net.sourceforge.pbeans.Store

public class Store
extends java.lang.Object

A Store instance provides mapping of Java objects (beans) to relational database tables and vice-versa. It attempts to do this in a manner that is comparable to an orthogonal and transitive persistence layer.

Store should be instantiated only once per database by a Java application.

Store deals with JavaBeans that are tagged with PersistentClass. A store will first know about a persistent object if the object is registered for the first time, inserted, or obtained from Store via one of its select methods.

Insertion

A new object, previously unkown by Store, may be inserted by invoking the insert method. If the same object or another object with a matching unique index was already inserted, the method will throw DuplicateEntryException. This is an example of insertion:

      User user = new User();
      user.setUserName ("joe");
      try {
          store.insert (user);
      } catch (DuplicateEntryException dee) {
          // Error: User already exists.
      }

 

Unique indexes may be defined by specifying the indexes value of the PersistentClass annotation.

Updates

Changes to a persistent object already inserted should be done by calling the save method, for example, as follows:

      try {
         store.save (user);
      } catch (DuplicateEntryException dee) {
         // Error: Can't change because of unique-index conflict.
      }
 
 

The save method may throw DuplicateEntryException if the change conflicts with another persistent object's unique index.

Queries

There are several select and selectSingle methods which may be used to query previously inserted persistent objects by class. For example, to obtain an object by providing a property value, use code similar to the following:

 
      User user = (User) store.selectSingle(User.class, "userName", "joe");
    
 

Other select methods return a ResultsIterator instance, which works similar to a regular Iterator. A ResultsIterator instance should be closed, however, when the caller is done with it.

 
      ResultsIterator ri = store.select(User.class, "SELECT * FROM User", new Object[0]);
      try {
          while(ri.hasNext()) {
              User user = (User) ri.next();
              System.out.println("User: " + user.getUserName());
          }
      } finally {
          ri.close();
      }
 

Constructor Summary

Store(javax.sql.DataSource dataSource)
Constructs a Store instance.

Store(javax.sql.DataSource dataSource, DatabaseFactory dbf, java.lang.ClassLoader defaultClassLoader)
Constructs a Store instance.

Store(javax.sql.DataSource dataSource, int maxConnections, int connectionTimeout)
Constructs a Store instance.

Store(javax.sql.DataSource dataSource, int maxConnections, int connectionTimeout, java.lang.ClassLoader classLoader)

Method Summary

void	beginTransaction() Begins a database transaction with isolation level TRANSACTION_READ_COMMITTED.
void	beginTransaction(int transactionIsolationLevel) Begins a database transaction with a given transaction isolation level.
boolean	delete(java.lang.Class beanClass, java.util.Map values) Deletes all database records that match the given criteria.
void	delete(java.lang.Object persObject) Removes a persistent object from storage.
void	delete(java.lang.Object persObject, boolean forget) Deletes an object's database representation.
void	endTransaction() Ends a transaction previously begun by a call to beginTransaction().
void	endTransaction(boolean rollback) Ends a transaction previously begun by a call to beginTransaction().
java.lang.Object	get(java.lang.String name) Gets a persistent object previously associated with a name using the put() method.
java.lang.Object	getCachedObject(GlobalPersistentID globalID) Gets a persistent object from main memory, if available.
protected java.lang.String	getFieldName(StoreInfo sinfo, java.lang.String propertyName) Gets the field name into which a JavaBean property name is mapped.
GlobalPersistentID	getGlobalPersistentID(java.lang.Object persObject)
int	getMaxColumnNameLength() Gets the maximum column name length supported by the underlying database.
int	getMaxTableNameLength()
int	getMemoryObjectCount() Gets the number of objects currently in main memory maps.
java.lang.Object	getObject(GlobalPersistentID globalID) Gets a persistent object given its unique ID.
java.lang.Object	getObject(GlobalPersistentID globalID, java.lang.ClassLoader classLoader) Gets a persistent object given its unique ID.
java.lang.Object	getObject(PersistentID objectID, java.lang.Class beanClass) Obtains an object given a PersistentID and a class reference.
PersistentID	getPersistentID(java.lang.Object persObject) Gets the PersistentID associated with a Persistent object.
protected PersistentMap<java.lang.String,java.lang.Object>	getRootMap() Gets the PersistentMap instance used by the get() and put() methods in this class.
StoreInfo	getStoreInfo(java.lang.Class beanClass) Gets a StoreInfo instance corresponding to a persistent class.
protected java.lang.String	getTableName(java.lang.Class beanClass) Gets the table name used for a given class.
void	insert(java.lang.Object persObject) Attempts to insert a new persistent object in its underlying database table.
boolean	inTransaction() Determines whether the current thread execution point is inside a transaction started by beginTransaction().
static boolean	isPersistable(java.lang.Class beanClass) Determines if a class is understood by Store as one whose instances can be persisted in a database.
void	put(java.lang.String name, java.lang.Object obj) Associates a persistent object with a name.
void	register(java.lang.Object persObject) Informs this Store about a new persistent object.
void	relinquishLock() Relinquishes a lock previously obtained with requestLock(Class, String, int).
void	relinquishLock(boolean rollback) Relinquishes a lock previously obtained with requestLock(Class, String, int).
void	reload(java.lang.Object persObject) Repopulates Persistent object properties with stored data.
void	remove(java.lang.String name) Removes an association of a name with a persistent object.
void	requestLock(java.lang.Class beanClass, java.lang.String dataName) Requests a lock with a transaction isolation level of TRANSACTION_READ_COMMITTED.
void	requestLock(java.lang.Class beanClass, java.lang.String dataName, int transactionIsolationLevel) Requests entrance to a critical section of code for both Java threads and database alterations.
void	save(java.lang.Object persObject) Updates the database record previously created for a Persistent object.
void	save(java.lang.Object persObject, boolean force, boolean reload) Saves an object in the database.
ResultsIterator	select(java.lang.Class inbeanClass) Gets an iterator of all stored instances of the given class.
ResultsIterator	select(java.lang.Class beanClass, java.util.Map values) Finds all stored instances matching the property values given.
ResultsIterator	select(java.lang.Class beanClass, java.util.Map values, java.lang.String orderByProperty, boolean descending, java.lang.Integer limit) Finds stored instances matching the property values given.
ResultsIterator	select(java.lang.Class beanClass, java.util.Map propertyValues, java.lang.String orderByProperty, boolean descending, java.lang.Integer limit, BeanFactory beanFactory) Finds stored instances matching the property values given.
ResultsIterator	select(java.lang.Class beanClass, java.lang.String sqlQuery, java.lang.Object[] parameters) General-purpose method for arbitrary SQL queries that return an iterator of beans.
ResultsIterator	select(java.lang.Class beanClass, java.lang.String sqlQuery, java.lang.Object[] parameters, BeanFactory beanFactory) General-purpose method for arbitrary SQL queries that return an iterator of beans.
ResultsIterator	selectParts(java.lang.Object containerBean, java.lang.Class partbeanClass, java.lang.String linkPropertyInPart) Gets an iterator of objects of the given class which have a "foreign key" property value equal to the containerBean given.
ResultsIterator	selectParts(PersistentID containerBeanID, java.lang.Class linkClass, java.lang.Class partClass, java.lang.String propertyLinkingContainer, java.lang.String propertyLinkingPart) Queries beans linked to a given bean by means of an intermediate class.
ResultsIterator	selectParts(PersistentID containerBeanID, java.lang.Class partbeanClass, java.lang.String linkPropertyInPart) Gets an iterator of objects of the given class which have a "foreign key" property value equal to the containerBeanID given.
java.lang.Object	selectSingle(java.lang.Class beanClass, java.util.Map values) Finds a stored instance matching the property values given.
java.lang.Object	selectSingle(java.lang.Class beanClass, java.util.Map values, java.lang.String orderBy, boolean descending) Finds a stored instance matching the property values given.
java.lang.Object	selectSingle(java.lang.Class beanClass, java.lang.String propertyName, java.lang.Object propertyValue) Finds a stored instance with the property value given.
boolean	update(java.lang.Class beanClass, java.lang.String sqlStatement, java.lang.String[] propertyNames, java.lang.Object[] parameters) Executes an arbitrary database update.

Methods inherited from class java.lang.Object

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

Constructor Detail

Store

public Store(javax.sql.DataSource dataSource,
             DatabaseFactory dbf,
             java.lang.ClassLoader defaultClassLoader)
      throws StoreException

Constructs a Store instance.

Parameters:

dataSource - A DataSource instance, which may be obtained from a JDBC 2.0 provider, or by instantiating net.sourceforge.pbeans.data.GenericDataSource.

dbf - An implementation of DatabaseFactory. This may be an instance of DefaultDatabaseFactory.

defaultClassLoader - The class loader the Store instance will use to load classes by default.

Throws:

StoreException

See Also:

GenericDataSource

Store

public Store(javax.sql.DataSource dataSource)
      throws StoreException

Constructs a Store instance. Internally it creates an instance of DefaultDatabaseFactory.

Parameters:

dataSource - A DataSource instance, which may be obtained from a JDBC 2.0 provider, or by instantiating net.sourceforge.pbeans.data.GenericDataSource.

Throws:

StoreException

See Also:

GenericDataSource

Store

public Store(javax.sql.DataSource dataSource,
             int maxConnections,
             int connectionTimeout)
      throws StoreException

Constructs a Store instance. Internally it creates an instance of DefaultDatabaseFactory.

Parameters:

dataSource - A DataSource instance, which may be obtained from a JDBC 2.0 provider, or by instantiating net.sourceforge.pbeans.data.GenericDataSource.

maxConnections - The maximum number of connections to be kept in the pBeans connection pool.

connectionTimeout - The maximum length of time (in milliseconds) an inactive JDBC connection is kept in the pBeans connection pool. The default is about one hour.

Throws:

StoreException

See Also:

GenericDataSource

Store

public Store(javax.sql.DataSource dataSource,
             int maxConnections,
             int connectionTimeout,
             java.lang.ClassLoader classLoader)
      throws StoreException

Throws:

StoreException

Method Detail

getMaxColumnNameLength

public int getMaxColumnNameLength()

Gets the maximum column name length supported by the underlying database.

getMaxTableNameLength

public int getMaxTableNameLength()

getFieldName

protected java.lang.String getFieldName(StoreInfo sinfo,
                                        java.lang.String propertyName)
                                 throws StoreException

Gets the field name into which a JavaBean property name is mapped.

Throws:

StoreException

getStoreInfo

public StoreInfo getStoreInfo(java.lang.Class beanClass)
                       throws StoreException

Gets a StoreInfo instance corresponding to a persistent class. Normally, an instance of net.sourceforge.pbeans.DefaultStoreInfo is used, unless another class is provided with the same name as that of beanClass but suffixed with "_StoreInfo" (similar to BeanInfo for JavaBeans.) Implementing StoreInfo gives more control over which properties are persistent, indexes, etc.

Throws:

StoreException

getMemoryObjectCount

public int getMemoryObjectCount()

Gets the number of objects currently in main memory maps.

put

public void put(java.lang.String name,
                java.lang.Object obj)
         throws StoreException

Associates a persistent object with a name.

Throws:

StoreException

See Also:

get(java.lang.String)

get

public java.lang.Object get(java.lang.String name)
                     throws StoreException

Gets a persistent object previously associated with a name using the put() method.

Throws:

StoreException

See Also:

put(java.lang.String, java.lang.Object)

remove

public void remove(java.lang.String name)
            throws StoreException

Removes an association of a name with a persistent object.

Throws:

StoreException

See Also:

put(java.lang.String, java.lang.Object), get(java.lang.String)

getRootMap

protected PersistentMap<java.lang.String,java.lang.Object> getRootMap()
                                                               throws StoreException

Gets the PersistentMap instance used by the get() and put() methods in this class.

Throws:

StoreException

getObject

public java.lang.Object getObject(GlobalPersistentID globalID)
                           throws StoreException

Gets a persistent object given its unique ID. The object may already be available in memory or it may be retrieved from secondary storage.

Throws:

StoreException

See Also:

getObject(GlobalPersistentID, ClassLoader), getObject(PersistentID, Class)

getObject

public java.lang.Object getObject(GlobalPersistentID globalID,
                                  java.lang.ClassLoader classLoader)
                           throws StoreException

Gets a persistent object given its unique ID. The object may already be available in memory or it may be retrieved from secondary storage. If the object is retrieved from secondary storage, the class loader provided is used to find its class.

Throws:

StoreException

See Also:

getObject(PersistentID,java.lang.Class)

getObject

public java.lang.Object getObject(PersistentID objectID,
                                  java.lang.Class beanClass)
                           throws StoreException

Obtains an object given a PersistentID and a class reference.

Parameters:

objectID - The ID of the desired object.

beanClass - The beanClass of the desired object.

Returns:

A Persistent object or null if an object of the given class and PersistentID does not exist.

Throws:

StoreException

getCachedObject

public java.lang.Object getCachedObject(GlobalPersistentID globalID)

Gets a persistent object from main memory, if available. This method will not load the object from secondary storage.

getTableName

protected java.lang.String getTableName(java.lang.Class beanClass)
                                 throws StoreException

Gets the table name used for a given class.

Throws:

StoreException

reload

public void reload(java.lang.Object persObject)
            throws StoreException

Repopulates Persistent object properties with stored data. It should only be used if changes have been made to the database outside of this API.

Throws:

StoreException

save

public void save(java.lang.Object persObject)
          throws StoreException

Updates the database record previously created for a Persistent object. The record is actually updated only if property changes have occurred since the last save or insertion. This method will not work on Persistent objects not previously inserted, registered or obtained from this Store, or if the record had previously been deleted.

Throws:

StoreException

save

public void save(java.lang.Object persObject,
                 boolean force,
                 boolean reload)
          throws StoreException

Saves an object in the database.

Parameters:

persObject - A bean.

force - Whether saving should be forced even if the object has not changed since the last time it was saved.

reload - If true, the record is reloaded from secondary storage if the save operation fails for any reason.

Throws:

StoreException

insert

public void insert(java.lang.Object persObject)
            throws StoreException

Attempts to insert a new persistent object in its underlying database table. This method should only be invoked on new objects unknown to this Store or objects that have been previously deleted. Persistent objects referred to by persObject should normally be obtained from Store prior to insertion, unless they are objects also known to be insertable. The object is also cached in main memory (using a weak reference cache) until it is garbage collected, so subsequent invocations to register passing persObject will have no effect.

Throws:

DuplicateEntryException - Thrown if the object was already inserted or another object with equal unique-index values already exists in persistent storage. This applies to the object being inserted and to any other objects referred to by persObject, directly and indirectly, which are not already known to Store.

StoreException

See Also:

StoreInfo, Index

register

public void register(java.lang.Object persObject)
              throws StoreException

Informs this Store about a new persistent object. If the object is already known by this Store, nothing is done. If the object is determined to be new, it is cached in main memory (using a weak reference cache) and inserted in data storage.

Throws:

DuplicateEntryException - Thrown if the object was not previously known by this Store instance and a record already exists with equal unique-index values.

StoreException

delete

public void delete(java.lang.Object persObject)
            throws StoreException

Removes a persistent object from storage. Any subsequent attempts to save the object will fail, unless insert is invoked first.

Throws:

StoreException

delete

public void delete(java.lang.Object persObject,
                   boolean forget)
            throws StoreException

Deletes an object's database representation.

Parameters:

persObject -

forget - If this parameter is true, the object will also be removed for Store's memory data structures. This means that the object can be saved again. If forget is false, save operations will have no effect on the deleted object.

Throws:

StoreException

getPersistentID

public PersistentID getPersistentID(java.lang.Object persObject)
                             throws StoreException

Gets the PersistentID associated with a Persistent object. If the object given was not previously obtained from Store or registered with Store, a new persistent record is created.

Throws:

StoreException

getGlobalPersistentID

public GlobalPersistentID getGlobalPersistentID(java.lang.Object persObject)
                                         throws StoreException

Throws:

StoreException

beginTransaction

public void beginTransaction()
                      throws StoreException

Begins a database transaction with isolation level TRANSACTION_READ_COMMITTED.

Throws:

StoreException

See Also:

beginTransaction(int), requestLock(Class, String, int)

beginTransaction

public void beginTransaction(int transactionIsolationLevel)
                      throws StoreException

Begins a database transaction with a given transaction isolation level. A transaction must be ended in the same thread with a call to endTransaction(). A try-finally block is recommended to achieve this, as follows

 store.beginTransaction(Connection.TRANSACTION_READ_COMMITTED);
 try {
     // store operations here
 } finally {
     store.endTransaction();
 }
 

Transactions only apply to the database. They do not prevent concurrent modification of Java objects, which can be shared by different threads when this Store class is used.

Nested transactions are disallowed.

Parameters:

transactionIsolationLevel - A transaction isolation level. See constants in Connection.

Throws:

StoreException

See Also:

requestLock(java.lang.Class, java.lang.String)

endTransaction

public void endTransaction()
                    throws StoreException

Ends a transaction previously begun by a call to beginTransaction().

Throws:

StoreException

endTransaction

public void endTransaction(boolean rollback)
                    throws StoreException

Ends a transaction previously begun by a call to beginTransaction().

Parameters:

rollback - Whether the transaction should be rolled back.

Throws:

StoreException

inTransaction

public boolean inTransaction()

Determines whether the current thread execution point is inside a transaction started by beginTransaction().

requestLock

public void requestLock(java.lang.Class beanClass,
                        java.lang.String dataName)
                 throws StoreException,
                        java.lang.InterruptedException

Requests a lock with a transaction isolation level of TRANSACTION_READ_COMMITTED.

Throws:

StoreException

java.lang.InterruptedException

See Also:

requestLock(Class, String, int)

requestLock

public void requestLock(java.lang.Class beanClass,
                        java.lang.String dataName,
                        int transactionIsolationLevel)
                 throws StoreException,
                        java.lang.InterruptedException

Requests entrance to a critical section of code for both Java threads and database alterations. In other words, it obtains a thread lock and begins a database transaction. This is useful in pBeans given that object instances looked up from Store are often shared between threads. Database transactions ensure isolation at the database level, but they do not prevent concurrent modifications of beans in memory.

If another thread owns the lock identified by the given class and data name, this call will block until the other thread relinquishes its lock.

A call to requestLock must be matched by a call to relinquishLock(). A try-finally block is recommended, as follows.

 store.requestLock(User.class, "johnsmith");
 try {
     User user = store.selectSingle(User.class, "username", "johnsmith");
     user.setBalance(user.getBalance() + 100.0);
     store.save(user);
 } finally {
     store.relinquishLock();
 }
 

Lock requests may be nested.

Parameters:

beanClass - A class.

dataName - A string that identifies the data to be accessed in the critical section. This can be any string but preferably it should be something that sufficiently identifies the row to be modified to provide proper lock isolation. For example, it could be a string representation or a hash of a unique index.

transactionIsolationLevel - See Connection constants.

Throws:

StoreException

java.lang.InterruptedException

See Also:

relinquishLock(), beginTransaction()

relinquishLock

public void relinquishLock()
                    throws StoreException

Relinquishes a lock previously obtained with requestLock(Class, String, int).

Throws:

StoreException

relinquishLock

public void relinquishLock(boolean rollback)
                    throws StoreException

Relinquishes a lock previously obtained with requestLock(Class, String, int).

Parameters:

rollback - Whether the transaction should be rolled back. It only applies to the outer-most lock block.

Throws:

StoreException

isPersistable

public static boolean isPersistable(java.lang.Class beanClass)

Determines if a class is understood by Store as one whose instances can be persisted in a database.

Parameters:

beanClass - A bean's class.

selectParts

public ResultsIterator selectParts(java.lang.Object containerBean,
                                   java.lang.Class partbeanClass,
                                   java.lang.String linkPropertyInPart)
                            throws StoreException

Gets an iterator of objects of the given class which have a "foreign key" property value equal to the containerBean given. The foreign key property linkPropertyInPart type must be assignable to Persistent (or PersistentID).

This is useful in queryting one-to-many relationships, and getting parts of a whole.

Throws:

StoreException

selectParts

public ResultsIterator selectParts(PersistentID containerBeanID,
                                   java.lang.Class partbeanClass,
                                   java.lang.String linkPropertyInPart)
                            throws StoreException

Gets an iterator of objects of the given class which have a "foreign key" property value equal to the containerBeanID given. The foreign key property linkPropertyInPart type must be assignable to Persistent (or PersistentID).

This is useful in queryting one-to-many relationships, and getting parts of a whole.

Throws:

StoreException

selectParts

public ResultsIterator selectParts(PersistentID containerBeanID,
                                   java.lang.Class linkClass,
                                   java.lang.Class partClass,
                                   java.lang.String propertyLinkingContainer,
                                   java.lang.String propertyLinkingPart)
                            throws StoreException

Queries beans linked to a given bean by means of an intermediate class. In other words, this query is designed for many-to-many relationships involving three classes, e.g. Instructor, Department and InstructorDepartment. A sample invocation follows.

 // Find departments an instructor works for
 store.selectParts(instructor, InstructorDepartment.class, Department.class, "instructorID", "departmentID");
 

Notes:

• This method requires INNER JOIN support.
• At the very least propertyLinkingContainer should be indexed.

Parameters:

containerBeanID - ID of the bean we're trying find related beans for.

linkClass - The intermediate class used to implement the many-to-many relationship.

partClass - The class we are querying.

propertyLinkingContainer - Property in linkClass which refers to the containerBeaninstance.

propertyLinkingPart - Property in linkClass which refers to a partClass instance.

Throws:

StoreException

select

public ResultsIterator select(java.lang.Class inbeanClass)
                       throws StoreException

Gets an iterator of all stored instances of the given class.

Throws:

StoreException

selectSingle

public java.lang.Object selectSingle(java.lang.Class beanClass,
                                     java.lang.String propertyName,
                                     java.lang.Object propertyValue)
                              throws StoreException

Finds a stored instance with the property value given.

Returns:

An instance of beanClass or null if an object is not found.

Throws:

StoreException

selectSingle

public java.lang.Object selectSingle(java.lang.Class beanClass,
                                     java.util.Map values)
                              throws StoreException

Finds a stored instance matching the property values given.

Parameters:

beanClass - Only instances of this class are searched.

values - A map of property names to values.

Returns:

An instance of beanClass or null if an object is not found.

Throws:

StoreException

selectSingle

public java.lang.Object selectSingle(java.lang.Class beanClass,
                                     java.util.Map values,
                                     java.lang.String orderBy,
                                     boolean descending)
                              throws StoreException

Finds a stored instance matching the property values given.

Parameters:

beanClass - Only instances of this class are searched.

values - A map of property names to values.

Returns:

An instance of beanClass or null if an object is not found.

Throws:

StoreException

select

public ResultsIterator select(java.lang.Class beanClass,
                              java.util.Map values)
                       throws StoreException

Finds all stored instances matching the property values given.

Parameters:

beanClass - Only instances of this class are searched.

values - A map of property names to values.

Returns:

An iterator of Persistent objects.

Throws:

StoreException

select

public ResultsIterator select(java.lang.Class beanClass,
                              java.util.Map values,
                              java.lang.String orderByProperty,
                              boolean descending,
                              java.lang.Integer limit)
                       throws StoreException

Finds stored instances matching the property values given.

Parameters:

beanClass - Only instances of this class are searched.

values - A map of property names to values. A value of null indicates all stored instances should

orderByProperty - Property name to order by. A value of null indicates there's no ordering.

descending - In case orderByProperty is not null, whether ordering should descend.

limit - The maximum number of results to return. A value of null indicates there's no limit.

Returns:

An iterator of Persistent objects.

Throws:

StoreException

select

public ResultsIterator select(java.lang.Class beanClass,
                              java.util.Map propertyValues,
                              java.lang.String orderByProperty,
                              boolean descending,
                              java.lang.Integer limit,
                              BeanFactory beanFactory)
                       throws StoreException

Finds stored instances matching the property values given.

Parameters:

beanClass - Only instances of this class are searched.

propertyValues - A map of property names to values. The map can be of type Criteria which allows operators other than equality.

orderByProperty - Property name to order by. A value of null indicates there's no ordering.

descending - In case orderByProperty is not null, whether ordering should descend.

limit - The maximum number of results to return. A value of null indicates there's no limit.

beanFactory - A factory that instantiates beanClass.

Returns:

An iterator of Persistent objects.

Throws:

StoreException

select

public ResultsIterator select(java.lang.Class beanClass,
                              java.lang.String sqlQuery,
                              java.lang.Object[] parameters)
                       throws StoreException

General-purpose method for arbitrary SQL queries that return an iterator of beans. Note that this is a potentially unsafe method. The caller is expected to query the right table, with the right field list, and matching bean class information.

The select overload that takes a BeanFactory argument is potentially faster.

Parameters:

sqlQuery - An arbitrary SQL query, optionally with JDBC-style placeholders (i.e. question marks).

parameters - An array of parameters corresponding to placeholders in the query.

beanClass - The bean class that will be instantiated for each row.

Returns:

An iterator of beans. Note that the iterator should be closed when the caller is done with it.

Throws:

StoreException

select

public ResultsIterator select(java.lang.Class beanClass,
                              java.lang.String sqlQuery,
                              java.lang.Object[] parameters,
                              BeanFactory beanFactory)
                       throws StoreException

General-purpose method for arbitrary SQL queries that return an iterator of beans. Note that this is a potentially unsafe method. The caller is expected to query the right table, with the right field list, and matching bean class information.

Parameters:

sqlQuery - An arbitrary SQL query, optionally with JDBC-style placeholders (i.e. question marks).

parameters - An array of parameters corresponding to placeholders in the query.

beanClass - The bean class that will be instantiated for each row.

beanFactory - A bean class instantiator factory.

Returns:

An iterator of beans. Note that the iterator should be closed when the caller is done with it.

Throws:

StoreException

delete

public boolean delete(java.lang.Class beanClass,
                      java.util.Map values)
               throws StoreException

Deletes all database records that match the given criteria. Once the record corresponding to a Persistent object is deleted, subsequent invocations to save will fail.

Throws:

StoreException

update

public boolean update(java.lang.Class beanClass,
                      java.lang.String sqlStatement,
                      java.lang.String[] propertyNames,
                      java.lang.Object[] parameters)
               throws StoreException

Executes an arbitrary database update. The bean class provided along with the array of property names are used to convert parameters to types that can be saved in the database.

Parameters:

beanClass - A bean class.

sqlStatement - An arbitrary SQL update statement.

parameters - An array of Java objects. These can be bean instances, which should be converted to reference IDs properly.

propertyNames - An array of property names corresponding to each parameter. Property names are only used for conversion purposes. This array can be shorter than the parameters array. Remaining parameters won't be converted.

Returns:

True if updates were actually made.

Throws:

StoreException