001 /**
002 * Copyright 2005-2014 The Kuali Foundation
003 *
004 * Licensed under the Educational Community License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.opensource.org/licenses/ecl2.php
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.kuali.rice.krad.service;
017
018 import org.kuali.rice.krad.bo.BusinessObject;
019 import org.kuali.rice.krad.bo.PersistableBusinessObject;
020
021 import java.util.Collection;
022 import java.util.List;
023 import java.util.Map;
024
025 /**
026 * This interface defines methods that a BusinessObjectService must provide.
027 *
028 *
029 */
030 public interface BusinessObjectService {
031
032 /**
033 * Saves the passed in object via the persistence layer.
034 *
035 * This will throw an IllegalArgumentException (runtime exception) if the object passed in is not a descendent of
036 * BusinessObject.
037 *
038 * @param bo A BusinessObject instance or descendent that you wish to be stored.
039 *
040 */
041 public <T extends PersistableBusinessObject> T save(T bo);
042
043 /**
044 * Saves the businessObjects on the list via the persistence layer.
045 *
046 * This will throw an IllegalArgumentException (runtime exception) if any of the objects passed in is not a descendent of
047 * BusinessObject.
048 *
049 * @param businessObjects A List<PersistableBusinessObject> of objects to persist.
050 *
051 */
052 public List<? extends PersistableBusinessObject> save(List<? extends PersistableBusinessObject> businessObjects);
053
054 /**
055 * Links up any contained objects, and then Saves the passed in object via the persistence layer.
056 *
057 * This will throw an IllegalArgumentException (runtime exception) if the object passed in is not a descendent of
058 * BusinessObject.
059 *
060 * @param bo A BusinessObject instance or descendent that you wish to be stored.
061 *
062 */
063 public PersistableBusinessObject linkAndSave(PersistableBusinessObject bo);
064
065 /**
066 * Links up any contained objects, and Saves the businessObjects on the list via the persistence layer.
067 *
068 * This will throw an IllegalArgumentException (runtime exception) if any of the objects passed in is not a descendent of
069 * BusinessObject.
070 *
071 * @param businessObjects A List<BusinessObject> of objects to persist.
072 *
073 */
074 public List<? extends PersistableBusinessObject> linkAndSave(List<? extends PersistableBusinessObject> businessObjects);
075
076 /**
077 * Retrieves an object instance identified by its primary key. For composite keys, use {@link #findByPrimaryKey(Class, Map)}
078 *
079 * @param clazz
080 * @param primaryKey
081 * @return
082 */
083 public <T extends BusinessObject> T findBySinglePrimaryKey(Class<T> clazz, Object primaryKey);
084
085 /**
086 * Retrieves an object instance identified by its primary keys and values. This can be done by constructing a map where the key
087 * to the map entry is the primary key attribute and the value of the entry being the primary key value. For composite keys,
088 * pass in each primaryKey attribute and its value as a map entry.
089 *
090 * @param clazz
091 * @param primaryKeys
092 * @return
093 */
094 public <T extends BusinessObject> T findByPrimaryKey(Class<T> clazz, Map<String, ?> primaryKeys);
095
096 /**
097 * Retrieves an object instance identified by the class of the given object and the object's primary key values.
098 *
099 * @param object
100 * @return
101 */
102 public PersistableBusinessObject retrieve(PersistableBusinessObject object);
103
104 /**
105 * Retrieves a collection of business objects populated with data, such that each record in the database populates a new object
106 * instance. This will only retrieve business objects by class type.
107 *
108 * @param clazz
109 * @return
110 */
111 public <T extends BusinessObject> Collection<T> findAll(Class<T> clazz);
112
113 /**
114 * Retrieves a collection of business objects populated with data, such that each record in the database populates a new object
115 * instance. This will only retrieve business objects by class type.
116 *
117 * @param clazz
118 * @return
119 */
120 public <T extends BusinessObject> Collection<T> findAllOrderBy( Class<T> clazz, String sortField, boolean sortAscending );
121
122 /**
123 * This method retrieves a collection of business objects populated with data, such that each record in the database populates a
124 * new object instance. This will retrieve business objects by class type and also by criteria passed in as key-value pairs,
125 * specifically attribute name and its expected value.
126 *
127 * @param clazz
128 * @param fieldValues
129 * @return
130 */
131 public <T extends BusinessObject> Collection<T> findMatching(Class<T> clazz, Map<String, ?> fieldValues);
132
133 /**
134 * Finds all entities matching the passed in Rice JPA criteria
135 *
136 * @param <T> the type of the entity that will be returned
137 * @param criteria the criteria to form the query with
138 * @return a Collection (most likely a List) of all matching entities
139 */
140 //public abstract <T extends BusinessObject> Collection<T> findMatching(Criteria criteria);
141
142 /**
143 * This method retrieves a count of the business objects populated with data which match the criteria in the given Map.
144 *
145 * @param clazz
146 * @param fieldValues
147 * @return number of businessObjects of the given class whose fields match the values in the given expected-value Map
148 */
149 public int countMatching(Class clazz, Map<String, ?> fieldValues);
150
151 /**
152 * This method retrieves a count of the business objects populated with data which match both the positive criteria
153 * and the negative criteria in the given Map.
154 *
155 * @param clazz
156 * @param positiveFieldValues
157 * @param negativeFieldValues
158 * @return number of businessObjects of the given class whose fields match the values in the given expected-value Maps
159 */
160 public int countMatching(Class clazz, Map<String, ?> positiveFieldValues, Map<String, ?> negativeFieldValues);
161
162 /**
163 * This method retrieves a collection of business objects populated with data, such that each record in the database populates a
164 * new object instance. This will retrieve business objects by class type and also by criteria passed in as key-value pairs,
165 * specifically attribute name and its expected value. Performs an order by on sort field.
166 *
167 * @param clazz
168 * @param fieldValues
169 * @return
170 */
171 public <T extends BusinessObject> Collection<T> findMatchingOrderBy(Class<T> clazz, Map<String, ?> fieldValues, String sortField, boolean sortAscending);
172
173 /**
174 * Deletes a business object from the database.
175 *
176 * @param bo
177 */
178 public void delete(PersistableBusinessObject bo);
179
180 /**
181 * Deletes each business object in the given List.
182 *
183 * @param boList
184 */
185 public void delete(List<? extends PersistableBusinessObject> boList);
186
187 /**
188 * Deletes the object(s) matching the given field values
189 *
190 * @param clazz
191 * @param fieldValues
192 */
193 public void deleteMatching(Class clazz, Map<String, ?> fieldValues);
194
195 /**
196 *
197 * This method attempts to retrieve the reference from a BO if it exists.
198 *
199 * @param bo - populated BusinessObject instance that includes the referenceName property
200 * @param referenceName - name of the member/property to load
201 * @return A populated object from the DB, if it exists
202 *
203 */
204 public BusinessObject getReferenceIfExists(BusinessObject bo, String referenceName);
205
206 /**
207 *
208 * Updates all KualiUser or Person objects contained within this BO, based on the UserID as the authoritative key. The
209 * appropriate foreign-key field in the BO itself is also updated.
210 *
211 * This allows UserIDs to be entered on forms, and the back-end will link up correctly based on this non-key field.
212 *
213 * @param bo The populated BO (or descendent) instance to be linked & updated
214 *
215 */
216 public void linkUserFields(PersistableBusinessObject bo);
217
218 /**
219 *
220 * Updates all KualiUser or Person objects contained within this BO, based on the UserID as the authoritative key. The
221 * appropriate foreign-key field in the BO itself is also updated.
222 *
223 * This allows UserIDs to be entered on forms, and the back-end will link up correctly based on this non-key field.
224 *
225 * @param bos A List of populated BusinessObject (or descendent) instances to be linked & updated.
226 */
227 public void linkUserFields(List<PersistableBusinessObject> bos);
228
229 /**
230 * Merges the given business object, but tells the ORM that the object is to be treated as Read Only,
231 * and even if it has changes, it will not be persisted to the database
232 *
233 * @param bo the business object to managed
234 * @return the managed copied of the business object
235 */
236 public PersistableBusinessObject manageReadOnly(PersistableBusinessObject bo);
237
238 }
239