001/**
002 * Copyright 2005-2016 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 * Defines methods that a BusinessObjectService must provide
027 * 
028 * @author Kuali Rice Team (rice.collab@kuali.org)
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    public <T extends PersistableBusinessObject> T save(T bo);
041
042    /**
043     * Saves the businessObjects on the list via the persistence layer.
044     * 
045     * This will throw an IllegalArgumentException (runtime exception) if any of the objects passed in is not a descendent of
046     * BusinessObject.
047     * 
048     * @param businessObjects A List<PersistableBusinessObject> of objects to persist.
049     */
050    public List<? extends PersistableBusinessObject> save(List<? extends PersistableBusinessObject> businessObjects);
051
052    /**
053     * Links up any contained objects, and then Saves the passed in object via the persistence layer.
054     * 
055     * This will throw an IllegalArgumentException (runtime exception) if the object passed in is not a descendent of
056     * BusinessObject.
057     * 
058     * @param bo A BusinessObject instance or descendent that you wish to be stored.
059     */
060    public PersistableBusinessObject linkAndSave(PersistableBusinessObject bo);
061
062    /**
063     * Links up any contained objects, and Saves the businessObjects on the list via the persistence layer.
064     * 
065     * This will throw an IllegalArgumentException (runtime exception) if any of the objects passed in is not a descendent of
066     * BusinessObject.
067     * 
068     * @param businessObjects A List<BusinessObject> of objects to persist.
069     * 
070     */
071    public List<? extends PersistableBusinessObject> linkAndSave(List<? extends PersistableBusinessObject> businessObjects);
072
073    /**
074     * Retrieves an object instance identified by its primary key. For composite keys, use {@link #findByPrimaryKey(Class, Map)}
075     * 
076     * @param clazz
077     * @param primaryKey
078     * @return
079     */
080    public <T extends BusinessObject> T findBySinglePrimaryKey(Class<T> clazz, Object primaryKey);
081    
082    /**
083     * Retrieves an object instance identified by its primary keys and values. This can be done by constructing a map where the key
084     * to the map entry is the primary key attribute and the value of the entry being the primary key value. For composite keys,
085     * pass in each primaryKey attribute and its value as a map entry.
086     * 
087     * @param clazz
088     * @param primaryKeys
089     * @return
090     */
091    public <T extends BusinessObject> T findByPrimaryKey(Class<T> clazz, Map<String, ?> primaryKeys);
092
093    /**
094     * Retrieves an object instance identified by the class of the given object and the object's primary key values.
095     * 
096     * @param object
097     * @return
098     */
099    public PersistableBusinessObject retrieve(PersistableBusinessObject object);
100
101    /**
102     * Retrieves a collection of business objects populated with data, such that each record in the database populates a new object
103     * instance. This will only retrieve business objects by class type.
104     * 
105     * @param clazz
106     * @return
107     */
108    public <T extends BusinessObject> Collection<T> findAll(Class<T> clazz);
109
110    /**
111     * Retrieves a collection of business objects populated with data, such that each record in the database populates a new object
112     * instance. This will only retrieve business objects by class type.
113     * 
114     * @param clazz
115     * @return
116     */
117    public <T extends BusinessObject> Collection<T> findAllOrderBy( Class<T> clazz, String sortField, boolean sortAscending );
118    
119    /**
120     * This method retrieves a collection of business objects populated with data, such that each record in the database populates a
121     * new object instance. This will retrieve business objects by class type and also by criteria passed in as key-value pairs,
122     * specifically attribute name and its expected value.
123     * 
124     * @param clazz
125     * @param fieldValues
126     * @return
127     */
128    public <T extends BusinessObject> Collection<T> findMatching(Class<T> clazz, Map<String, ?> fieldValues);
129    
130    /**
131     * Finds all entities matching the passed in Rice JPA criteria
132     * 
133     * @param <T> the type of the entity that will be returned
134     * @param criteria the criteria to form the query with
135     * @return a Collection (most likely a List) of all matching entities 
136     */
137    //public abstract <T extends BusinessObject> Collection<T> findMatching(Criteria criteria);
138
139    /**
140     * This method retrieves a count of the business objects populated with data which match the criteria in the given Map.
141     * 
142     * @param clazz
143     * @param fieldValues
144     * @return number of businessObjects of the given class whose fields match the values in the given expected-value Map
145     */
146    public int countMatching(Class clazz, Map<String, ?> fieldValues);
147
148    /**
149     * This method retrieves a count of the business objects populated with data which match both the positive criteria 
150     * and the negative criteria in the given Map.
151     * 
152     * @param clazz
153     * @param positiveFieldValues
154     * @param negativeFieldValues
155     * @return number of businessObjects of the given class whose fields match the values in the given expected-value Maps
156     */
157    public int countMatching(Class clazz, Map<String, ?> positiveFieldValues, Map<String, ?> negativeFieldValues);
158    
159    /**
160     * This method retrieves a collection of business objects populated with data, such that each record in the database populates a
161     * new object instance. This will retrieve business objects by class type and also by criteria passed in as key-value pairs,
162     * specifically attribute name and its expected value. Performs an order by on sort field.
163     * 
164     * @param clazz
165     * @param fieldValues
166     * @return
167     */
168    public <T extends BusinessObject> Collection<T> findMatchingOrderBy(Class<T> clazz, Map<String, ?> fieldValues, String sortField, boolean sortAscending);
169
170    /**
171     * Deletes a business object from the database.
172     * 
173     * @param bo
174     */
175    public void delete(PersistableBusinessObject bo);
176
177    /**
178     * Deletes each business object in the given List.
179     * 
180     * @param boList
181     */
182    public void delete(List<? extends PersistableBusinessObject> boList);
183
184    /**
185     * Deletes the object(s) matching the given field values
186     * 
187     * @param clazz
188     * @param fieldValues
189     */
190    public void deleteMatching(Class clazz, Map<String, ?> fieldValues);
191
192    /**
193     * 
194     * This method attempts to retrieve the reference from a BO if it exists.
195     * 
196     * @param bo - populated BusinessObject instance that includes the referenceName property
197     * @param referenceName - name of the member/property to load
198     * @return A populated object from the DB, if it exists
199     * 
200     */
201    public BusinessObject getReferenceIfExists(BusinessObject bo, String referenceName);
202
203    /**
204     * 
205     * Updates all KualiUser or Person objects contained within this BO, based on the UserID as the authoritative key. The
206     * appropriate foreign-key field in the BO itself is also updated.
207     * 
208     * This allows UserIDs to be entered on forms, and the back-end will link up correctly based on this non-key field.
209     * 
210     * @param bo The populated BO (or descendent) instance to be linked & updated
211     * 
212     */
213    public void linkUserFields(PersistableBusinessObject bo);
214
215    /**
216     * 
217     * Updates all KualiUser or Person objects contained within this BO, based on the UserID as the authoritative key. The
218     * appropriate foreign-key field in the BO itself is also updated.
219     * 
220     * This allows UserIDs to be entered on forms, and the back-end will link up correctly based on this non-key field.
221     * 
222     * @param bos A List of populated BusinessObject (or descendent) instances to be linked & updated.
223     */
224    public void linkUserFields(List<PersistableBusinessObject> bos);
225    
226    /**
227     * Merges the given business object, but tells the ORM that the object is to be treated as Read Only,
228     * and even if it has changes, it will not be persisted to the database 
229     * 
230     * @param bo the business object to managed
231     * @return the managed copied of the business object
232     */
233    public PersistableBusinessObject manageReadOnly(PersistableBusinessObject bo);
234
235}
236