1 /***
2 * Copyright (C) 2006 Philipp Mpalampanis
3 *
4 * License: MPL 1.1/GPL 2.0/LGPL 2.1
5 *
6 * The contents of this file are subject to the Mozilla Public License Version
7 * 1.1 (the "License"); you may not use this file except in compliance with
8 * the License. You may obtain a copy of the License at
9 * http://www.mozilla.org/MPL/
10 *
11 * Software distributed under the License is distributed on an "AS IS" basis,
12 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
13 * for the specific language governing rights and limitations under the
14 * License.
15 *
16 * Alternatively, the contents of this file may be used under the terms of
17 * either the GNU General Public License Version 2 or later (the "GPL"), or
18 * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
19 * in which case the provisions of the GPL or the LGPL are applicable instead
20 * of those above. If you wish to allow use of your version of this file only
21 * under the terms of either the GPL or the LGPL, and not to allow others to
22 * use your version of this file under the terms of the MPL, indicate your
23 * decision by deleting the provisions above and replace them with the notice
24 * and other provisions required by the GPL or the LGPL. If you do not delete
25 * the provisions above, a recipient may use your version of this file under
26 * the terms of any one of the MPL, the GPL or the LGPL.
27 */
28
29 package net.sf.echobinding.binding;
30
31 import java.util.Set;
32
33 import net.sf.echobinding.decorator.Decorator;
34 import net.sf.echobinding.format.Format;
35 import net.sf.echobinding.validation.*;
36
37 /***
38 * A PropertyAdapter is an adapter for a single bean property or a collection of beans.
39 * Through a PropertyAdapter you can retrieve and set the value of properties in
40 * a uniform way. The <code>PropertyAdapter</code> interface defines the
41 * protocol for accessing, manipulating and validating beans.
42 *
43 * @see net.sf.echobinding.binding.BindingContext
44 * @see net.sf.echobinding.format.Format
45 * @see net.sf.echobinding.decorator.Decorator
46 * @see net.sf.echobinding.validation.ValidationHandler
47 */
48 public interface PropertyAdapter {
49
50 /***
51 * Sets the identifier for the adapter. Generally you won't have to set the
52 * adapter id explicitly. Whenever you add/get an adapter to/from the
53 * binding context the there specified adapter id will be used as identfier.
54 *
55 * @param id
56 * the id
57 *
58 * @return the adapter
59 */
60 PropertyAdapter setId(String id);
61
62 /***
63 * Returns the identifier of the adapter.
64 *
65 * @return the adapter's id
66 */
67 String getId();
68
69 /***
70 * Sets the value of the wrapped bean property.
71 *
72 * @param value
73 * The value to set
74 * @param bean
75 * The bean
76 *
77 * @throws BindingException
78 * If the value cannot be set (eg. if the adapter is not
79 * applicable for the bean/property)
80 */
81 void setValue(Object bean, Object value) throws BindingException;
82
83 /***
84 * Returns the value of the wrapped bean property.
85 *
86 * @param bean
87 * the bean
88 *
89 * @return the value
90 *
91 * @throws BindingException
92 * If the value cannot be retrieved (eg. if the adapter is not
93 * applicable for the bean/property)
94 */
95 Object getValue(Object bean) throws BindingException;
96
97 /***
98 * Checks if the given value is valid for the specified bean. Returns
99 * a ValidationReport which tells you if the value is valid
100 * (ValidationReport.isValid()). The ValidationReport may also contain the
101 * error message (ValidationReport.getMessage()).
102 *
103 * @see ValidationReport
104 *
105 * @param value
106 * the value to validate
107 * @param bean
108 * the bean
109 *
110 * @return the validation report
111 */
112 ValidationReport validate(Object bean, Object value);
113
114 /***
115 * Sets the validators. Validators are used to validate bean input. Each
116 * added Validator will be consulted when a bean input is checked by the
117 * validate(Obejct bean, Obejct value) method.
118 *
119 * @see Validator
120 *
121 * @param validators
122 * the validators
123 *
124 * @return the property adapter
125 */
126 PropertyAdapter setValidators(Set<Validator> validators);
127
128 /***
129 * Adds a validator to the list of validators.
130 *
131 * @see Validator
132 *
133 * @param validator
134 * @return
135 */
136 PropertyAdapter addValidator(Validator validator);
137
138 /***
139 * Sets the format to be used by the getValue() method.
140 *
141 * @param format
142 * the format
143 *
144 * @return the adapter
145 */
146 PropertyAdapter setFormat(Format format);
147
148 /***
149 * Sets the format to be used by the getValue() method.
150 *
151 * @param format *
152 * @return the adapter
153 */
154 Format getFormat();
155
156 /***
157 * Sets the decorator for this adapter. A Decorator will be used in list
158 * components (SelectField, ListBox) to decorate the items in the list.
159 *
160 * @param decorator
161 * the decorator
162 *
163 * @return the property adapter
164 */
165 PropertyAdapter setDecorator(Decorator decorator);
166
167 /***
168 * Returns the decorator.
169 *
170 * @return the decorator
171 */
172 Decorator getDecorator();
173
174
175 /***
176 * Sets the label. Labels are user in data bound tables for the column
177 * header names.
178 *
179 * @param labelName
180 * The label to set.
181 *
182 * @return the property adapter
183 */
184 PropertyAdapter setLabel(String labelName);
185
186 /***
187 * Returns the label for the adapter.
188 *
189 * @return the label
190 */
191 String getLabel();
192
193 /***
194 * Sets the sub context. In case your adapter wraps another bean or a
195 * collection of beans you may specify a sub context for this bean.
196 *
197 * Sub contexts are often used in data bound tables to resolve relationships
198 * between entities (e.g. one-to-many associations).
199 *
200 * @param context
201 * The context to set
202 *
203 * @return the property adapter
204 */
205 PropertyAdapter setSubContext(BindingContext context);
206
207 /***
208 * Returns the sub context.
209 *
210 * @return the sub context
211 */
212 BindingContext getSubContext();
213
214 /***
215 * Creates a new adapter instance. Clones the adapter. Will be used by the
216 * binding context to create child contexts.
217 *
218 * @return the property adapter
219 */
220 PropertyAdapter newInstance();
221
222 /***
223 * Sets the validation handler. A ValidationHanlder is used to report
224 * (validation) errors to the user.
225 *
226 * @param handler
227 * The validation handler
228 *
229 * @return the property adapter
230 */
231 PropertyAdapter setValidationHandler(ValidationHandler handler);
232
233 /***
234 * Returns the validation handler.
235 *
236 * @return the validation handler
237 */
238 ValidationHandler getValidationHandler();
239
240 }