net.sf.mmm.persistence.api

Interface GenericDao<ID,ENTITY extends GenericEntity<ID>>

Type Parameters:

ID - is the type of the primary key of the managed GenericEntity.

ENTITY - is the type of the managed entity. We strongly recommend to extend PersistenceEntity.

All Known Subinterfaces:

RevisionedDao<ID,ENTITY>

All Known Implementing Classes:

AbstractGenericDao, AbstractJpaGenericDao, AbstractRevisionedDao, AbstractRevisionedDaoEnvers, JpaGenericDao

@ComponentSpecification(plugin=true)
public interface GenericDao<ID,ENTITY extends GenericEntity<ID>>

This is the interface for a Data Access Object (DAO). It acts as a manager responsible for the persistence operations on a specific type of GenericEntity. It is responsible for loading, saving and searching entities of the according type.
For each (non-abstract) implementation of GenericEntity there should exist one instance of this interface. Typically when you create a custom entity you will also create a custom interface and implementation of an according GenericDao. If there is no custom implementation of a GenericDao for some type of GenericEntity, a generic implementation is used as fallback.
The PersistenceManager can be seen as the manager of all GenericDao and acts as front-end to them.

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

GenericEntity, PersistenceManager

Method Summary

Modifier and Type	Method and Description
ENTITY	create() This method creates a new, empty, and transient instance of the managed entity.
void	delete(ENTITY entity) This method deletes the given entity from the persistent store.
void	deleteById(ID id) This method deletes the entity identified by the given id from the persistent store.
ENTITY	find(ID id) This method loads the GenericEntity with the given id from the persistent store.
ENTITY	findIfExists(ID id) This method loads the GenericEntity with the given id from the persistent store.
Class<? extends ENTITY>	getEntityClass() This method gets the Class reflecting the GenericEntity managed by this GenericDao.
ENTITY	getReference(ID id) This method creates a lazy reference proxy of the GenericEntity with the given id from the persistent store.
void	save(ENTITY entity) This method saves the given entity in the persistent store.

Method Detail

create

ENTITY create()
       throws ReflectionException

This method creates a new, empty, and transient instance of the managed entity. The default implementation is Class.newInstance(), however more specific implementations are possible. This allows to use interfaces for entities and use the persistence layer as API without knowing the implementation. However you are still free to ignore this method and work with the POJO approach.

Returns:

the new instance.

Throws:

ReflectionException - is the instantiation failed.

getEntityClass

Class<? extends ENTITY> getEntityClass()

This method gets the Class reflecting the GenericEntity managed by this GenericDao.

Returns:

the according entity-class.

find

ENTITY find(ID id)
     throws ObjectNotFoundException

This method loads the GenericEntity with the given id from the persistent store.

Parameters:

id - is the primary key of the requested entity.

Returns:

the requested entity.

Throws:

ObjectNotFoundException - if the requested entity could NOT be found. Unlike the JPA we throw this exception instead of returning null as this is typically an exceptional situation and it is better to have a precise exception than a NPE. Otherwise use findIfExists(Object).

See Also:

EntityManager.find(Class, Object)

findIfExists

ENTITY findIfExists(ID id)

This method loads the GenericEntity with the given id from the persistent store.

Parameters:

id - is the primary key of the requested entity.

Returns:

the requested entity or null if it does NOT exist in persistent store.

See Also:

EntityManager.find(Class, Object)

getReference

ENTITY getReference(ID id)

This method creates a lazy reference proxy of the GenericEntity with the given id from the persistent store.

Parameters:

id - is the primary key of the requested entity.

Returns:

the requested entity.

See Also:

EntityManager.getReference(Class, Object)

save

void save(ENTITY entity)

This method saves the given entity in the persistent store. If the entity is new it is initially created in the persistent store (after commit). If the entity is configured to have a generated primary key a unique ID is generated and assigned. Otherwise, if the entity is already managed , the entity is updated in the persistent store.
ATTENTION:
Modifications to a managed entity are automatically saved even if this method has NOT been invoked. However, it is a good practice to always invoke this method after modifying a managed entity to make your code more explicit. This will also guarantee that potential custom-logic of your DAO is invoked.

Parameters:

entity - is the GenericEntity to save.

delete

void delete(ENTITY entity)

This method deletes the given entity from the persistent store.
If the entity is transient this method has no effect.

Parameters:

entity - is the GenericEntity to save.

deleteById

void deleteById(ID id)

This method deletes the entity identified by the given id from the persistent store.

Parameters:

id - is the primary key of the entity to delete.