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 import net.sf.jguiraffe.transform.ValidationResult;
19
20 /**
21 * <p>
22 * Definition of an interface for accessing fields of a form.
23 * </p>
24 * <p>
25 * A form consists of an arbitrary number of fields, i.e. interaction elements
26 * where the user can enter data. Such a field must be able to interact with the
27 * GUI widget used for data entering. In addition it supports validation of the
28 * entered data and conversion into a target data type.
29 * </p>
30 *
31 * @author Oliver Heger
32 * @version $Id: FieldHandler.java 205 2012-01-29 18:29:57Z oheger $
33 */
34 public interface FieldHandler
35 {
36 /**
37 * Returns the <code>ComponentHandler</code> used by this
38 * <code>FieldHandler</code>. With this handler, the underlying GUI
39 * component can be controlled.
40 *
41 * @return the associated <code>ComponentHandler</code>
42 */
43 ComponentHandler<?> getComponentHandler();
44
45 /**
46 * Returns the data of this field. This is not necessary the same data
47 * object as returned by the <code>ComponentHandler</code>. Instead it
48 * can be the result of a conversion process to transform the data into a
49 * certain target data type. For this conversion to succeed it must be
50 * ensured that this method is only envoked after validation at the field
51 * level has been successfull. The object returned here should be of the
52 * same type as returned by <code>{@link #getType()}</code>.
53 *
54 * @return the data of this field
55 */
56 Object getData();
57
58 /**
59 * Sets the data of this field. An implementation must perform suitable
60 * conversions and then write the data into the associated GUI component.
61 * This is the opposite of <code>{@link #getData()}</code>.
62 *
63 * @param data the data to set
64 */
65 void setData(Object data);
66
67 /**
68 * Validates this field either at the field or the form level. The returned
69 * <code>ValidationResult</code> object contains information if the
70 * field's content is valid or which errors have been found.
71 *
72 * @param phase determines the validation phase
73 * @return an object with the validation results
74 */
75 ValidationResult validate(ValidationPhase phase);
76
77 /**
78 * Returns the data type for this field. Valid user input will be converted
79 * into this data type.
80 *
81 * @return the data type of this field
82 */
83 Class<?> getType();
84
85 /**
86 * Returns the name of the corresponding property in the form bean. This
87 * method can return <b>null</b>, which means that the bean property has
88 * the same name as this field. But by specifying a different name it is
89 * possible to map to more complex bean properties, e.g. mapped or indexed
90 * ones.
91 *
92 * @return the name of the corresponding bean property
93 */
94 String getPropertyName();
95
96 /**
97 * Returns the display name of this field. This should be a plain name in
98 * the language of the current user. The method can return <b>null</b> if
99 * no display name has been set. In this case the form will use the field
100 * name also as display name.
101 *
102 * @return a display name for this field
103 */
104 String getDisplayName();
105 }