1 /**
2 * Copyright 2005-2016 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.QueryByCriteria;
19 import org.kuali.rice.core.api.criteria.QueryResults;
20 import org.kuali.rice.krad.data.CopyOption;
21 import org.kuali.rice.krad.data.PersistenceOption;
22
23 /**
24 * Defines persistence SPI for data providers.
25 *
26 * <p>
27 * PersistenceProviders are responsible for creating, updating, querying, copying and deleting data objects.
28 * DataObjectTypes the PersistenceProvider supports must be queried through {@link #handles(Class)} before interaction
29 * with the PersistenceProvider.
30 * </p>
31 *
32 * @author Kuali Rice Team (rice.collab@kuali.org)
33 */
34 public interface PersistenceProvider extends Provider {
35
36 /**
37 * Saves the given data object, determining whether or not this is a new data object which is being created, or an
38 * existing one which should be updated.
39 *
40 * <p>
41 * Optional persistence options can be passed to indicate whether or not linking should be performed prior to
42 * persistence and whether or not validation should be performed. By default, linking is performed as well as
43 * validation.
44 * </p>
45 *
46 * @param dataObject the data object to save
47 * @param options the options to use when saving the data object
48 * @param <T> the data object class type
49 *
50 * @return the saved data object, calling code should always use the reference the object returned from this method
51 * for future operations after calling the save since it could have been updated
52 *
53 * @throws IllegalArgumentException if {@code dataObject} is not a valid data object
54 * @throws org.springframework.dao.DataAccessException if data access fails
55 */
56 <T> T save(T dataObject, PersistenceOption... options);
57
58 /**
59 * Invoked to retrieve a data object instance by a single primary key field or id object.
60 *
61 * <p>In the case of a compound primary key consisting of multiple attributes on the data object, a CompoundKey can
62 * be passed in order to encapsulate these into a single argument.
63 * </p>
64 *
65 * @param type the type of the data object to find
66 * @param id the id representing the primary key of the data object to find
67 * @param <T> the data object class type
68 *
69 * @return the entity with the given primary key or null if none found
70 *
71 * @throws IllegalArgumentException if {@code type} does not denote a data object type or {@code id} is not a valid
72 * type for the data object's primary key or is null
73 * @throws org.springframework.dao.DataAccessException if data access fails
74 */
75 <T> T find(Class<T> type, Object id);
76
77 /**
78 * Executes a query for the given data object.
79 *
80 * <p>
81 * If the given QueryByCriteria is empty or null, then all data objects for the given type will be returned.
82 * Depending on the given criteria and the implementation for the query execution, not all matching results may be
83 * returned. The QueryResults will contain information on whether or not there are additional results which can be
84 * used for paging and similar functionality.
85 * </p>
86 *
87 * @param type the type of the data objects to query
88 * @param queryByCriteria query object, can contain sorting and page request configuration
89 * @param <T> the data object class type
90 *
91 * @return the results of the query, will never return null but may return empty results
92 *
93 * @throws IllegalArgumentException if {@code type} does not denote a data object type or if {@code queryByCriteria}
94 * is null
95 * @throws org.springframework.dao.DataAccessException if data access fails
96 */
97 <T> QueryResults<T> findMatching(Class<T> type, QueryByCriteria queryByCriteria);
98
99 /**
100 * Retrieves all data objects for the given type.
101 *
102 * @param type the type of data objects to find
103 * @param <T> the data object class type
104 *
105 * @return the results of the query, will never return null but may return empty results
106 *
107 * @throws java.lang.IllegalArgumentException if type is null.
108 */
109 <T> QueryResults<T> findAll(Class<T> type);
110
111 /**
112 * Deletes a given data object.
113 *
114 * @param dataObject the data object to delete
115 *
116 * @throws IllegalArgumentException if {@code dataObject} is not a valid data object
117 * @throws org.springframework.dao.DataAccessException if data access fails
118 */
119 void delete(Object dataObject);
120
121 /**
122 * Deletes data objects based on the given criteria
123 *
124 * <p>If the given criteria is empty or null than an {@link java.lang.IllegalArgumentException} will be thrown.
125 * If the given type is null then an {@link java.lang.IllegalArgumentException} will be thrown.</p>
126 *
127 * @param type the type of data object
128 * @param queryByCriteria criteria to filter by
129 *
130 * @throws IllegalArgumentException if the criteria or criteria predicate is null
131 * @throws org.springframework.dao.DataAccessException if data access fails
132 */
133 <T> void deleteMatching(Class<T> type, QueryByCriteria queryByCriteria);
134
135 /**
136 * Deletes all data objects based on the given type.
137 *
138 * @param type the type of data objects to delete
139 * @param <T> the data object class type
140 *
141 * @throws IllegalArgumentException if the class type is null
142 * @throws org.springframework.dao.DataAccessException if data access fails
143 */
144 <T> void deleteAll(Class<T> type);
145
146 /**
147 * Returns a copy of the given data object instance.
148 *
149 * <p>
150 * The method of copying is provider dependent, and will handle instances (including nested) using whatever measures
151 * might be required to deal with the quirks of said provider (e.g. fetching lazy loaded relations).
152 * </p>
153 *
154 * @param dataObject the data object to copy
155 * @param <T> the type of the data object
156 *
157 * @return a copy of the given data object
158 */
159 <T> T copyInstance(T dataObject, CopyOption... options);
160
161 /**
162 * Indicates whether or not this provider handles persistence for the given data object type.
163 *
164 * <p>
165 * Responsibility on with the caller to call prior to invocation of any other PersistenceProvider methods to ensure
166 * the data objects of the right type are passed.
167 * </p>
168 *
169 * @param type the data object type to check
170 *
171 * @return true if this provider can handle the given type, false otherwise
172 */
173 boolean handles(Class<?> type);
174
175 /**
176 * Flush any outstanding changes within the current context for the provider pertaining to the given data object
177 * Class type.
178 *
179 * <p>
180 * If an implementation of this interface does not support or require the concept of "flushing", this method can be
181 * ignored. However, when used, this must purge *all* cache items for the given types from all caches managed by
182 * this provider.
183 * </p>
184 *
185 * @param type
186 * the type of the data object for which to perform the flush. This should be used to identify the
187 * context in which to perform the flush.
188 */
189 void flush(Class<?> type);
190
191 }