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 are responsible of the binding of
21 * form fields to model objects.
22 * </p>
23 * <p>
24 * The main purpose of a form is to gather user input. This input must be stored
25 * somewhere so that it can be accessed by the application in an appropriate and
26 * convenient way. Applications typically use different ways of storing (and
27 * further processing of) user input. An obvious way is to create specialized
28 * Java bean classes whose properties correspond to the fields provided by the
29 * form. That way the data entered into the form can be directly transfered into
30 * Java objects. However, this is only one example, and applications may have
31 * completely different requirements.
32 * </p>
33 * <p>
34 * The purpose of this interface is to serve as an abstraction between form
35 * objects and specific data models used by applications. When a form is asked
36 * to read the data entered by the user or to populate its fields from the
37 * application's model it delegates to a {@code BindingStrategy}. So it can be
38 * independent on the concrete data model (technology) used by the application.
39 * </p>
40 * <p>
41 * This interface defines low-level methods for reading and writing properties
42 * from and to the data model. These are called by the {@link Form} class when
43 * access to the model is needed. All methods defined by this interface
44 * do not throw checked exceptions (depending on the concrete API or technology
45 * a concrete implementation interacts with there will be different types of
46 * exceptions). If something goes wrong, an implementation should throw a
47 * {@link FormRuntimeException}.
48 * </p>
49 *
50 * @author Oliver Heger
51 * @version $Id: BindingStrategy.java 205 2012-01-29 18:29:57Z oheger $
52 */
53 public interface BindingStrategy
54 {
55 /**
56 * Reads the value of the specified property from the given model object.
57 * This method is called when the form is initialized and its fields must be
58 * populated from the underlying data model. An implementation has to obtain
59 * the value of the specified property from the passed in data object. The
60 * value will then be passed to the {@link FieldHandler} of the
61 * corresponding form field.
62 *
63 * @param model the model object
64 * @param propertyName the name of the property in question
65 * @return the current value of this property
66 */
67 Object readProperty(Object model, String propertyName);
68
69 /**
70 * Writes the specified value of a property of the given model object. This
71 * method is called when the user input is evaluated, i.e. the data the user
72 * has entered into the fields needs to be saved in the underlying model. An
73 * implementation has to ensure that the passed in value is correctly
74 * written into the model data object.
75 *
76 * @param model the model object
77 * @param propertyName the name of the property in question
78 * @param value the value to be written into this property
79 */
80 void writeProperty(Object model, String propertyName, Object value);
81 }