org.dasein.persist
Class PersistentFactory<T>

java.lang.Object
  org.dasein.persist.PersistentFactory<T>

Type Parameters:

T - the type of object managed by this factory

public final class PersistentFactory<T>
extends Object

Manages the movement of persistent objects between the data store and a memory cache. This class is generally used as a delegate by true factory classes.

 public class EmployeeFactory {
   private PersistentFactory<Employee> factory;
   
   public EmployeeFactory() {
       factory = new PersistentFactory<Employee>(Employee.class, "employeeId", "ssn");
   }
   
   public Collection<Employee> findEmployees(String ln) throws PersistenceException {
       return factory.find("lastName", ln);
   }
   
   public Employee getEmployee(Long empid) throws PersistenceException {
       return factory.get("employeeId", empid);
   }
   
   public Employee getEmployee(String ssn) throws PersistenceException {
       return factory.get("ssn", ssn);
   }
   
   public void updateEmployee(Transaction xaction, Employee emp, Map<String,Object> state)
   throws PersistenceException {
       factory.update(xaction, emp, state);
   }
 }
 

This persistence is automatic. You may, however, specify your own queries that will be managed by passing in an extension of the Execution class.

Last modified: $Date: 2006/12/31 15:25:56 $

Version:

$Revision: 1.20 $

Author:

George Reese

Nested Class Summary

static interface

PersistentFactory.DependencyManager<T>

Field Summary

static String

LISTING Convenience constant used by search executions as they key for multi-valued results.

Constructor Summary

PersistentFactory(Class<T> cls, String... keys)
Constructs a new persistent factory for objects of the specified class with the named unique identifier attributes.

Method Summary

void	addCounter(String field, Class<? extends Execution> cls) Adds a query for counts on a specified field.
void	addSearch(String field, Class<? extends Execution> cls) Adds a query for searches on a specified field.
void	addSingleton(String field, Class<? extends Execution> cls) Adds a query for searches on a specified field.
long	count() Counts the total number of objects governed by this factory in the database.
long	count(Class<? extends Execution> cls, Map<String,Object> criteria) Counts the number of items matching an arbitrary query.
long	count(String field, Object val) Counts the total number of objects in the database matching the specified criteria.
long	countJoin(Class jc, String key, Object val)
T	create(Transaction xaction, Map<String,Object> state) Creates the specified object with the data provided in the specified state under the governance of the specified transaction.
Collection<T>	find(Class<? extends Execution> cls, Map<String,Object> criteria) Executes an arbitrary search using the passed in search class and criteria.
Collection<T>	find(Class jc, String key, Object id)
Collection<T>	find(String field, Object val) Executes a search that may return multiple values.
T	get(Map<String,Object> state)
T	get(String id, Object val) Retrieves the object uniquely identified by the value for the specified ID field.
String	getKey()
long	getNewKeyValue()
Collection<T>	list() Loads all elements of this class from the data store.
Collection<T>	list(Class<? extends Execution> cls)
Map<String,Translator<String>>	loadTranslations(Transaction xaction, String idstr)
void	remove(Transaction xaction, T item) Removes the specified item from the system permanently.
void	removeTranslations(Transaction xaction, String idstr)
void	saveTranslation(Transaction xaction, String idstr, String attr, Translator<String> val)
void	setCreate(Class<? extends Execution> cls) Sets the class that manages the query that will create objects in this factory in the data store.
void	setDependency(PersistentFactory.DependencyManager<T> mgr) Sets the callback class to handle the management of dependencies.
void	setRemove(Class<? extends Execution> cls) Sets the class that manages the query that will remove objects in this factory from the data store.
void	setUpdate(Class<? extends Execution> cls) Sets the class that manages the query that will update objects in this factory in the data store.
String	toString()
void	update(Transaction xaction, T item, Map<String,Object> state) Updates the specified object with the data provided in the specified state under the governance of the specified transaction.
void	write(File file, InputStream is)

Methods inherited from class java.lang.Object

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

Field Detail

LISTING

public static final String LISTING

Convenience constant used by search executions as they key for multi-valued results.

See Also:

Constant Field Values

Constructor Detail

PersistentFactory

public PersistentFactory(Class<T> cls,
                         String... keys)

Constructs a new persistent factory for objects of the specified class with the named unique identifier attributes.

Parameters:

cls - the class of objects managed by this factory

keys - a list of unique identifiers for instances of the specified class

Method Detail

addCounter

public void addCounter(String field,
                       Class<? extends Execution> cls)

Adds a query for counts on a specified field.

Parameters:

field - the field to count matches on

cls - the class of the query that performs the count

addSearch

public void addSearch(String field,
                      Class<? extends Execution> cls)

Adds a query for searches on a specified field.

Parameters:

field - the field to search on

cls - the class of the query that performs the search

addSingleton

public void addSingleton(String field,
                         Class<? extends Execution> cls)

Adds a query for searches on a specified field. These searches return unique values.

Parameters:

field - the field to search on

cls - the class of the query that performs the search

count

public long count()
           throws PersistenceException

Counts the total number of objects governed by this factory in the database.

Returns:

the number of objects in the database

Throws:

