com.subshell.persistence.mapper
Interface PersistenceMapper<T>

All Known Implementing Classes:

TransactionPersistenceMapper

public interface PersistenceMapper<T>

All persistence mappers must implement this interface.

A persistence mapper can be used to directly access the database without losing the abstractions of the persistence API. For example, it can provide methods which return a list of objects in a more efficient manner than the usual persistent objects could do.

Persistence mappers can be obtained using Database.getPersistenceMapper().

Persistence mappers must not be used across transaction boundaries. That is, a persistence mapper must not be used during a different transaction than the one during which it was created.

Note: Depending on the application using the persistence mapper, it is strongly recommended that implementors be thread-safe. That is, implementations should make no use of instance member variables and the like.

Also, implementations of PersistenceMapper must provide a publicly accessible no-args constructor.

The following is an example of a persistence mapper for objects of type Foo. Please note that this implementation is suited for use with Hibernate only. To make use of other O/R mappers, a different implementation of PersistenceMapper should be used. Use interfaces for lose coupling (FooPersistenceMapper in this example).

     public interface FooPersistenceMapper extends PersistenceMapper {
         Set getAllWithDeletedFlag(boolean deleted);
     }

     public class HibernateFooPersistenceMapper extends TransactionPersistenceMapper
         implements FooPersistenceMapper {
 
         public HibernateFooPersistenceMapper(Transaction tx, Class clazz) {
             super(tx, clazz);
         }
 
         public Set getAllWithDeletedFlag(boolean deleted) {
             // directly cast the Transaction to HibernateTransaction
             HibernateTransaction htx = (HibernateTransaction) getTransaction();

             // get a Hibernate Session from that transaction
             Session session = htx.getSession();

             // ... do something with Hibernate's session and
             // return a Set of Foo objects ...
         }
     }
 

Method Summary

Serializable	create(T o) Creates an object in the database.
void	delete(T o) Deletes a persistent object from the database.
boolean	isPersistent(T o) Returns whether an object is persistent.
T	load(Serializable id) Loads an object from the database.

Method Detail

load

T load(Serializable id)
       throws PersistenceException,
              ObjectNotFoundException

Loads an object from the database.

Parameters:

id - the object's ID

Throws:

PersistenceException - when loading the object fails

ObjectNotFoundException - if no object with the given id is found

TransactionCommittedException - when the underlying Transaction has been commited/rolled back already

create

Serializable create(T o)
                    throws PersistenceException

Creates an object in the database.

Parameters:

o - the object to create

Returns:

the identifier that has been assigned to the created object

Throws:

PersistenceException - when creating the object fails

TransactionCommittedException - when the underlying Transaction has been commited/rolled back already

delete

void delete(T o)
            throws PersistenceException

Deletes a persistent object from the database.

Parameters:

o - the object to delete

Throws:

PersistenceException - when deleting the object fails

TransactionCommittedException - when the underlying Transaction has been commited/rolled back already

isPersistent

boolean isPersistent(T o)
                     throws PersistenceException

Returns whether an object is persistent.

Throws:

PersistenceException - when there is a persistence-related error