001: /*
002: * Copyright 2005-2007 The Kuali Foundation.
003: *
004: * Licensed under the Educational Community License, Version 1.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/ecl1.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.core.service;
017:
018: import java.util.Collection;
019: import java.util.List;
020: import java.util.Map;
021:
022: import org.kuali.core.bo.PersistableBusinessObject;
023:
024: /**
025: * This interface defines methods that a BusinessObjectService must provide.
026: *
027: *
028: */
029: public interface BusinessObjectService {
030:
031: /**
032: * Saves the passed in object via the persistence layer.
033: *
034: * This will throw an IllegalArgumentException (runtime exception) if the object passed in is not a descendent of
035: * BusinessObject.
036: *
037: * @param bo A BusinessObject instance or descendent that you wish to be stored.
038: *
039: */
040: public void save(PersistableBusinessObject 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<BusinessObject> of objects to persist.
049: *
050: */
051: public void save(List businessObjects);
052:
053: /**
054: * Links up any contained objects, and then Saves the passed in object via the persistence layer.
055: *
056: * This will throw an IllegalArgumentException (runtime exception) if the object passed in is not a descendent of
057: * BusinessObject.
058: *
059: * @param bo A BusinessObject instance or descendent that you wish to be stored.
060: *
061: */
062: public void linkAndSave(PersistableBusinessObject bo);
063:
064: /**
065: * Links up any contained objects, and Saves the businessObjects on the list via the persistence layer.
066: *
067: * This will throw an IllegalArgumentException (runtime exception) if any of the objects passed in is not a descendent of
068: * BusinessObject.
069: *
070: * @param businessObjects A List<BusinessObject> of objects to persist.
071: *
072: */
073: public void linkAndSave(
074: List<PersistableBusinessObject> businessObjects);
075:
076: /**
077: * Retrieves an object instance identified by its primary keys and values. This can be done by constructing a map where the key
078: * to the map entry is the primary key attribute and the value of the entry being the primary key value. For composite keys,
079: * pass in each primaryKey attribute and its value as a map entry.
080: *
081: * @param clazz
082: * @param primaryKeys
083: * @return
084: */
085: public PersistableBusinessObject findByPrimaryKey(Class clazz,
086: Map primaryKeys);
087:
088: /**
089: * Retrieves an object instance identified by the class of the given object and the object's primary key values.
090: *
091: * @param object
092: * @return
093: */
094: public PersistableBusinessObject retrieve(
095: PersistableBusinessObject object);
096:
097: /**
098: * Retrieves a collection of business objects populated with data, such that each record in the database populates a new object
099: * instance. This will only retrieve business objects by class type.
100: *
101: * @param clazz
102: * @return
103: */
104: public Collection findAll(Class clazz);
105:
106: /**
107: * This method retrieves a collection of business objects populated with data, such that each record in the database populates a
108: * new object instance. This will retrieve business objects by class type and also by criteria passed in as key-value pairs,
109: * specifically attribute name and its expected value.
110: *
111: * @param clazz
112: * @param fieldValues
113: * @return
114: */
115: public Collection findMatching(Class clazz, Map fieldValues);
116:
117: /**
118: * This method retrieves a count of the business objects populated with data which match the criteria in the given Map.
119: *
120: * @param clazz
121: * @param fieldValues
122: * @return number of businessObjects of the given class whose fields match the values in the given expected-value Map
123: */
124: public int countMatching(Class clazz, Map fieldValues);
125:
126: /**
127: * This method retrieves a count of the business objects populated with data which match both the positive criteria
128: * and the negative criteria in the given Map.
129: *
130: * @param clazz
131: * @param positiveFieldValues
132: * @param negativeFieldValues
133: * @return number of businessObjects of the given class whose fields match the values in the given expected-value Maps
134: */
135: public int countMatching(Class clazz, Map positiveFieldValues,
136: Map negativeFieldValues);
137:
138: /**
139: * This method retrieves a collection of business objects populated with data, such that each record in the database populates a
140: * new object instance. This will retrieve business objects by class type and also by criteria passed in as key-value pairs,
141: * specifically attribute name and its expected value. Performs an order by on sort field.
142: *
143: * @param clazz
144: * @param fieldValues
145: * @return
146: */
147: public Collection findMatchingOrderBy(Class clazz, Map fieldValues,
148: String sortField, boolean sortAscending);
149:
150: /**
151: * Deletes a business object from the database.
152: *
153: * @param bo
154: */
155: public void delete(PersistableBusinessObject bo);
156:
157: /**
158: * Deletes each business object in the given List.
159: *
160: * @param boList
161: */
162: public void delete(List<PersistableBusinessObject> boList);
163:
164: /**
165: * Deletes the object(s) matching the given field values
166: *
167: * @param clazz
168: * @param fieldValues
169: */
170: public void deleteMatching(Class clazz, Map fieldValues);
171:
172: /**
173: *
174: * This method attempts to retrieve the reference from a BO if it exists.
175: *
176: * @param bo - populated BusinessObject instance that includes the referenceName property
177: * @param referenceName - name of the member/property to load
178: * @return A populated object from the DB, if it exists
179: *
180: */
181: public PersistableBusinessObject getReferenceIfExists(
182: PersistableBusinessObject bo, String referenceName);
183:
184: /**
185: *
186: * Updates all KualiUser or UniversalUser objects contained within this BO, based on the UserID as the authoritative key. The
187: * appropriate foreign-key field in the BO itself is also updated.
188: *
189: * This allows UserIDs to be entered on forms, and the back-end will link up correctly based on this non-key field.
190: *
191: * @param bo The populated BO (or descendent) instance to be linked & updated
192: *
193: */
194: public void linkUserFields(PersistableBusinessObject bo);
195:
196: /**
197: *
198: * Updates all KualiUser or UniversalUser objects contained within this BO, based on the UserID as the authoritative key. The
199: * appropriate foreign-key field in the BO itself is also updated.
200: *
201: * This allows UserIDs to be entered on forms, and the back-end will link up correctly based on this non-key field.
202: *
203: * @param bos A List of populated BusinessObject (or descendent) instances to be linked & updated.
204: */
205: public void linkUserFields(List<PersistableBusinessObject> bos);
206:
207: }
|