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;
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.metadata.MetadataRepository;
21 import org.springframework.dao.DataAccessException;
22 import org.springframework.dao.IncorrectResultSizeDataAccessException;
23
24 /**
25 * The primary API for interacting with the data layer.
26 *
27 * <p>Contains basic data access and query operations for supported data objects. Also provides access to the
28 * {@link MetadataRepository} which contains information about the structure and relationships between data objects.</p>
29 *
30 * <p>This service supports the ability to create a {@link DataObjectWrapper} for a given data object. This
31 * wrapper allows for accessing and manipulating properties within the data object as well as performing various
32 * metadata-aware operations on the data object.</p>
33 *
34 * <p>This service is meant to act as a facade to specific persistence and query-capable solutions and data stores.
35 * Implementations of this service may provide transactional capabilities where it makes sense to do so (and depending
36 * on the transactional support of the backend persistence technology). The documentation for the specific
37 * implementation of DataObjectService that is being used should be consulted for specifics on transaction
38 * semantics.</p>
39 *
40 * @author Kuali Rice Team (rice.collab@kuali.org)
41 */
42 public interface DataObjectService {
43
44 /**
45 * Invoked to retrieve a data object instance by a single primary key field or id object. In the
46 * case of a compound primary key consisting of multiple attributes on the data object, a
47 * {@link CompoundKey} can be passed in order to encapsulate these into a single argument.
48 *
49 * @param type the type of the data object to find
50 * @param id the id representing the primary key of the data object to find
51 * @param <T> the data object class type
52 *
53 * @return the entity with the given primary key or null if none found
54 *
55 * @throws IllegalArgumentException if {@code type} does not denote a data object type or {@code id} is not a valid
56 * type for the data object's primary key or is null
57 * @throws DataAccessException if data access fails
58 *
59 * @see CompoundKey
60 */
61 <T> T find(Class<T> type, Object id);
62
63 /**
64 * Executes a query for the given data object. If the given QueryByCriteria is empty or null, then
65 * all data objects for the given type will be returned. Depending on the given criteria and the
66 * implementation for the query execution, not all matching results may be returned. The QueryResults
67 * will contain information on whether or not there are additional results which can be used for paging
68 * and similar functionality.
69 *
70 * @param type the type of the data objects to query
71 * @param queryByCriteria query object, can contain sorting and page request configuration
72 * @param <T> the data object class type
73 *
74 * @return the results of the query, will never return null but may return empty results
75 *
76 * @throws IllegalArgumentException if {@code type} does not denote a data object type
77 * @throws DataAccessException if data access fails
78 */
79 <T> QueryResults<T> findMatching(Class<T> type, QueryByCriteria queryByCriteria);
80
81 /**
82 * Executes a query for the data object matching the given queryByCriteria and expecting a single unique result to
83 * be returned. If no results match the given criteria, then null will be returned. If the given criteria matches
84 * more than one result, then an {@link IncorrectResultSizeDataAccessException} will be
85 * thrown.
86 *
87 * @param type the type of the data object to query
88 * @param queryByCriteria query object defining the criteria for the query
89 * @param <T> the data object class type
90 *
91 * @return the single result of the query, or null if no objects were matched
92 *
93 * @throws IllegalArgumentException if {@code type} does not denote a data object type
94 * @throws IncorrectResultSizeDataAccessException if more than one object matched the given criteria
95 */
96 <T> T findUnique(Class<T> type, QueryByCriteria queryByCriteria);
97
98 /**
99 * Deletes a given data object.
100 *
101 * @param dataObject the data object to delete
102 *
103 * @throws IllegalArgumentException if {@code dataObject} is not a valid data object
104 * @throws DataAccessException if data access fails
105 */
106 void delete(Object dataObject);
107
108 /**
109 * Deletes data objects
110 *
111 * @param type the type of the data objects to query
112 * @param queryByCriteria query object
113 * @throws DataAccessException if data access fails
114 */
115 <T> void deleteMatching(Class<T> type, QueryByCriteria queryByCriteria);
116
117 /**
118 * Saves the given data object, determining whether or not this is a new data object which is being created, or an
119 * existing one which should be updated.
120 *
121 * <p>Optional persistence options can be passed to indicate whether or not linking should be performed prior to
122 * persistence. By default, linking is performed.</p>
123 *
124 * @param dataObject the data object to save
125 * @param options the options to use when saving the data object
126 * @param <T> the data object class type
127 *
128 * @return the saved data object, calling code should always use the reference the object returned from this method
129 * for future operations after calling the save since it could have been updated
130 *
131 * @throws IllegalArgumentException if {@code dataObject} is not a valid data object
132 * @throws DataAccessException if data access fails
133 */
134 <T> T save(T dataObject, PersistenceOption... options);
135
136 /**
137 * Flushes any outstanding work to the backend data store.
138 *
139 * <p>Depending on the backend persistence implementation for the given type, this method may or may not do
140 * anything.</p>
141 *
142 * @param type the type of the data object for which to perform the flush. This is primarily used to identify the
143 * context in which to perform the flush.
144 */
145 void flush(Class<?> type);
146
147
148 /**
149 * Returns the MetadataRepository which provides access to all data object metadata known to the system.
150 *
151 * @return the MetadataRepository
152 */
153 MetadataRepository getMetadataRepository();
154
155 /**
156 * Wraps the given data object in an accessor which provides numerous utility and helper methods related to
157 * accessing data and attributes on the data object.
158 *
159 * @param dataObject the data object to wrap, must be non-null
160 * @param <T> the type of the data object
161 * @return an accessor which wraps the given data object and it's associated metadata and provides utility and
162 * methods useful when accessing data and attributes on the data object
163 * @throws IllegalArgumentException if the given data object is null or an invalid data object type
164 */
165 <T> DataObjectWrapper<T> wrap(T dataObject);
166
167 /**
168 * Returns a copy of the given data object instance.
169 *
170 * <p>The method of copying is provider dependent, and will handle instances (including nested) using whatever
171 * measures might be required to deal with the quirks of said provider (e.g. fetching lazy loaded relations).
172 * </p>
173 *
174 * @param dataObject the data object to copy
175 * @param <T> the type of the data object
176 * @return a copy of the given data object
177 */
178 <T> T copyInstance(T dataObject);
179
180 /**
181 * Returns whether the DataObjectService supports the given type, where
182 * "supports" means that there is at least one PersistenceProvider that handles the given type.
183 *
184 * @param type the data object type
185 * @return whether the DataObjectService supports the given type
186 */
187 <T> boolean supports(Class<T> type);
188
189 }