PersistenceException - an error occurred counting the elements in the database

count

public long count(String field,
                  Object val)
           throws PersistenceException

Counts the total number of objects in the database matching the specified criteria.

Parameters:

field - the field to match on

val - the value to match against

Returns:

the number of matching objects

Throws:

PersistenceException - an error occurred counting the elements in the database

count

public long count(Class<? extends Execution> cls,
                  Map<String,Object> criteria)
           throws PersistenceException

Counts the number of items matching an arbitrary query. This method expects the passed in query to have one field called 'count' in the map it returns. Anything else is ignored

Parameters:

cls - the execution class for the arbitrary query

criteria - the criteria to match against for the query

Returns:

the number of matches (essentially, the number returned from the arbitrary query in the 'count' field)

Throws:

PersistenceException - an error occurred executing the query.

countJoin

public long countJoin(Class jc,
                      String key,
                      Object val)
               throws PersistenceException

Throws:

PersistenceException

create

public T create(Transaction xaction,
                Map<String,Object> state)
         throws PersistenceException

Creates the specified object with the data provided in the specified state under the governance of the specified transaction.

Parameters:

xaction - the transaction governing this event

state - the new state for the new object

Throws:

PersistenceException - an error occurred talking to the data store, or creates are not supported

find

public Collection<T> find(String field,
                          Object val)
                   throws PersistenceException

Executes a search that may return multiple values. The specified field must have been set up by a call to @{link #addSearch(String,Class)}.

Parameters:

field - the field being searched on

val - the value being searched against

Returns:

a list of objects that match the criteria

Throws:

PersistenceException - an error occurred talking to the data store

find

public Collection<T> find(Class jc,
                          String key,
                          Object id)
                   throws PersistenceException

Throws:

PersistenceException

find

public Collection<T> find(Class<? extends Execution> cls,
                          Map<String,Object> criteria)
                   throws PersistenceException

Executes an arbitrary search using the passed in search class and criteria. This is useful for searches that simply do not fit well into the rest of the API.

Parameters:

cls - the class to perform the search

criteria - the search criteria

Returns:

the results of the search

Throws:

PersistenceException - an error occurred performing the search

get

public T get(Map<String,Object> state)
      throws PersistenceException

Throws:

PersistenceException

get

public T get(String id,
             Object val)
      throws PersistenceException

Retrieves the object uniquely identified by the value for the specified ID field.

Parameters:

id - the ID field identifying the object

val - the value that uniquely identifies the desired object

Returns:

the object matching the query criterion

Throws:

PersistenceException - an error occurred talking to the data store

getKey

public String getKey()

getNewKeyValue

public long getNewKeyValue()
                    throws PersistenceException

Throws:

PersistenceException

list

public Collection<T> list()
                   throws PersistenceException

Loads all elements of this class from the data store. Use this method only when you know exactly what you are doing. Otherwise, you will pull a lot of data.

Returns:

all objects from the database

Throws:

PersistenceException - an error occurred executing the query

list

public Collection<T> list(Class<? extends Execution> cls)
                   throws PersistenceException

Throws:

PersistenceException

loadTranslations

public Map<String,Translator<String>> loadTranslations(Transaction xaction,
                                                       String idstr)
                                                throws PersistenceException

Throws:

PersistenceException

remove

public void remove(Transaction xaction,
                   T item)
            throws PersistenceException

Removes the specified item from the system permanently.

Parameters:

xaction - the transaction under which this event is occurring

item - the item to be removed

Throws:

PersistenceException - an error occurred talking to the data store or removal of these objects is prohibited

removeTranslations

public void removeTranslations(Transaction xaction,
                               String idstr)
                        throws PersistenceException

Throws:

PersistenceException

saveTranslation

public void saveTranslation(Transaction xaction,
                            String idstr,
                            String attr,
                            Translator<String> val)
                     throws PersistenceException

Throws:

PersistenceException

setCreate

public void setCreate(Class<? extends Execution> cls)

Sets the class that manages the query that will create objects in this factory in the data store.

Parameters:

cls - the execution class that creates objects in the data store

setDependency

public void setDependency(PersistentFactory.DependencyManager<T> mgr)

Sets the callback class to handle the management of dependencies.

Parameters:

mgr - the dependency manager to use for dependency management

setRemove

public void setRemove(Class<? extends Execution> cls)

Sets the class that manages the query that will remove objects in this factory from the data store.

Parameters:

cls - the execution class that removes objects from the data store

setUpdate

public void setUpdate(Class<? extends Execution> cls)

Sets the class that manages the query that will update objects in this factory in the data store.

Parameters:

cls - the execution class that updates objects in the data store

update

public void update(Transaction xaction,
                   T item,
                   Map<String,Object> state)
            throws PersistenceException

Updates the specified object with the data provided in the specified state under the governance of the specified transaction.

Parameters:

xaction - the transaction governing this event

item - the item to be updated

state - the new state for the updated object

Throws:

PersistenceException - an error occurred talking to the data store, or updates are not supported

write

public void write(File file,
                  InputStream is)
           throws IOException

Throws:

IOException

toString

public String toString()

Overrides:

toString in class Object