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