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 org.kuali.core.bo.BusinessObject;
019: import org.kuali.core.bo.PersistableBusinessObject;
020: import org.kuali.core.datadictionary.ApcRuleDefinition;
021: import org.kuali.core.datadictionary.ReferenceDefinition;
022: import org.kuali.core.document.Document;
023:
024: /**
025: * Defines the API for the validating against the data dictionary.
026: *
027: *
028: */
029: public interface DictionaryValidationService {
030:
031: /**
032: * Validates the contents of a document (i.e. attributes within a document) against the data dictionary.
033: *
034: * @param document - document to validate
035: */
036: public void validateDocument(Document document);
037:
038: /**
039: * Validates the contents of a document (i.e. attributes within a document) against the data dictionary. Recursively checks
040: * business objects of the document.
041: *
042: * @param document - document to validate
043: * @param depth - Specify how deep the recrusion should go (0 based). If a negative number is supplied, it's infinite.
044: *
045: * @deprecated Use {@link #validateDocumentAndUpdatableReferencesRecursively(Document, int, boolean)}
046: */
047: @Deprecated
048: public void validateDocumentRecursively(Document document, int depth);
049:
050: /**
051: * Validates the contents of a document and recursively validates any of its updatable references
052: *
053: * @param document the document
054: * @param maxDepth the maximum numbers of levels to recurse
055: * @param validateRequired whether to validate whether a field is required and is currently blank
056: */
057: public void validateDocumentAndUpdatableReferencesRecursively(
058: Document document, int maxDepth, boolean validateRequired);
059:
060: /**
061: * Validates the specified attribute of the given document against the data dictionary.
062: *
063: * @param document
064: * @param attributeName
065: * @param errorPrefix
066: */
067: public void validateDocumentAttribute(Document document,
068: String attributeName, String errorPrefix);
069:
070: /**
071: * Validates the business object primitive attributes against the data dictionary. Adds errors to the map as they are
072: * encountered.
073: *
074: * @param businessObject - business object to validate
075: */
076: public void validateBusinessObject(
077: PersistableBusinessObject businessObject);
078:
079: /**
080: * Validates the business object primitive attributes against the data dictionary. Adds errors to the map as they are
081: * encountered.
082: *
083: * @param businessObject - business object to validate
084: * @param validateRequired - whether to execute required field checks
085: */
086: public void validateBusinessObject(
087: PersistableBusinessObject businessObject,
088: boolean validateRequired);
089:
090: /**
091: * Encapsulates <code>{@link #validateBusinessObject(BusinessObject) and returns boolean so one doesn't need to check the
092: * ErrorMap.Validates the business object primitive attributes against the data dictionary. Adds errors to the map as they are
093: * encountered.<br/>
094: * <br/>
095: * Makes no error path adjustments
096: *
097: * @param businessObject - business object to validate
098: * @return boolean validOrNot
099: */
100: public boolean isBusinessObjectValid(
101: PersistableBusinessObject businessObject);
102:
103: /**
104: * Encapsulates <code>{@link #validateBusinessObject(BusinessObject) and returns boolean so one doesn't need to check the
105: * ErrorMap.Validates the business object primitive attributes against the data dictionary. Adds errors to the map as they are
106: * encountered.<br/>
107: * <br/>
108: * Makes no error path adjustments
109: *
110: * @param businessObject - business object to validate
111: * @param prefix - error prefix
112: * @return boolean valid or not
113: */
114: public boolean isBusinessObjectValid(
115: PersistableBusinessObject businessObject, String prefix);
116:
117: /**
118: * Validates the business object against the dictionary, uses reflection to get any child business objects, and recursively
119: * calls back. Adds errors to the map as they are encountered.
120: *
121: * @param businessObject - business object to validate
122: * @param depth - Specify how deep the recrusion should go (0 based). If a negative number is supplied, it's infinite.
123: */
124: public void validateBusinessObjectsRecursively(
125: PersistableBusinessObject businessObject, int depth);
126:
127: /**
128: * Validates an attribute of a given class for proper min, max length, syntax, and required.
129: *
130: * @param entryName - name of the dd entry
131: * @param attributeName - name of attribute in the bo class
132: * @param attributeValue - current value to validate
133: * @param errorKey - key to place to errors under
134: */
135: public void validateAttributeFormat(String entryName,
136: String attributeName, String attributeValue, String errorKey);
137:
138: /**
139: * Validates an attribute of a given class for required check.
140: *
141: * @param entryName - name of the dd entry
142: * @param attributeName - name of attribute in the bo class
143: * @param attributeValue - current value to validate
144: * @param errorKey - key to place to errors under
145: */
146: public void validateAttributeRequired(String entryName,
147: String attributeName, Object attributeValue,
148: Boolean forMaintenance, String errorKey);
149:
150: /**
151: *
152: * This method examines the populated BusinessObject bo instance passed in for a member named by the referenceName. If this
153: * member exists, and if this member is a descendent of BusinessObject, then an existence check proceeds.
154: *
155: * First the foreign keys for this reference are gathered, and then examined to see if they have values. If they do not have
156: * values, the method ends with a true return value. If they all have values, then an object with those primary keys is retrieve
157: * from the database. If one is retrieve, then the reference exists, and True is returned. Otherwise, false is returned.
158: *
159: * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the errorMap with no
160: * prefix, other than what has already been pushed onto the errorMap.
161: *
162: * @param bo - The bo whose reference is being tested.
163: * @param reference - The ReferenceDefinition to be existence tested.
164: * @return True if no exceptions occur and the object exists in the db, false otherwise.
165: *
166: */
167: public boolean validateReferenceExists(
168: PersistableBusinessObject bo, ReferenceDefinition reference);
169:
170: /**
171: *
172: * This method examines the populated BusinessObject bo instance passed in for a member named by the referenceName. If this
173: * member exists, and if this member is a descendent of BusinessObject, then an existence check proceeds.
174: *
175: * First the foreign keys for this reference are gathered, and then examined to see if they have values. If they do not have
176: * values, the method ends with a true return value. If they all have values, then an object with those primary keys is retrieve
177: * from the database. If one is retrieve, then the reference exists, and True is returned. Otherwise, false is returned.
178: *
179: * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the errorMap with no
180: * prefix, other than what has already been pushed onto the errorMap.
181: *
182: * @param bo - The bo whose reference is being tested.
183: * @param referenceName - The name of the member to be existence tested.
184: * @return True if no exceptions occur and the object exists in the db, false otherwise.
185: *
186: */
187: public boolean validateReferenceExists(
188: PersistableBusinessObject bo, String referenceName);
189:
190: /**
191: *
192: * This method retrieves the reference from the DB, and then tests whether the object is active.
193: *
194: * It will return false if there is no activeIndicator field on this object, if the object doesnt exist in the DB, if the field
195: * doesnt exist or cannot be cast as a boolean, if the field value is null, or if the field value is false.
196: *
197: * It will only return true if the reference bo is present, the field is present, it is a boolean and non-null, and the value is
198: * true.
199: *
200: * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the errorMap with no
201: * prefix, other than what has already been pushed onto the errorMap.
202: *
203: * @param bo
204: * @param reference
205: * @return
206: *
207: */
208: public boolean validateReferenceIsActive(
209: PersistableBusinessObject bo, ReferenceDefinition reference);
210:
211: /**
212: *
213: * This method retrieves the reference from the DB, and then tests whether the object is active.
214: *
215: * It will return false if there is no activeIndicator field on this object, if the object doesnt exist in the DB, if the field
216: * doesnt exist or cannot be cast as a boolean, if the field value is null, or if the field value is false.
217: *
218: * It will only return true if the reference bo is present, the field is present, it is a boolean and non-null, and the value is
219: * true.
220: *
221: * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the errorMap with no
222: * prefix, other than what has already been pushed onto the errorMap.
223: *
224: * @param bo
225: * @param referenceName
226: * @param activeIndicatorAttributeName
227: * @param activeIndicatorReversed
228: * @return
229: *
230: */
231: public boolean validateReferenceIsActive(
232: PersistableBusinessObject bo, String referenceName,
233: String activeIndicatorAttributeName,
234: boolean activeIndicatorReversed);
235:
236: /**
237: *
238: * This method intelligently tests the designated reference on the bo for both existence and active status, where appropriate.
239: *
240: * It will not test anything if the foreign-key fields for the given reference arent filled out with values, and it will not
241: * test active status if the reference doesnt exist.
242: *
243: * Further, it will only test active status where the correct flag is set.
244: *
245: * On failures of either sort, it will put the relevant errors into the GlobalVariables errorMap, and return a false. If there
246: * are no failures, or nothing can be tested because the foreign-key fields arent fully filled out, it will return true and add
247: * no errors.
248: *
249: * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the errorMap with no
250: * prefix, other than what has already been pushed onto the errorMap.
251: *
252: * @param bo - the BusinessObject instance to be tested.
253: * @param reference - the ReferenceDefinition to control the nature of the testing.
254: * @return true or false as per the criteria above
255: *
256: */
257: public boolean validateReferenceExistsAndIsActive(
258: PersistableBusinessObject bo, ReferenceDefinition reference);
259:
260: /**
261: *
262: * This method intelligently tests the designated reference on the bo for both existence and active status, where appropriate.
263: *
264: * It will not test anything if the foreign-key fields for the given reference arent filled out with values, and it will not
265: * test active status if the reference doesnt exist.
266: *
267: * Note that it will not fail or raise any error if all of the foreign-keys are filled with a value. If this needs to be tested
268: * (ie, the 'if any field is filled, then all must be filled' rule), you'll have to do that separately.
269: *
270: * Further, it will only test active status where the correct flag is set.
271: *
272: * On failures of either sort, it will put the relevant errors into the GlobalVariables errorMap, and return a false. If there
273: * are no failures, or nothing can be tested because the foreign-key fields arent fully filled out, it will return true and add
274: * no errors.
275: *
276: * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the errorMap with no
277: * prefix, other than what has already been pushed onto the errorMap.
278: *
279: * @param bo - the BusinessObject instance to be tested.
280: * @param referenceName - the member name on the bo to be tested for existence and active-state
281: * @param activeIndicatorAttributeName - the name on the class of the referenceName member to indicate active status
282: * @param activeIndicatorReversed - a flag to indicate if the flag means closed or inactive, rather than active
283: * @param activeIndicatorSet - a flag to control whether active state testing happens at all
284: * @param attributeToHighlightOnFail - the fieldName to highlight with the error message on a failure
285: * @param displayFieldName - the human-readable display name of the failed field, to go in the error message
286: * @return true or false as per the criteria above
287: */
288: public boolean validateReferenceExistsAndIsActive(
289: PersistableBusinessObject bo, String referenceName,
290: String activeIndicatorAttributeName,
291: boolean activeIndicatorReversed,
292: boolean activeIndicatorSet,
293: String attributeToHighlightOnFail, String displayFieldName);
294:
295: /**
296: *
297: * This method does an existence check against all references of a BusinessObject as defined in the MaintenanceDocument.xml file
298: * for that business object.
299: *
300: * Appropriate errors will also be placed in the GlobalVariables.ErrorMap.
301: *
302: * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the errorMap with no
303: * prefix, other than what has already been pushed onto the errorMap.
304: *
305: * @param bo - BusinessObject instance that should be tested
306: * @return true if all passed existence tests, false if any failed
307: *
308: */
309: public boolean validateDefaultExistenceChecks(
310: PersistableBusinessObject bo);
311:
312: /**
313: *
314: * This method applies a specific rule against the given BusinessObject as defined in the MaintenanceDocument.xml file.
315: *
316: * Appropriate errors will also be placed in the GlobalVariables.ErrorMap.
317: *
318: * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the errorMap with no
319: * prefix, other than what has already been pushed onto the errorMap.
320: *
321: * @param bo
322: * @param apcRule
323: * @return true if rule passes
324: */
325: public boolean validateApcRule(PersistableBusinessObject bo,
326: ApcRuleDefinition apcRule);
327:
328: /**
329: * This method applies all rules against the given BusinessObject as defined in the MaintenanceDocument.xml file.
330: *
331: * Appropriate errors will also be placed in the GlobalVariables.ErrorMap.
332: *
333: * This method assumes that you already have the errorPath set exactly as desired, and adds new errors to the errorMap with no
334: * prefix, other than what has already been pushed onto the errorMap.
335: *
336: * @param bo
337: * @return true if rule passes
338: */
339: public boolean validateApcRules(PersistableBusinessObject bo);
340: }
|