001: /*
002: * Copyright 2006-2007 Dan Shellman
003: *
004: * Licensed under the Apache 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.apache.org/licenses/LICENSE-2.0
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.iscreen;
017:
018: import java.util.Locale;
019:
020: /**
021: * This interface represents the main entry point for performing
022: * validations. <br />
023: * <br />
024: * A note about exceptions: <br />
025: * The interface is designed to be used so that checked exceptions are
026: * thrown when a validation failure (or warning) occurs. The debate about
027: * checked versus unchecked exceptions is a long and heated one, but it is
028: * the author's opinion that checked exceptions (in this case, at least) are
029: * the more appropriate approach. However, realizing that a framework may
030: * be used in different ways, and not wishing to force a particular opinion
031: * on developers, the validateObject() methods were added to support
032: * unchecked exceptions. However, there is a known issue with these methods
033: * and the unchecked exception this they throw: these interfaces are mere
034: * copies on top of the checked exceptions calls (i.e. convenience methods),
035: * and as such, will lose the original root exception (and, hence, the
036: * original stack trace). Under normal circumstances, this isn't an issue
037: * (since your users shouldn't care), but it does cause issues for
038: * developers trying to debug. Hence, the "contained" checked exception
039: * can be retrieved from the unchecked exception's API for debugging purposes.
040: *
041: * @author Shellman, Dan
042: */
043: public interface ValidationService {
044: /**
045: * Called to validate an object (typically a JavaBean). If the
046: * object passes validation, nothing occurs (there should be no
047: * side-effects). If one or more Validators find one or more
048: * validation failures, then an exception will be thrown containing
049: * all validations failures found.
050: *
051: * @param obj The object (usually a JavaBean) to validate.
052: *
053: * @exception ValidationException The exception containing any
054: * validation failures.
055: */
056: void validate(Object obj) throws ValidationException;
057:
058: /**
059: * Called to validate an object (typically a JavaBean). If the
060: * object passes validation, nothing occurs (there should be no
061: * side-effects). If one or more Validators find one or more
062: * validation failures, then an exception will be thrown containing
063: * all validations failures found.
064: *
065: * @param obj The object (usually a JavaBean) to validate.
066: * @param locale The locale used for failure message generation.
067: *
068: * @exception ValidationException The exception containing any
069: * validation failures.
070: */
071: void validate(Object obj, Locale locale) throws ValidationException;
072:
073: /**
074: * Identical to validate() except that it throws the unchecked exception
075: * ObjectValidationException instead of a checked exception.
076: *
077: * @param obj The object (usually a JavaBean) to validate.
078: *
079: * @exception ObjectValidationException The exception containing any
080: * validation failures.
081: */
082: void validateObject(Object obj);
083:
084: /**
085: * Identical to validate() except that it throws the unchecked exception
086: * ObjectValidationException instead of a checked exception.
087: *
088: * @param obj The object (usually a JavaBean) to validate.
089: * @param locale The locale used for failure message generation.
090: *
091: * @exception ObjectValidationException The exception containing any
092: * validation failures.
093: */
094: void validateObject(Object obj, Locale locale);
095:
096: /**
097: * The service name (unique id) of the service. This is the fully
098: * qualified name of the Validation Set that this service represents.
099: *
100: * @return Returns the unique service name/id of this service.
101: */
102: String getServiceName();
103:
104: /**
105: * Retrieves an iterator of String values representing the documentation
106: * configured for this validation service (the underlying validation set).
107: *
108: * @return Returns an iterator of Strings representing documentation.
109: */
110: DocumentationIterator getDocumentation();
111: } //end ValidationService
|