001/**
002 * Copyright 2005-2015 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 */
016package org.kuali.rice.krad.service;
017
018import org.kuali.rice.krad.bo.BusinessObject;
019import org.kuali.rice.krad.bo.PersistableBusinessObject;
020
021import java.util.Collection;
022import java.util.List;
023import java.util.Map;
024
025/**
026 * This interface defines methods that a BusinessObjectService must provide.
027 * 
028 * 
029 */
030public 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