Package 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

    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)
    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 Details

    • 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:

    • 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