1 /**
2 * Copyright 2005-2014 The Kuali Foundation
3 *
4 * Licensed under the Educational Community License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.opensource.org/licenses/ecl2.php
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.kuali.rice.krad.data.provider;
17
18 import org.kuali.rice.core.api.criteria.LookupCustomizer;
19 import org.kuali.rice.core.api.criteria.QueryByCriteria;
20 import org.kuali.rice.core.api.criteria.QueryResults;
21 import org.kuali.rice.krad.data.PersistenceOption;
22
23 /**
24 * Defines persistence SPI for data providers. PersistenceProviders are responsible for creating, updating, querying,
25 * copying and deleting data objects. DataObjectTypes the PersistenceProvider supports must be queried through
26 * {@link #handles(Class)} before interaction with the PersistenceProvider.
27 *
28 * @author Kuali Rice Team (rice.collab@kuali.org)
29 */
30 public interface PersistenceProvider extends Provider {
31
32 /**
33 * Saves the given data object, determining whether or not this is a new data object which is being created, or an
34 * existing one which should be updated.
35 *
36 * <p>Optional persistence options can be passed to indicate whether or not linking should be performed prior to
37 * persistence and whether or not validation should be performed. By default, linking is performed as well as
38 * validation.</p>
39 *
40 * @param dataObject the data object to save
41 * @param options the options to use when saving the data object
42 * @param <T> the data object class type
43 *
44 * @return the saved data object, calling code should always use the reference the object returned from this method
45 * for future operations after calling the save since it could have been updated
46 *
47 * @throws IllegalArgumentException if {@code dataObject} is not a valid data object
48 * @throws org.springframework.dao.DataAccessException if data access fails
49 */
50 <T> T save(T dataObject, PersistenceOption... options);
51
52 /**
53 * Invoked to retrieve a data object instance by a single primary key field or id object. In the
54 * case of a compound primary key consisting of multiple attributes on the data object, a
55 * CompoundKey can be passed in order to encapsulate these into a single argument.
56 *
57 * @param type the type of the data object to find
58 * @param id the id representing the primary key of the data object to find
59 * @param <T> the data object class type
60 *
61 * @return the entity with the given primary key or null if none found
62 *
63 * @throws IllegalArgumentException if {@code type} does not denote a data object type or {@code id} is not a valid
64 * type for the data object's primary key or is null
65 * @throws org.springframework.dao.DataAccessException if data access fails
66 */
67 <T> T find(Class<T> type, Object id);
68
69 /**
70 * Executes a query for the given data object. If the given QueryByCriteria is empty or null, then
71 * all data objects for the given type will be returned. Depending on the given criteria and the
72 * implementation for the query execution, not all matching results may be returned. The QueryResults
73 * will contain information on whether or not there are additional results which can be used for paging
74 * and similar functionality.
75 *
76 * @param type the type of the data objects to query
77 * @param queryByCriteria query object, can contain sorting and page request configuration
78 * @param <T> the data object class type
79 *
80 * @return the results of the query, will never return null but may return empty results
81 *
82 * @throws IllegalArgumentException if {@code type} does not denote a data object type
83 * @throws org.springframework.dao.DataAccessException if data access fails
84 */
85 <T> QueryResults<T> findMatching(Class<T> type, QueryByCriteria queryByCriteria);
86
87 /**
88 * Executes a query for the given data object. If the given QueryByCriteria is empty or null, then
89 * all data objects for the given type will be returned. Depending on the given criteria and the
90 * implementation for the query execution, not all matching results may be returned. The QueryResults
91 * will contain information on whether or not there are additional results which can be used for paging
92 * and similar functionality.
93 *
94 * @param type the type of the data objects to query
95 * @param queryByCriteria query object, can contain sorting and page request configuration
96 * @param lookupCustomizer predication transformation
97 * @param <T> the data object class type
98 *
99 * @return the results of the query, will never return null but may return empty results
100 *
101 * @throws IllegalArgumentException if {@code type} does not denote a data object type
102 * @throws org.springframework.dao.DataAccessException if data access fails
103 */
104 <T> QueryResults<T> findMatching(Class<T> type, QueryByCriteria queryByCriteria, LookupCustomizer<T> lookupCustomizer);
105
106
107 /**
108 * Deletes a given data object.
109 *
110 * @param dataObject the data object to delete
111 *
112 * @throws IllegalArgumentException if {@code dataObject} is not a valid data object
113 * @throws org.springframework.dao.DataAccessException if data access fails
114 */
115 void delete(Object dataObject);
116
117 /**
118 * Returns a copy of the given data object instance.
119 *
120 * <p>The method of copying is provider dependent, and will handle instances (including nested) using whatever
121 * measures might be required to deal with the quirks of said provider (e.g. fetching lazy loaded relations).
122 * </p>
123 *
124 * @param dataObject the data object to copy
125 * @param <T> the type of the data object
126 * @return a copy of the given data object
127 */
128 <T> T copyInstance(T dataObject);
129
130 /**
131 * Indicates whether or not this provider handles persistence for the given data object type.
132 * Responsibility on with the caller to call prior to invocation of any other PersistenceProvider methods
133 * to ensure the data objects of the right type are passed.
134 *
135 * @param type the data object type to check
136 *
137 * @return true if this provider can handle the given type, false otherwise
138 */
139 boolean handles(Class<?> type);
140
141 /**
142 * Flush any outstanding changes within the current context for the provider pertaining to the given data object
143 * Class type.
144 *
145 * <p>If an implementation of this interface does not support or require the concept of "flushing", this method can
146 * be ignored.</p>
147 *
148 * @param type the type of the data object for which to perform the flush. This shoul be used to identify the
149 * context in which to perform the flush.
150 */
151 void flush(Class<?> type);
152
153 }