1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache 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.apache.org/licenses/LICENSE-2.0
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 net.sf.jguiraffe.gui.forms;
17
18 /**
19 * <p>
20 * Definition of an interface for objects that can validate forms.
21 * </p>
22 * <p>
23 * While a normal validator can check only single fields of a form a {@code
24 * FormValidator} can deal with a form as a whole and thus can evaluate complex
25 * conditions and dependencies between the single elements.
26 * </p>
27 * <p>
28 * This kind of validation takes places only after validation on both the field
29 * and form level have succeeded. Validations performed by {@code FormValidator}
30 * implementations are logically related to form level validations. The main
31 * difference is that a <code>FormValidator</code> can access all form fields at
32 * once and so is able to check relations between fields, too.
33 * </p>
34 * <p>
35 * Validation of a form as a whole is very specific and strongly depends on the
36 * data fields contained in the form and its model. So there is no default base
37 * implementation of this interface. A concrete implementation can access the
38 * whole data that was entered into the form - either by querying the
39 * {@link FieldHandler} objects of the form or by calling the
40 * {@link Form#readFields(Object)} method passing in an appropriate data object
41 * - and perform arbitrary checks.
42 * </p>
43 *
44 * @author Oliver Heger
45 * @version $Id: FormValidator.java 205 2012-01-29 18:29:57Z oheger $
46 */
47 public interface FormValidator
48 {
49 /**
50 * Validates the specified form. When this method is invoked by the form
51 * framework it is guaranteed that field and form level validation have
52 * passed. Thus all {@link FieldHandler} objects contained in the form have
53 * been initialized with the current data entered by the user. One way to
54 * obtain this data is by calling {@code getData()} on a {@code
55 * FieldHandler}. An alternative is to call {@code readFields()} on the
56 * {@code Form} object and let the data be copied into a corresponding model
57 * object. (This model object must of course be compatible with the
58 * {@link BindingStrategy} used by the {@code Form}.
59 *
60 * @param form the form object to be validated
61 * @return an object with validation results
62 */
63 FormValidatorResults isValid(Form form);
64 }