org.kuali.rice.krad.data

Interface DataObjectService

All Known Implementing Classes:

ProviderBasedDataObjectService

public interface DataObjectService

The primary API for interacting with the data layer.

Contains basic data access and query operations for supported data objects. Also provides access to the MetadataRepository which contains information about the structure and relationships between data objects.

This service supports the ability to create a DataObjectWrapper for a given data object. This wrapper allows for accessing and manipulating properties within the data object as well as performing various metadata-aware operations on the data object.

This service is meant to act as a facade to specific persistence and query-capable solutions and data stores. Implementations of this service may provide transactional capabilities where it makes sense to do so (and depending on the transactional support of the backend persistence technology). The documentation for the specific implementation of DataObjectService that is being used should be consulted for specifics on transaction semantics.

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) Removes all records for the given data object type
<T> void	deleteMatching(Class<T> type, QueryByCriteria queryByCriteria) Deletes records for the given type and matching 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) Executes a query for the given data object returning all data objects for the given type.
<T> QueryResults<T>	findMatching(Class<T> type, QueryByCriteria queryByCriteria) Executes a query for the given data object.
<T> T	findUnique(Class<T> type, QueryByCriteria queryByCriteria) Executes a query for the data object matching the given queryByCriteria and expecting a single unique result to be returned.
void	flush(Class<?> type) Flushes any outstanding work to the backend data store.
MetadataRepository	getMetadataRepository() Returns the MetadataRepository which provides access to all data object metadata known to the system.
<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.
<T> boolean	supports(Class<T> type) Returns whether the DataObjectService supports the given type, where "supports" means that there is at least one PersistenceProvider that handles the given type.
<T> DataObjectWrapper<T>	wrap(T dataObject) Wraps the given data object in an accessor which provides numerous utility and helper methods related to accessing data and attributes on the data object.

Method Detail

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

See Also:

CompoundKey

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, also if the queryByCriteria is null or empty.

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

findAll

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

Executes a query for the given data object returning all data objects for the given type.

Type Parameters:

T - the data object class type

Parameters:

type - tye type of data objects to query

Returns:

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

Throws:

IllegalArgumentException - if type is null.

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

findUnique

<T> T findUnique(Class<T> type,
               QueryByCriteria queryByCriteria)

Executes a query for the data object matching the given queryByCriteria and expecting a single unique result to be returned. If no results match the given criteria, then null will be returned. If the given criteria matches more than one result, then an IncorrectResultSizeDataAccessException will be thrown.

Type Parameters:

T - the data object class type

Parameters:

type - the type of the data object to query

queryByCriteria - query object defining the criteria for the query

Returns:

the single result of the query, or null if no objects were matched

Throws:

IllegalArgumentException - if type does not denote a data object type

org.springframework.dao.IncorrectResultSizeDataAccessException - if more than one object matched the given criteria

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 records for the given type and matching the given criteria. If the given type is null then an IllegalArgumentException will be thrown. If the given criteria is null or empty an IllegalArgumentException is also thrown to help prevent table truncations.

Parameters:

type - the type of data objects to delete

queryByCriteria - query object

Throws:

IllegalArgumentException - if type is null or if the QueryByCriteria is null or empty

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

deleteAll

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

Removes all records for the given data object type

Type Parameters:

T - the data object class type.

Parameters:

type - the type of data objects

Throws:

IllegalArgumentException - if type is null

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

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. By default, linking is performed.

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

flush

void flush(Class<?> type)

Flushes any outstanding work to the backend data store.

Depending on the backend persistence implementation for the given type, this method may or may not do anything.

Parameters:

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

getMetadataRepository

MetadataRepository getMetadataRepository()

Returns the MetadataRepository which provides access to all data object metadata known to the system.

Returns:

the MetadataRepository

wrap

<T> DataObjectWrapper<T> wrap(T dataObject)

Wraps the given data object in an accessor which provides numerous utility and helper methods related to accessing data and attributes on the data object.

Type Parameters:

T - the type of the data object

Parameters:

dataObject - the data object to wrap, must be non-null

Returns:

an accessor which wraps the given data object and it's associated metadata and provides utility and methods useful when accessing data and attributes on the data object

Throws:

IllegalArgumentException - if the given data object is null or an invalid data object type

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

supports

<T> boolean supports(Class<T> type)

Returns whether the DataObjectService supports the given type, where "supports" means that there is at least one PersistenceProvider that handles the given type.

Parameters:

type - the data object type

Returns:

whether the DataObjectService supports the given type