1 /**
2 * Copyright 2005-2011 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.datadictionary.DataDictionaryEntry;
20 import org.kuali.rice.krad.datadictionary.ReferenceDefinition;
21 import org.kuali.rice.krad.datadictionary.validation.result.DictionaryValidationResult;
22 import org.kuali.rice.krad.document.Document;
23 import org.kuali.rice.krad.document.TransactionalDocument;
24
25 import java.beans.PropertyDescriptor;
26
27 /**
28 * Defines the API for the validating against the data dictionary.
29 *
30 * @author Kuali Rice Team (rice.collab@kuali.org)
31 */
32 public interface DictionaryValidationService {
33
34 /**
35 * Validates the contents of a document (i.e. attributes within a document) against the data dictionary.
36 *
37 * @param document - document to validate
38 */
39 public void validateDocument(Document document);
40
41 /**
42 * Validates the contents of a document and recursively validates any of its updatable references
43 *
44 * @param document the document
45 * @param maxDepth the maximum numbers of levels to recurse
46 * @param validateRequired whether to validate whether a field is required and is currently blank
47 */
48 public void validateDocumentAndUpdatableReferencesRecursively(Document document, int maxDepth,
49 boolean validateRequired);
50
51 /**
52 * Validates the contents of a document and recursively validates any of its updatable references
53 *
54 * @param document the document
55 * @param maxDepth the maximum numbers of levels to recurse
56 * @param validateRequired whether to validate whether a field is required and is currently blank
57 * @param chompLastLetterSFromCollectionName if true, the error path for any collections encountered will have the
58 * last "s" removed from the collection name if it ends
59 * with the letter "s". If false, this method acts like {@link #validateDocumentAndUpdatableReferencesRecursively(Document,
60 * int, boolean)}
61 */
62 public void validateDocumentAndUpdatableReferencesRecursively(Document document, int maxDepth,
63 boolean validateRequired, boolean chompLastLetterSFromCollectionName);
64
65 /**
66 * Validates the specified attribute of the given document against the data dictionary.
67 *
68 * @param document
69 * @param attributeName
70 * @param errorPrefix
71 */
72 public void validateDocumentAttribute(Document document, String attributeName, String errorPrefix);
73
74 /**
75 * Validates an object using its class name as the entry name to look up its metadata in the dictionary.
76 *
77 * @param object - an object to validate
78 * @return the dictionary validation result object associated with this validation
79 */
80 public DictionaryValidationResult validate(Object object);
81
82 /**
83 * Validates an object using its class name as the entry name to look up its metadata in the dictionary.
84 *
85 * @param object - an object to validate
86 * @param doOptionalProcessing true if the validation should do optional validation (e.g. to check if empty values
87 * are required or not), false otherwise
88 * @return the dictionary validation result object associated with this validation
89 */
90 public DictionaryValidationResult validate(Object object, boolean doOptionalProcessing);
91
92 /**
93 * Validates an object using the passed entry name to look up metadata in the dictionary
94 *
95 * @param object - an object to validate
96 * @param entryName - the dictionary entry name to look up the metadata associated with this object
97 * @return the dictionary validation result object associated with this validation
98 * @since 1.1
99 */
100 public DictionaryValidationResult validate(Object object, String entryName);
101
102 /**
103 * Same as {@link #validate(java.lang.Object, java.lang.String)} except that it provides a boolean parameter for
104 * the
105 * calling method to choose whether to do optional processing (generally to check if blank/empty values are
106 * required
107 * or not).
108 *
109 * @param object - an object to validate
110 * @param entryName - the dictionary entry name to look up the metadata associated with this object
111 * @param doOptionalProcessing true if the validation should do optional validation (e.g. to check if empty values
112 * are required or not), false otherwise
113 * @return the dictionary validation result object associated with this validation
114 * @since 1.1
115 */
116 public DictionaryValidationResult validate(Object object, String entryName, boolean doOptionalProcessing);
117
118 /**
119 * Validates a single attribute on the passed object using the passed entry name to look up
120 * metadata in the dictionary.
121 *
122 * @param object - an object to validate
123 * @param entryName - the dictionary entry name to look up the metadata associated with this object
124 * @param attributeName - the name of the attribute (field) on the object that should be validated
125 * @return the dictionary validation result object associated with this validation
126 * @since 1.1
127 */
128 public DictionaryValidationResult validate(Object object, String entryName, String attributeName);
129
130 /**
131 * Same as {@link #validate(Object, String, String)} except that it provides a boolean parameter for the
132 * calling method to choose whether to do optional processing (generally to check if blank/empty values are
133 * required
134 * or not).
135 *
136 * @param object - an object to validate
137 * @param entryName - the dictionary entry name to look up the metadata associated with this object
138 * @param attributeName - the name of the attribute (field) on the object that should be validated
139 * @param doOptionalProcessing true if the validation should do optional validation (e.g. to check if empty values
140 * are required or not), false otherwise
141 * @return the dictionary validation result object associated with this validation
142 * @since 1.1
143 */
144 public DictionaryValidationResult validate(Object object, String entryName, String attributeName,
145 boolean doOptionalProcessing);
146
147 /**
148 * Same as {@link DictionaryValidationService#validate(Object, String, boolean) except that it provides an explicit
149 * data dictionary
150 * entry to use for the purpose of validation.
151 *
152 * @param object - an object to validate
153 * @param entryName - the dictionary entry name to use in association with error look ups
154 * @param entry - the dictionary entry to use for validation
155 * @param doOptionalProcessing true if the validation should do optional validation (e.g. to check if empty values
156 * are required or not), false otherwise
157 * @return the dictionary validation result object associated with this validation
158 * @since 1.1
159 */
160 public DictionaryValidationResult validate(Object object, String entryName, DataDictionaryEntry entry,
161 boolean doOptionalProcessing);
162
163 /**
164 * Instead of validating an object with dictionary metadata, or validating a specific member of an object by name,
165 * validates a
166 * specific attribute of an object by passing in the attribute value itself. This limits the amount of validation
167 * that can be done
168 * to constraints that directly affect this attribute.
169 *
170 * @param entryName - the dictionary entry name to use in association with error look ups
171 * @param attributeName - the dictionary entry attribute name to use in association with error look ups
172 * @param attributeValue - the value of the attribute being validated
173 */
174 public void validate(String entryName, String attributeName, Object attributeValue);
175
176 /**
177 * Same as {@link #validate(String, String, Object)} except that it provides a boolean parameter for the
178 * calling method to choose whether to do optional processing (generally to check if blank/empty values are
179 * required
180 * or not).
181 *
182 * @param entryName - the dictionary entry name to use in association with error look ups
183 * @param attributeName - the dictionary entry attribute name to use in association with error look ups
184 * @param attributeValue - the value of the attribute being validated
185 * @param doOptionalProcessing - true if the validation should do optional validation (e.g. to check if empty
186 * values
187 * are required or not), false otherwise
188 */
189 public void validate(String entryName, String attributeName, Object attributeValue, boolean doOptionalProcessing);
190
191 /**
192 * Encapsulates <code>{@link #validateBusinessObject(BusinessObject) and returns boolean so one doesn't need to
193 * check the
194 * ErrorMap.Validates the business object primitive attributes against the data dictionary. Adds errors to the map
195 * as they are
196 * encountered.<br/>
197 * <br/>
198 * Makes no error path adjustments
199 *
200 * @param businessObject - business object to validate
201 * @return boolean validOrNot
202 */
203 public boolean isBusinessObjectValid(BusinessObject businessObject);
204
205 /**
206 * Encapsulates <code>{@link #validateBusinessObject(BusinessObject) and returns boolean so one doesn't need to
207 * check the
208 * ErrorMap.Validates the business object primitive attributes against the data dictionary. Adds errors to the map
209 * as they are
210 * encountered.<br/>
211 * <br/>
212 * Makes no error path adjustments
213 *
214 * @param businessObject - business object to validate
215 * @param prefix - error prefix
216 * @return boolean valid or not
217 */
218 public boolean isBusinessObjectValid(BusinessObject businessObject, String prefix);
219
220 /**
221 * Validates the business object primitive attributes against the data dictionary. Adds errors to the map as they
222 * are
223 * encountered.
224 *
225 * @param businessObject - business object to validate
226 * @deprecated since 1.1 - use validate(Object.class) instead
227 */
228 @Deprecated
229 public void validateBusinessObject(BusinessObject businessObject);
230
231 /**
232 * Validates the business object primitive attributes against the data dictionary. Adds errors to the map as they
233 * are
234 * encountered.
235 *
236 * @param businessObject - business object to validate
237 * @param validateRequired - whether to execute required field checks
238 * @deprecated since 1.1 - use validate(Object.class) instead
239 */
240 @Deprecated
241 public void validateBusinessObject(BusinessObject businessObject, boolean validateRequired);
242
243 /**
244 * This method examines the populated BusinessObject bo instance passed in for a member named by the referenceName.
245 * If this
246 * member exists, and if this member is a descendent of BusinessObject, then an existence check proceeds.
247 *
248 * First the foreign keys for this reference are gathered, and then examined to see if they have values. If they do
249 * not have
250 * values, the method ends with a true return value. If they all have values, then an object with those primary
251 * keys
252 * is retrieve
253 * from the database. If one is retrieve, then the reference exists, and True is returned. Otherwise, false is
254 * returned.
255 *
256 * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the
257 * errorMap with no
258 * prefix, other than what has already been pushed onto the errorMap.
259 *
260 * @param bo - The bo whose reference is being tested.
261 * @param reference - The ReferenceDefinition to be existence tested.
262 * @return True if no exceptions occur and the object exists in the db, false otherwise.
263 */
264 public boolean validateReferenceExists(BusinessObject bo, ReferenceDefinition reference);
265
266 /**
267 * This method examines the populated BusinessObject bo instance passed in for a member named by the referenceName.
268 * If this
269 * member exists, and if this member is a descendent of BusinessObject, then an existence check proceeds.
270 *
271 * First the foreign keys for this reference are gathered, and then examined to see if they have values. If they do
272 * not have
273 * values, the method ends with a true return value. If they all have values, then an object with those primary
274 * keys
275 * is retrieve
276 * from the database. If one is retrieve, then the reference exists, and True is returned. Otherwise, false is
277 * returned.
278 *
279 * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the
280 * errorMap with no
281 * prefix, other than what has already been pushed onto the errorMap.
282 *
283 * @param bo - The bo whose reference is being tested.
284 * @param referenceName - The name of the member to be existence tested.
285 * @return True if no exceptions occur and the object exists in the db, false otherwise.
286 */
287 public boolean validateReferenceExists(BusinessObject bo, String referenceName);
288
289 /**
290 * This method retrieves the reference from the DB, and then tests whether the object is active.
291 *
292 * It will return false if there is no activeIndicator field on this object, if the object doesnt exist in the DB,
293 * if the field
294 * doesnt exist or cannot be cast as a boolean, if the field value is null, or if the field value is false.
295 *
296 * It will only return true if the reference bo is present, the field is present, it is a boolean and non-null, and
297 * the value is
298 * true.
299 *
300 * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the
301 * errorMap with no
302 * prefix, other than what has already been pushed onto the errorMap.
303 *
304 * @param bo
305 * @param reference
306 * @return
307 */
308 public boolean validateReferenceIsActive(BusinessObject bo, ReferenceDefinition reference);
309
310 /**
311 * This method retrieves the reference from the DB, and then tests whether the object is active.
312 *
313 * It will return false if there is no activeIndicator field on this object, if the object doesnt exist in the DB,
314 * if the field
315 * doesnt exist or cannot be cast as a boolean, if the field value is null, or if the field value is false.
316 *
317 * It will only return true if the reference bo is present, the field is present, it is a boolean and non-null, and
318 * the value is
319 * true.
320 *
321 * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the
322 * errorMap with no
323 * prefix, other than what has already been pushed onto the errorMap.
324 *
325 * @param bo
326 * @param referenceName
327 * @return
328 */
329 public boolean validateReferenceIsActive(BusinessObject bo, String referenceName);
330
331 /**
332 * This method intelligently tests the designated reference on the bo for both existence and active status, where
333 * appropriate.
334 *
335 * It will not test anything if the foreign-key fields for the given reference arent filled out with values, and it
336 * will not
337 * test active status if the reference doesnt exist.
338 *
339 * Further, it will only test active status where the correct flag is set.
340 *
341 * On failures of either sort, it will put the relevant errors into the GlobalVariables errorMap, and return a
342 * false. If there
343 * are no failures, or nothing can be tested because the foreign-key fields arent fully filled out, it will return
344 * true and add
345 * no errors.
346 *
347 * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the
348 * errorMap with no
349 * prefix, other than what has already been pushed onto the errorMap.
350 *
351 * @param bo - the BusinessObject instance to be tested.
352 * @param reference - the ReferenceDefinition to control the nature of the testing.
353 * @return true or false as per the criteria above
354 */
355 public boolean validateReferenceExistsAndIsActive(BusinessObject bo, ReferenceDefinition reference);
356
357 /**
358 * This method intelligently tests the designated reference on the bo for both existence and active status, where
359 * appropriate.
360 *
361 * It will not test anything if the foreign-key fields for the given reference arent filled out with values, and it
362 * will not
363 * test active status if the reference doesnt exist.
364 *
365 * Note that it will not fail or raise any error if all of the foreign-keys are filled with a value. If this needs
366 * to be tested
367 * (ie, the 'if any field is filled, then all must be filled' rule), you'll have to do that separately.
368 *
369 * Further, it will only test active status where the correct flag is set.
370 *
371 * On failures of either sort, it will put the relevant errors into the GlobalVariables errorMap, and return a
372 * false. If there
373 * are no failures, or nothing can be tested because the foreign-key fields arent fully filled out, it will return
374 * true and add
375 * no errors.
376 *
377 * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the
378 * errorMap with no
379 * prefix, other than what has already been pushed onto the errorMap.
380 *
381 * @param bo - the BusinessObject instance to be tested.
382 * @param referenceName - the member name on the bo to be tested for existence and active-state
383 * @param attributeToHighlightOnFail - the fieldName to highlight with the error message on a failure
384 * @param displayFieldName - the human-readable display name of the failed field, to go in the error message
385 * @return true or false as per the criteria above
386 */
387 public boolean validateReferenceExistsAndIsActive(BusinessObject bo, String referenceName,
388 String attributeToHighlightOnFail, String displayFieldName);
389
390 /**
391 * This method does an existence check against all references of a BusinessObject as defined in the
392 * MaintenanceDocument.xml file
393 * for that business object.
394 *
395 * Appropriate errors will also be placed in the GlobalVariables.ErrorMap.
396 *
397 * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the
398 * errorMap with no
399 * prefix, other than what has already been pushed onto the errorMap.
400 *
401 * @param bo - BusinessObject instance that should be tested
402 * @return true if all passed existence tests, false if any failed
403 */
404 public boolean validateDefaultExistenceChecks(BusinessObject bo);
405
406 /**
407 * Does an existence check against all references configured as a default existence check in the maintenance
408 * document data dictionary file for the given business object
409 *
410 * Appropriate errors will also be placed in the GlobalVariables.ErrorMap.
411 *
412 * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the
413 * errorMap
414 * with no
415 * prefix, other than what has already been pushed onto the errorMap.
416 *
417 * @param bo parent business object instance to retrieve default checks for
418 * @param newCollectionItem new collection line to validate
419 * @param collectionName name of the collection in the parent
420 * @return true if all passed existence tests, false if any failed
421 */
422 public boolean validateDefaultExistenceChecksForNewCollectionItem(BusinessObject bo,
423 BusinessObject newCollectionItem, String collectionName);
424
425 /**
426 * This method does an existence check against all references of a transactionalDocument
427 *
428 * Appropriate errors will also be placed in the GlobalVariables.ErrorMap.
429 *
430 * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the
431 * errorMap
432 * with no
433 * prefix, other than what has already been pushed onto the errorMap.
434 *
435 * @param document document instance that should be tested
436 * @return true if all passed existence tests, false if any failed
437 */
438 public boolean validateDefaultExistenceChecksForTransDoc(TransactionalDocument document);
439
440 /**
441 * This method does an existence check against all references of a transactionalDocument
442 *
443 * Appropriate errors will also be placed in the GlobalVariables.ErrorMap.
444 *
445 * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the
446 * errorMap
447 * with no
448 * prefix, other than what has already been pushed onto the errorMap.
449 *
450 * @param document document instance that should be tested
451 * @param accountingLine that should be tested
452 * @param collectionName that should be tested
453 * @return true if all passed existence tests, false if any failed
454 */
455 public boolean validateDefaultExistenceChecksForNewCollectionItem(TransactionalDocument document,
456 BusinessObject accountingLine, String collectionName);
457
458 /**
459 * @deprecated since 1.1
460 */
461 @Deprecated
462 public void validatePrimitiveFromDescriptor(String entryName, Object object, PropertyDescriptor propertyDescriptor,
463 String errorPrefix, boolean validateRequired);
464 }