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.beans.PropertyChangeListener;
32 import java.util.List;
33 import java.util.Set;
34
35 import net.sf.echobinding.BoundControl;
36 import net.sf.echobinding.decorator.Decorator;
37 import net.sf.echobinding.format.Format;
38 import net.sf.echobinding.model.PresentationModel;
39 import net.sf.echobinding.validation.ValidationHandler;
40 import net.sf.echobinding.validation.ValidationReport;
41
42 /***
43 * The BindingContext interface.
44 *
45 */
46 public interface BindingContext extends PropertyChangeListener {
47
48 /***
49 * Adds a property adapter to the context.
50 *
51 * @param adapterId the adapter id
52 * @param adapter the adapter
53 *
54 * @return this
55 */
56 BindingContext add(String adapterId, PropertyAdapter adapter);
57
58 /***
59 * Removes a binding from the context.
60 *
61 * @param adapterId The adapter id
62 *
63 * @return the removed property adapter
64 */
65 PropertyAdapter remove(String adapterId);
66
67
68 /***
69 * Returns all property adapters for this context.
70 *
71 * @return List of all adapters
72 */
73 List<PropertyAdapter> getPropertyAdapters();
74
75 /***
76 * Returns the property adapter for the given adapter id.
77 *
78 * @param adapterId The adapter id
79 *
80 * @return the property adapter
81 */
82 PropertyAdapter getAdapter(String adapterId);
83
84 /***
85 * Returns the value for the specified adapter.
86 *
87 * @param id the id
88 *
89 * @return the value
90 *
91 * @throws BindingException the binding exception
92 */
93 Object getValue(String id) throws BindingException;
94
95 /***
96 * Sets the value for the specific adapter.
97 *
98 * @param value the value
99 * @param id the id
100 *
101 * @throws BindingException the binding exception
102 */
103 void setValue(String id, Object value) throws BindingException;
104
105 /***
106 * Checks if the value is valid for the specified adapter.
107 *
108 * @param value the value
109 * @param id the id
110 *
111 * @return the validation report
112 */
113 ValidationReport validate(String id, Object value);
114
115 /***
116 * Returns the format for the specified adapter.
117 *
118 * @param id the id
119 *
120 * @return the format
121 */
122 Format getFormat(String id);
123
124 /***
125 * Sets the <code>ValidationHandler</code> for this context.
126 *
127 * @param handler the handler
128 *
129 * @return the binding context
130 */
131 BindingContext setValidationHandler(ValidationHandler handler);
132
133 /***
134 * Returns the <code>ValidationHandler</code> for this context.
135 *
136 * @return the ValidationHandler
137 */
138 ValidationHandler getValidationHandler();
139
140 /***
141 * Returns the <code>ValidationHandler</code> for a specific binding. If
142 * no <code>ValidationHandler</code> exists for the binding, the
143 * <code>ValidationHandler</code> of the context should be returned.
144 *
145 * @param id the id
146 *
147 * @return the validation handler
148 */
149 ValidationHandler getValidationHandler(String id);
150
151 /***
152 * Add a PropertyChangeListener to the listener list. The listener is
153 * registered for all properties. The same listener object may be added more
154 * than once, and will be called as many times as it is added. If listener
155 * is null, no exception is thrown and no action is taken.
156 *
157 * @param listener- The PropertyChangeListener to be added
158 * @param listener the listener
159 */
160 void addPropertyChangeListener(
161 PropertyChangeListener listener);
162
163 /***
164 * Add a PropertyChangeListener to the listener list for a specific
165 * property. The same listener object may be added more than once, and will
166 * be called as many times as it is added. If listener is null, no exception
167 * is thrown and no action is taken.
168 *
169 * @param listener- The PropertyChangeListener to be added
170 * @param propertyName the property name
171 * @param listener the listener
172 */
173 void addPropertyChangeListener(String propertyName,
174 PropertyChangeListener listener);
175
176 /***
177 * Remove a PropertyChangeListener from the listener list. This removes a
178 * PropertyChangeListener that was registered for all properties. If
179 * listener was added more than once to the same event source, it will be
180 * notified one less time after being removed. If listener is null, or was
181 * never added, no exception is thrown and no action is taken.
182 *
183 * @param listener -
184 * The PropertyChangeListener to be removed
185 */
186 void removePropertyChangeListener(PropertyChangeListener listener);
187
188 /***
189 * Returns the model.
190 *
191 * @return Returns the model.
192 */
193 Object getModel();
194
195 /***
196 * Sets the model to be used.
197 *
198 * @param rootObject The root object to set.
199 * @param bean the bean
200 *
201 * @return the binding context
202 */
203 BindingContext setModel(Object bean);
204
205 /***
206 * Creates a new BindingContext instance and adds it as a child to this
207 * context. The child context inherits all bindings of the parent/this
208 * context.
209 *
210 * @return a new BindingContext instance with all bindings of this instance
211 */
212 BindingContext createChild();
213
214 /***
215 * Removes a child context from this context.
216 *
217 * @param context the context
218 *
219 * @return true, if remove child
220 */
221 boolean removeChild(BindingContext context);
222
223 /***
224 * Returns the decorator for the specified binding id.
225 *
226 * @param id the id
227 *
228 * @return the decorator of the binding
229 */
230 Decorator getDecorator(String id);
231
232 /***
233 * Checks if the given value equals the value in the bean.
234 *
235 * @param value the value
236 * @param id the id
237 *
238 * @return true, if is dirty
239 *
240 * @throws BindingException the binding exception
241 */
242 boolean isDirty(String id, Object value) throws BindingException;
243
244 /***
245 * Registers a bound control at the context. Each bound control
246 * registeres itself with the id of its adapter at the binding context.
247 *
248 * @param control the control
249 * @param id the adapter id
250 */
251 void registerControl(String id, BoundControl control);
252
253 /***
254 * Renoves a bound control from the context.
255 *
256 * @param control the control
257 * @param id the adapter id
258 */
259 void removeControl(BoundControl control);
260
261 /***
262 * Returns the bound control that belongs to the adapter id.
263 *
264 * @param id The adapter id
265 *
266 * @return The bound control
267 */
268 BoundControl getControl(String id);
269
270 /***
271 * Returns all registered controls.
272 *
273 * @return the controls
274 */
275 Set<BoundControl> getControls();
276
277 /***
278 * Sets the presentation model.
279 *
280 * @param presentationModel the presentation model
281 */
282 void setPresentationModel(PresentationModel presentationModel);
283
284 /***
285 * Returns the pesentation model.
286 *
287 * @return the presentation model
288 */
289 PresentationModel getPresentationModel();
290
291 /***
292 * Sets the parent binding context.
293 *
294 * @param context
295 * The parent context
296 *
297 */
298 void setParent(BindingContext context);
299
300 /***
301 * Returns the parent binding context.
302 *
303 * @return the parent
304 */
305 BindingContext getParent();
306
307 /***
308 * Returns the child binding contexts.
309 *
310 * @return the childs
311 */
312 Set<BindingContext> getChilds();
313
314
315 /***
316 * Validates this context and all its sub contexts. Invokes validateInput() on
317 * each attached control to show validation errors to the user.
318 *
319 */
320 void validate();
321
322 /***
323 * Checks if all controls in this context and the controls in its sub
324 * contexts contain valid inputs.
325 *
326 * @return true if all controls are valid, otherwise false
327 */
328 boolean isValid();
329
330 /***
331 * Checks if the state of any controls in this context an its sub contexts is
332 * different from the state in the model.
333 *
334 * @return true if any controls is dirty, false otherwise
335 */
336 boolean isDirty();
337
338
339 /***
340 * Synchronizes the GUI/screen state with the application state. Transfers the
341 * state of every widget attached to this context to the model.
342 *
343 */
344 void synchronize();
345
346 /***
347 * Resets the GUI/screen state. Overwrites the widget's state with the state
348 * in the model.
349 */
350 void update();
351
352
353 }