it.biobytes.ammentos
Class Ammentos

java.lang.Object
  extended by it.biobytes.ammentos.Ammentos

public class Ammentos
extends java.lang.Object

This class represents the persistence framework itself. Provides all methods for managing objects persistence: save, load, lookup by primary key and delete operations. These operations can be atomic or can be performed into a transaction by using the transaction related methods such as openTransaction(), commitTransaction() and rollbackTransaction(). An internal caching mechanism dramatically optimizes direct lookup() calls. Furthermore is possible to receive persistence events by registering PersistenceListeners objects to the Framework.

Author:
Davide Deidda

Constructor Summary
Ammentos()
           
 
Method Summary
static void addPersistenceListener(PersistenceListener listener)
          Adds a PersistenceListener to the framework.
static void commitTransaction()
          Commits the current transaction.
static
<T> T
createInstance(java.lang.Class<T> c)
          Creates a new instance of the provided object.
static
<T> void
delete(T obj)
          Deletes the object.
static
<T> java.util.List<Field>
diff(T obj1, T obj2)
          Returns a "diff" report for the provided objects
static java.sql.Connection getDbConnection()
          Returns a connection to the underlying database.
static Metadata getMetadata(java.lang.Class c)
          Returns the metadata for the objects that belong to the provided class.
static Field getPrimaryKeyField(java.lang.Class c)
          Gets the primary key field for the objects of the provided class
static
<T> T
load(java.lang.Class<T> c, java.lang.Object primaryKey)
          Loads the object whith the provided primary key
static
<T> java.util.List<T>
load(java.lang.Class<T> c, Query qry)
          Loads the objects which match the provided query.
static
<T> java.util.List<T>
loadUpdatable(java.lang.Class<T> c, Query qry)
          Returns an updatable list of objects which match the provided query.
static
<T> T
lookup(java.lang.Class<T> c, java.lang.Object primaryKey)
          Lookup the object of the provided class whith the specified primary key.
static void openTransaction()
          Opens a transaction to the datatabse.
static void openTransaction(int isolationLevel)
          Opens a transaction to the datatabse.
static void removePersistenceListener(PersistenceListener listener)
           
static void rollbackTransaction()
          Rolls back the current transaction.
static
<T> void
save(T obj)
          Saves the provided object instance.
static void setDataSource(javax.sql.DataSource source)
          Sets the datasource for this framework
static
<T> void
validate(java.lang.Class<T> c, T obj)
          Validates the provided Object using its related validator
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Ammentos

public Ammentos()
Method Detail

getMetadata

public static Metadata getMetadata(java.lang.Class c)
                            throws PersistenceException
Returns the metadata for the objects that belong to the provided class.

Parameters:
c - The class to get metadata for
Returns:
The metadata for the provided class
Throws:
PersistenceException - If the provided class does not contain valid metadata information

createInstance

public static <T> T createInstance(java.lang.Class<T> c)
                        throws PersistenceException
Creates a new instance of the provided object.

Parameters:
c - The class of the object to create
Returns:
An instance of the provided class
Throws:
PersistenceException - If any errors occurred while trying to create the instance

save

public static <T> void save(T obj)
                 throws PersistenceException
Saves the provided object instance. If a transaction is opened this operation will be actually performed when the commitTransaction() method will be called

Parameters:
obj - The object to save
Throws:
PersistenceException - If any errors occurr while saving the object

delete

public static <T> void delete(T obj)
                   throws PersistenceException
Deletes the object. If a transaction is opened this operation will be actually performed when the commitTransaction() method will be called

Parameters:
obj - The object to delete
Throws:
PersistenceException

load

public static <T> T load(java.lang.Class<T> c,
                         java.lang.Object primaryKey)
              throws PersistenceException
Loads the object whith the provided primary key

Parameters:
c -
primaryKey -
Returns:
Throws:
PersistenceException

load

public static <T> java.util.List<T> load(java.lang.Class<T> c,
                                         Query qry)
                              throws PersistenceException
Loads the objects which match the provided query. The returned list is unmodifiabale.

Parameters:
c -
qry -
Returns:
Throws:
PersistenceException

loadUpdatable

public static <T> java.util.List<T> loadUpdatable(java.lang.Class<T> c,
                                                  Query qry)
                                       throws PersistenceException
Returns an updatable list of objects which match the provided query. By calling add() and remove() method on this list the objects will be respectively saved or removed from their persistor.

Throws:
PersistenceException

getPrimaryKeyField

public static Field getPrimaryKeyField(java.lang.Class c)
                                throws PersistenceException
Gets the primary key field for the objects of the provided class

Parameters:
c -
Returns:
Throws:
PersistenceException

lookup

public static <T> T lookup(java.lang.Class<T> c,
                           java.lang.Object primaryKey)
                throws PersistenceException
Lookup the object of the provided class whith the specified primary key. This methods uses an internal caching mechanism which dramatically increases the performance, so use this method instead of load(Class,String) whenever is possible to obtain the best performance in retrieving objects.

Parameters:
c -
primaryKey -
Returns:
Throws:
PersistenceException

setDataSource

public static void setDataSource(javax.sql.DataSource source)
Sets the datasource for this framework

Parameters:
source -

openTransaction

public static void openTransaction()
                            throws PersistenceException
Opens a transaction to the datatabse. Each next call to save() method in the same thread will save objects into this transaction, until one between commitTransaction() or rollbackTransaction() is called. The isolation level for the created transaction is TRANSACTION_READ_UNCOMMITTED, what means that dirty reads are allowed.

Throws:
PersistenceException

openTransaction

public static void openTransaction(int isolationLevel)
                            throws PersistenceException
Opens a transaction to the datatabse. Each next call to save() method in the same thread will save objects into this transaction, until one between commitTransaction() or rollbackTransaction() is called. The isolation level for the created transaction must be one between the constants defined for java.sql.Connection.

Throws:
PersistenceException

rollbackTransaction

public static void rollbackTransaction()
                                throws PersistenceException
Rolls back the current transaction. The cache of the objects involved in the transaction will not be removed.

Throws:
PersistenceException

commitTransaction

public static void commitTransaction()
                              throws PersistenceException
Commits the current transaction. If the commit ends successfully all the objects involved in the transaction are removed from the cache.

Throws:
PersistenceException

getDbConnection

public static java.sql.Connection getDbConnection()
                                           throws PersistenceException
Returns a connection to the underlying database.

Returns:
Throws:
PersistenceException

validate

public static <T> void validate(java.lang.Class<T> c,
                                T obj)
                     throws PersistenceException
Validates the provided Object using its related validator

Parameters:
obj -
Throws:
PersistenceException

diff

public static <T> java.util.List<Field> diff(T obj1,
                                             T obj2)
                                  throws PersistenceException
Returns a "diff" report for the provided objects

Throws:
PersistenceException

addPersistenceListener

public static void addPersistenceListener(PersistenceListener listener)
Adds a PersistenceListener to the framework.

Parameters:
listener -

removePersistenceListener

public static void removePersistenceListener(PersistenceListener listener)