1 /**
2 * Copyright 2005-2013 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.service;
17
18 import org.kuali.rice.krad.bo.BusinessObject;
19 import org.kuali.rice.krad.bo.PersistableBusinessObject;
20 import org.kuali.rice.krad.util.LegacyDataFramework;
21
22 import java.util.Collection;
23 import java.util.List;
24 import java.util.Map;
25
26 /**
27 * Defines methods that a BusinessObjectService must provide
28 *
29 * @author Kuali Rice Team (rice.collab@kuali.org)
30 * @deprecated use new KRAD Data framework {@link org.kuali.rice.krad.data.DataObjectService}
31 */
32 @Deprecated
33 @LegacyDataFramework
34 public interface BusinessObjectService {
35
36 /**
37 * Saves the passed in object via the persistence layer.
38 *
39 * This will throw an IllegalArgumentException (runtime exception) if the object passed in is not a descendent of
40 * BusinessObject.
41 *
42 * @param bo A BusinessObject instance or descendent that you wish to be stored.
43 */
44 public <T extends PersistableBusinessObject> T save(T bo);
45
46 /**
47 * Saves the businessObjects on the list via the persistence layer.
48 *
49 * This will throw an IllegalArgumentException (runtime exception) if any of the objects passed in is not a descendent of
50 * BusinessObject.
51 *
52 * @param businessObjects A List<PersistableBusinessObject> of objects to persist.
53 */
54 public List<? extends PersistableBusinessObject> save(List<? extends PersistableBusinessObject> businessObjects);
55
56 /**
57 * Links up any contained objects, and then Saves the passed in object via the persistence layer.
58 *
59 * This will throw an IllegalArgumentException (runtime exception) if the object passed in is not a descendent of
60 * BusinessObject.
61 *
62 * @param bo A BusinessObject instance or descendent that you wish to be stored.
63 */
64 public PersistableBusinessObject linkAndSave(PersistableBusinessObject bo);
65
66 /**
67 * Links up any contained objects, and Saves the businessObjects on the list via the persistence layer.
68 *
69 * This will throw an IllegalArgumentException (runtime exception) if any of the objects passed in is not a descendent of
70 * BusinessObject.
71 *
72 * @param businessObjects A List<BusinessObject> of objects to persist.
73 *
74 */
75 public List<? extends PersistableBusinessObject> linkAndSave(List<? extends PersistableBusinessObject> businessObjects);
76
77 /**
78 * Retrieves an object instance identified by its primary key. For composite keys, use {@link #findByPrimaryKey(Class, Map)}
79 *
80 * @param clazz
81 * @param primaryKey
82 * @return
83 */
84 public <T extends BusinessObject> T findBySinglePrimaryKey(Class<T> clazz, Object primaryKey);
85
86 /**
87 * Retrieves an object instance identified by its primary keys and values. This can be done by constructing a map where the key
88 * to the map entry is the primary key attribute and the value of the entry being the primary key value. For composite keys,
89 * pass in each primaryKey attribute and its value as a map entry.
90 *
91 * @param clazz
92 * @param primaryKeys
93 * @return
94 */
95 public <T extends BusinessObject> T findByPrimaryKey(Class<T> clazz, Map<String, ?> primaryKeys);
96
97 /**
98 * Retrieves an object instance identified by the class of the given object and the object's primary key values.
99 *
100 * @param object
101 * @return
102 */
103 public PersistableBusinessObject retrieve(PersistableBusinessObject object);
104
105 /**
106 * Retrieves a collection of business objects populated with data, such that each record in the database populates a new object
107 * instance. This will only retrieve business objects by class type.
108 *
109 * @param clazz
110 * @return
111 */
112 public <T extends BusinessObject> Collection<T> findAll(Class<T> clazz);
113
114 /**
115 * Retrieves a collection of business objects populated with data, such that each record in the database populates a new object
116 * instance. This will only retrieve business objects by class type.
117 *
118 * @param clazz
119 * @return
120 */
121 public <T extends BusinessObject> Collection<T> findAllOrderBy( Class<T> clazz, String sortField, boolean sortAscending );
122
123 /**
124 * This method retrieves a collection of business objects populated with data, such that each record in the database populates a
125 * new object instance. This will retrieve business objects by class type and also by criteria passed in as key-value pairs,
126 * specifically attribute name and its expected value.
127 *
128 * @param clazz
129 * @param fieldValues
130 * @return
131 */
132 public <T extends BusinessObject> Collection<T> findMatching(Class<T> clazz, Map<String, ?> fieldValues);
133
134 /**
135 * Finds all entities matching the passed in Rice JPA criteria
136 *
137 * @param <T> the type of the entity that will be returned
138 * @param criteria the criteria to form the query with
139 * @return a Collection (most likely a List) of all matching entities
140 */
141 //public abstract <T extends BusinessObject> Collection<T> findMatching(Criteria criteria);
142
143 /**
144 * This method retrieves a count of the business objects populated with data which match the criteria in the given Map.
145 *
146 * @param clazz
147 * @param fieldValues
148 * @return number of businessObjects of the given class whose fields match the values in the given expected-value Map
149 */
150 public int countMatching(Class clazz, Map<String, ?> fieldValues);
151
152 /**
153 * This method retrieves a count of the business objects populated with data which match both the positive criteria
154 * and the negative criteria in the given Map.
155 *
156 * @param clazz
157 * @param positiveFieldValues
158 * @param negativeFieldValues
159 * @return number of businessObjects of the given class whose fields match the values in the given expected-value Maps
160 */
161 public int countMatching(Class clazz, Map<String, ?> positiveFieldValues, Map<String, ?> negativeFieldValues);
162
163 /**
164 * This method retrieves a collection of business objects populated with data, such that each record in the database populates a
165 * new object instance. This will retrieve business objects by class type and also by criteria passed in as key-value pairs,
166 * specifically attribute name and its expected value. Performs an order by on sort field.
167 *
168 * @param clazz
169 * @param fieldValues
170 * @return
171 */
172 public <T extends BusinessObject> Collection<T> findMatchingOrderBy(Class<T> clazz, Map<String, ?> fieldValues, String sortField, boolean sortAscending);
173
174 /**
175 * Deletes a business object from the database.
176 *
177 * @param bo
178 */
179 public void delete(PersistableBusinessObject bo);
180
181 /**
182 * Deletes each business object in the given List.
183 *
184 * @param boList
185 */
186 public void delete(List<? extends PersistableBusinessObject> boList);
187
188 /**
189 * Deletes the object(s) matching the given field values
190 *
191 * @param clazz
192 * @param fieldValues
193 */
194 public void deleteMatching(Class clazz, Map<String, ?> fieldValues);
195
196 /**
197 *
198 * This method attempts to retrieve the reference from a BO if it exists.
199 *
200 * @param bo - populated BusinessObject instance that includes the referenceName property
201 * @param referenceName - name of the member/property to load
202 * @return A populated object from the DB, if it exists
203 *
204 */
205 public BusinessObject getReferenceIfExists(BusinessObject bo, String referenceName);
206
207 /**
208 *
209 * Updates all KualiUser or Person objects contained within this BO, based on the UserID as the authoritative key. The
210 * appropriate foreign-key field in the BO itself is also updated.
211 *
212 * This allows UserIDs to be entered on forms, and the back-end will link up correctly based on this non-key field.
213 *
214 * @param bo The populated BO (or descendent) instance to be linked & updated
215 *
216 */
217 public void linkUserFields(PersistableBusinessObject bo);
218
219 /**
220 *
221 * Updates all KualiUser or Person objects contained within this BO, based on the UserID as the authoritative key. The
222 * appropriate foreign-key field in the BO itself is also updated.
223 *
224 * This allows UserIDs to be entered on forms, and the back-end will link up correctly based on this non-key field.
225 *
226 * @param bos A List of populated BusinessObject (or descendent) instances to be linked & updated.
227 */
228 public void linkUserFields(List<PersistableBusinessObject> bos);
229
230 /**
231 * Merges the given business object, but tells the ORM that the object is to be treated as Read Only,
232 * and even if it has changes, it will not be persisted to the database
233 *
234 * @param bo the business object to managed
235 * @return the managed copied of the business object
236 */
237 public PersistableBusinessObject manageReadOnly(PersistableBusinessObject bo);
238
239 }
240