Package 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

    Modifier and Type
    Method
    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, org.kuali.rice.core.api.criteria.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> org.kuali.rice.core.api.criteria.QueryResults<T>
    findAll(Class<T> type)
    Retrieves all data objects for the given type.
    <T> org.kuali.rice.core.api.criteria.QueryResults<T>
    findMatching(Class<T> type, org.kuali.rice.core.api.criteria.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 Details

    • 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> org.kuali.rice.core.api.criteria.QueryResults<T> findMatching(Class<T> type, org.kuali.rice.core.api.criteria.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> org.kuali.rice.core.api.criteria.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, org.kuali.rice.core.api.criteria.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.