DataBindingContext


1   /*******************************************************************************
2    * Copyright (c) 2005, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *     Brad Reynolds - bug 159539
11   *     Brad Reynolds - bug 140644
12   *     Brad Reynolds - bug 159940
13   *     Brad Reynolds - bug 116920, 159768
14   *******************************************************************************/
15  package org.eclipse.core.databinding;
16  
17  import java.util.Iterator  ;
18  
19  import org.eclipse.core.databinding.observable.Observables;
20  import org.eclipse.core.databinding.observable.Realm;
21  import org.eclipse.core.databinding.observable.list.IObservableList;
22  import org.eclipse.core.databinding.observable.list.WritableList;
23  import org.eclipse.core.databinding.observable.map.IObservableMap;
24  import org.eclipse.core.databinding.observable.value.IObservableValue;
25  import org.eclipse.core.internal.databinding.ValidationStatusMap;
26  import org.eclipse.core.runtime.Assert;
27  import org.eclipse.core.runtime.IStatus;
28  
29  /**
30   * A DataBindingContext is the point of contact for the creation and management of
31   * {@link Binding bindings}.
32   * <p>
33   * A DataBindingContext provides the following abilities:
34   * <ul>
35   * <li>Ability to create bindings between
36   * {@link IObservableValue observable values}.</li>
37   * <li>Ability to create bindings between
38   * {@link IObservableList observable lists}.</li>
39   * <li>Access to the bindings created by the instance.</li>
40   * <li>Access to the validation status of its bindings.</li>
41   * </ul>
42   * </p>
43   * <p>
44   * Multiple contexts can be used at any point in time. One strategy for the
45   * management of contexts is the aggregation of validation statuses. For example
46   * an <code>IWizardPage</code> could use a single context and the statuses
47   * could be aggregated to set the page status and fulfillment. Each page in the
48   * <code>IWizard</code> would have its own context instance.
49   * </p>
50   * 
51   * @since 1.0
52   */
53  public class DataBindingContext {
54      private WritableList bindings;
55  
56      /**
57       * Unmodifiable version of {@link #bindings} for public exposure.
58       */
59      private IObservableList unmodifiableBindings;
60  
61      private IObservableMap validationStatusMap;
62  
63      private Realm validationRealm;
64  
65      /**
66       * Creates a data binding context, using the current default realm for the
67       * validation observables.
68       * 
69       * @see Realm
70       */
71      public DataBindingContext() {
72          this(Realm.getDefault());
73      }
74  
75      /**
76       * Creates a data binding context using the given realm for the validation
77       * observables.
78       * 
79       * @param validationRealm
80       *            the realm to be used for the validation observables
81       * 
82       * @see Realm
83       */
84      public DataBindingContext(Realm validationRealm) {
85          Assert.isNotNull(validationRealm);
86          this.validationRealm = validationRealm;
87          bindings = new WritableList(validationRealm);
88  
89          unmodifiableBindings = Observables.unmodifiableObservableList(bindings);
90          validationStatusMap = new ValidationStatusMap(validationRealm,
91                  bindings);
92      }
93  
94      /**
95       * Creates a {@link Binding} to synchronize the values of two
96       * {@link IObservableValue observable values}. During synchronization
97       * validation and conversion can be employed to customize the process. For
98       * specifics on the customization of the process see
99       * {@link UpdateValueStrategy}.
100      * 
101      * @param targetObservableValue
102      *            target value, commonly a UI widget
103      * @param modelObservableValue
104      *            model value
105      * @param targetToModel
106      *            strategy to employ when the target is the source of the change
107      *            and the model is the destination
108      * @param modelToTarget
109      *            strategy to employ when the model is the source of the change
110      *            and the target is the destination
111      * @return created binding
112      * 
113      * @see UpdateValueStrategy
114      */
115     public final Binding bindValue(IObservableValue targetObservableValue,
116             IObservableValue modelObservableValue,
117             UpdateValueStrategy targetToModel, UpdateValueStrategy modelToTarget) {
118         UpdateValueStrategy targetToModelStrategy = targetToModel != null ? targetToModel
119                         : createTargetToModelUpdateValueStrategy(targetObservableValue, modelObservableValue);
120         UpdateValueStrategy modelToTargetStrategy = modelToTarget != null ? modelToTarget
121                 : createModelToTargetUpdateValueStrategy(modelObservableValue, targetObservableValue);
122         targetToModelStrategy.fillDefaults(targetObservableValue, modelObservableValue);
123         modelToTargetStrategy.fillDefaults(modelObservableValue, targetObservableValue);
124         ValueBinding result = new ValueBinding(targetObservableValue,
125                 modelObservableValue, targetToModelStrategy,
126                 modelToTargetStrategy);
127         result.init(this);
128         return result;
129     }
130 
131     /**
132      * Returns an update value strategy to be used for copying values from the
133      * from value to the to value. Clients may override.
134      * 
135      * @param fromValue
136      * @param toValue
137      * @return a update value strategy
138      */
139     protected UpdateValueStrategy createModelToTargetUpdateValueStrategy(
140             IObservableValue fromValue, IObservableValue toValue) {
141         return new UpdateValueStrategy();
142     }
143 
144     /**
145      * Returns an update value strategy to be used for copying values from the
146      * from value to the to value. Clients may override.
147      * 
148      * @param fromValue
149      * @param toValue
150      * @return a update value strategy
151      */
152     protected UpdateValueStrategy createTargetToModelUpdateValueStrategy(
153             IObservableValue fromValue, IObservableValue toValue) {
154         return new UpdateValueStrategy();
155     }
156     
157     /**
158      * Creates a {@link Binding} to synchronize the values of two
159      * {@link IObservableList observable lists}. During synchronization
160      * validation and conversion can be employed to customize the process. For
161      * specifics on the customization of the process see
162      * {@link UpdateListStrategy}.
163      * 
164      * @param targetObservableList
165      *            target list, commonly a list representing a list in the UI
166      * @param modelObservableList
167      *            model list
168      * @param targetToModel
169      *            strategy to employ when the target is the source of the change
170      *            and the model is the destination
171      * @param modelToTarget
172      *            strategy to employ when the model is the source of the change
173      *            and the target is the destination
174      * @return created binding
175      * 
176      * @see UpdateListStrategy
177      */
178     public final Binding bindList(IObservableList targetObservableList,
179             IObservableList modelObservableList,
180             UpdateListStrategy targetToModel, UpdateListStrategy modelToTarget) {
181         UpdateListStrategy targetToModelStrategy = targetToModel != null ? targetToModel
182                 : createTargetToModelUpdateListStrategy(targetObservableList,
183                         modelObservableList);
184         UpdateListStrategy modelToTargetStrategy = modelToTarget != null ? modelToTarget
185                 : createModelToTargetUpdateListStrategy(modelObservableList,
186                         targetObservableList);
187         targetToModelStrategy.fillDefaults(targetObservableList,
188                 modelObservableList);
189         modelToTargetStrategy.fillDefaults(modelObservableList,
190                 targetObservableList);
191         ListBinding result = new ListBinding(targetObservableList,
192                 modelObservableList, targetToModelStrategy,
193                 modelToTargetStrategy);
194         result.init(this);
195         return result;
196     }
197 
198     /**
199      * @param modelObservableList
200      * @param targetObservableList
201      * @return an update list strategy
202      */
203     protected UpdateListStrategy createModelToTargetUpdateListStrategy(
204             IObservableList modelObservableList,
205             IObservableList targetObservableList) {
206         return new UpdateListStrategy();
207     }
208 
209     /**
210      * @param targetObservableList
211      * @param modelObservableList
212      * @return an update list strategy 
213      */
214     protected UpdateListStrategy createTargetToModelUpdateListStrategy(
215             IObservableList targetObservableList,
216             IObservableList modelObservableList) {
217         return new UpdateListStrategy();
218     }
219 
220     /**
221      * Disposes of this data binding context and all bindings that were added to
222      * this context.
223      */
224     public final void dispose() {
225         Binding[] bindingArray = (Binding[]) bindings.toArray(new Binding[bindings.size()]);
226         for (int i = 0; i < bindingArray.length; i++) {
227             bindingArray[i].dispose();
228         }
229     }
230 
231     /**
232      * Returns an unmodifiable observable list with elements of type
233      * {@link Binding}, ordered by time of addition.
234      * 
235      * @return the observable list containing all bindings
236      */
237     public final IObservableList getBindings() {
238         return unmodifiableBindings;
239     }
240 
241     /**
242      * Returns an observable map from bindings (type: {@link Binding}) to
243      * statuses (type: {@link IStatus}). The keys of the map are the bindings
244      * returned by {@link #getBindings()}, and the values are the current
245      * validaion status objects for each binding.
246      * 
247      * @return the observable map from bindings to status objects.
248      */
249     public final IObservableMap getValidationStatusMap() {
250         return validationStatusMap;
251     }
252 
253     /**
254      * Adds the given binding to this data binding context.
255      * 
256      * @param binding
257      *            The binding to add.
258      */
259     public void addBinding(Binding binding) {
260         bindings.add(binding);
261     }
262 
263     /**
264      * Updates all model observable objects to reflect the current state of the
265      * target observable objects.
266      * 
267      */
268     public final void updateModels() {
269         for (Iterator   it = bindings.iterator(); it.hasNext();) {
270             Binding binding = (Binding) it.next();
271             binding.updateTargetToModel();
272         }
273     }
274 
275     /**
276      * Updates all target observable objects to reflect the current state of the
277      * model observable objects.
278      * 
279      */
280     public final void updateTargets() {
281         for (Iterator   it = bindings.iterator(); it.hasNext();) {
282             Binding binding = (Binding) it.next();
283             binding.updateModelToTarget();
284         }
285     }
286 
287     /**
288      * Removes the given binding.
289      * 
290      * @param binding
291      * @return <code>true</code> if was associated with the context,
292      *         <code>false</code> if not
293      */
294     public boolean removeBinding(Binding binding) {
295         return bindings.remove(binding);
296     }
297 
298     /**
299      * Returns the validation realm.
300      * 
301      * @return the realm for the validation observables
302      * @see Realm
303      */
304     public final Realm getValidationRealm() {
305         return validationRealm;
306     }
307 }
308
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags