org.kuali.rice.krad.data.provider

Interface PersistenceProvider

All Superinterfaces:

Provider

All Known Implementing Classes:

JpaPersistenceProvider

public interface PersistenceProvider
extends Provider

Defines persistence SPI for data providers.

PersistenceProviders are responsible for creating, updating, querying, copying and deleting data objects. DataObjectTypes the PersistenceProvider supports must be queried through handles(Class) before interaction with the PersistenceProvider.

Author:

Kuali Rice Team (rice.collab@kuali.org)

Method Summary

Methods

Modifier and Type	Method and Description
<T> T	copyInstance(T dataObject, CopyOption... options) Returns a copy of the given data object instance.
void	delete(Object dataObject) Deletes a given data object.
<T> void	deleteAll(Class<T> type) Deletes all data objects based on the given type.
<T> void	deleteMatching(Class<T> type, QueryByCriteria queryByCriteria) Deletes data objects based on the given criteria
<T> T	find(Class<T> type, Object id) Invoked to retrieve a data object instance by a single primary key field or id object.
<T> QueryResults<T>	findAll(Class<T> type) Retrieves all data objects for the given type.
<T> QueryResults<T>	findMatching(Class<T> type, QueryByCriteria queryByCriteria) Executes a query for the given data object.
void	flush(Class<?> type) Flush any outstanding changes within the current context for the provider pertaining to the given data object Class type.
boolean	handles(Class<?> type) Indicates whether or not this provider handles persistence for the given data object type.
<T> T	save(T dataObject, PersistenceOption... options) Saves the given data object, determining whether or not this is a new data object which is being created, or an existing one which should be updated.

Method Detail

save

<T> T save(T dataObject,
         PersistenceOption... options)

Saves the given data object, determining whether or not this is a new data object which is being created, or an existing one which should be updated.

Optional persistence options can be passed to indicate whether or not linking should be performed prior to persistence and whether or not validation should be performed. By default, linking is performed as well as validation.

Type Parameters:

T - the data object class type

Parameters:

dataObject - the data object to save

options - the options to use when saving the data object

Returns:

the saved data object, calling code should always use the reference the object returned from this method for future operations after calling the save since it could have been updated

Throws:

IllegalArgumentException - if dataObject is not a valid data object

org.springframework.dao.DataAccessException - if data access fails

find

<T> T find(Class<T> type,
         Object id)

Invoked to retrieve a data object instance by a single primary key field or id object.

In the case of a compound primary key consisting of multiple attributes on the data object, a CompoundKey can be passed in order to encapsulate these into a single argument.

Type Parameters:

T - the data object class type

Parameters:

type - the type of the data object to find

id - the id representing the primary key of the data object to find

Returns:

the entity with the given primary key or null if none found

Throws:

IllegalArgumentException - if type does not denote a data object type or id is not a valid type for the data object's primary key or is null

org.springframework.dao.DataAccessException - if data access fails

findMatching

<T> QueryResults<T> findMatching(Class<T> type,
                               QueryByCriteria queryByCriteria)

Executes a query for the given data object.

If the given QueryByCriteria is empty or null, then all data objects for the given type will be returned. Depending on the given criteria and the implementation for the query execution, not all matching results may be returned. The QueryResults will contain information on whether or not there are additional results which can be used for paging and similar functionality.

Type Parameters:

T - the data object class type

Parameters:

type - the type of the data objects to query

queryByCriteria - query object, can contain sorting and page request configuration

Returns:

the results of the query, will never return null but may return empty results

Throws:

IllegalArgumentException - if type does not denote a data object type or if queryByCriteria is null

org.springframework.dao.DataAccessException - if data access fails

findAll

<T> QueryResults<T> findAll(Class<T> type)

Retrieves all data objects for the given type.

Type Parameters:

T - the data object class type

Parameters:

type - the type of data objects to find

Returns:

the results of the query, will never return null but may return empty results

Throws:

IllegalArgumentException - if type is null.

delete

void delete(Object dataObject)

Deletes a given data object.

Parameters:

dataObject - the data object to delete

Throws:

IllegalArgumentException - if dataObject is not a valid data object

org.springframework.dao.DataAccessException - if data access fails

deleteMatching

<T> void deleteMatching(Class<T> type,
                      QueryByCriteria queryByCriteria)

Deletes data objects based on the given criteria

If the given criteria is empty or null than an IllegalArgumentException will be thrown. If the given type is null then an IllegalArgumentException will be thrown.

Parameters:

type - the type of data object

queryByCriteria - criteria to filter by

Throws:

IllegalArgumentException - if the criteria or criteria predicate is null

org.springframework.dao.DataAccessException - if data access fails

deleteAll

<T> void deleteAll(Class<T> type)

Deletes all data objects based on the given type.

Type Parameters:

T - the data object class type

Parameters:

type - the type of data objects to delete

Throws:

IllegalArgumentException - if the class type is null

org.springframework.dao.DataAccessException - if data access fails

copyInstance

<T> T copyInstance(T dataObject,
                 CopyOption... options)

Returns a copy of the given data object instance.

The method of copying is provider dependent, and will handle instances (including nested) using whatever measures might be required to deal with the quirks of said provider (e.g. fetching lazy loaded relations).

Type Parameters:

T - the type of the data object

Parameters:

dataObject - the data object to copy

Returns:

a copy of the given data object

handles

boolean handles(Class<?> type)

Indicates whether or not this provider handles persistence for the given data object type.

Responsibility on with the caller to call prior to invocation of any other PersistenceProvider methods to ensure the data objects of the right type are passed.

Parameters:

type - the data object type to check

Returns:

true if this provider can handle the given type, false otherwise

flush

void flush(Class<?> type)

Flush any outstanding changes within the current context for the provider pertaining to the given data object Class type.

If an implementation of this interface does not support or require the concept of "flushing", this method can be ignored. However, when used, this must purge *all* cache items for the given types from all caches managed by this provider.

Parameters:

type - the type of the data object for which to perform the flush. This should be used to identify the context in which to perform the flush.