io.oasp.module.jpa.dataaccess.api

Interface GenericDao<ID,E extends net.sf.mmm.util.entity.api.PersistenceEntity<ID>>

Type Parameters:

ID - is the generic type if the primary key.

E - is the generic type of the PersistenceEntity.

All Known Subinterfaces:

Dao<E>, MasterDataDao<E>

All Known Implementing Classes:

AbstractDao, AbstractGenericDao, AbstractMasterDataDao

public interface GenericDao<ID,E extends net.sf.mmm.util.entity.api.PersistenceEntity<ID>>

This is the interface for a Data Access Object (DAO). It acts as a manager responsible for the persistence operations on a specific entity <E>.
This is base interface contains the CRUD operations:

• Create: call save(PersistenceEntity) on a new entity.
• Retrieve: use find* methods such as findOne(Object). More specific queries will be added in dedicated DAO interfaces.
• Update: done automatically by JPA vendor (hibernate) on commit or call save(PersistenceEntity) to merge an entity.
• Delete: call delete(PersistenceEntity) or delete(Object).

For each (non-abstract) implementation of entity MyEntity you should create an interface interface MyEntityDao that inherits from this GenericDao interface. Also you create an implementation of that interface MyEntityDaoImpl that you derive from AbstractGenericDao.

Author:

hohwille

Method Summary

Methods

Modifier and Type	Method and Description
void	delete(E entity) Deletes a given entity.
void	delete(ID id) Deletes the entity with the given id.
void	delete(Iterable<? extends E> entities) Deletes the given entities.
boolean	exists(ID id) Returns whether an entity with the given id exists.
E	find(ID id) Retrieves an entity by its id.
List<E>	findAll(Iterable<ID> ids) Returns all instances of the type with the given IDs.
E	findOne(ID id) Retrieves an entity by its id.
void	forceIncrementModificationCounter(E entity) Enforces to increment the modificationCounter e.g.
E	save(E entity) Saves a given entity.
void	save(Iterable<? extends E> entities) Saves all given entities.

Method Detail

save

E save(E entity)

Saves a given entity. Use the returned instance for further operations as the save operation might have changed the entity instance completely.

Parameters:

entity - the entity to save

Returns:

the saved entity

save

void save(Iterable<? extends E> entities)

Saves all given entities.

Parameters:

entities - the entities to save

find

E find(ID id)
                                                                throws net.sf.mmm.util.exception.api.ObjectNotFoundUserException

Retrieves an entity by its id.

Parameters:

id - must not be null.

Returns:

the entity with the given id or null if none found

Throws:

net.sf.mmm.util.exception.api.ObjectNotFoundUserException - if the requested entity does not exists (use findOne(Object) to prevent).

findOne

E findOne(ID id)
                                                                   throws IllegalArgumentException

Retrieves an entity by its id.

Parameters:

id - must not be null.

Returns:

the entity with the given id or null if none found

Throws:

IllegalArgumentException - if id is null

exists

boolean exists(ID id)

Returns whether an entity with the given id exists.

Parameters:

id - must not be null.

Returns:

true if an entity with the given id exists, false otherwise

findAll

List<E> findAll(Iterable<ID> ids)

Returns all instances of the type with the given IDs.

Parameters:

ids - are the IDs of all entities to retrieve e.g. as List.

Returns:

an Iterable with all entites for the given ids.

delete

void delete(ID id)
            throws IllegalArgumentException

Deletes the entity with the given id.

Parameters:

id - must not be null.

Throws:

IllegalArgumentException - in case the given id is null

delete

void delete(E entity)

Deletes a given entity.

Parameters:

entity - the entity to delete

delete

void delete(Iterable<? extends E> entities)

Deletes the given entities.

Parameters:

entities - the entities to delete

forceIncrementModificationCounter

void forceIncrementModificationCounter(E entity)

Enforces to increment the modificationCounter e.g. to enforce that a parent object gets locked when its children are modified.
As an example we assume that we have the two optimistic locked entities Order and its contained OrderPosition. By default the users can modify an Order and each of its OrderPositions in parallel without getting a locking conflict. This can be desired. However, it can also be a demand that an Order gets approved and the user doing that is responsible for the total price as the sum of the prices of each OrderPosition. Now if another user is adding or changing an OrderPostion belonging to that Order in parallel the Order will get approved but the approved total price will differ from what the user has actually seen when he clicked on approve. To prevent this the use-case to modify an OrderPosition can use this method to trigger a locking on the associated Order. The implication is also that two users changing an OrderPosition associated with the same Order in parallel will get a conflict.

Parameters:

entity - that is getting checked.