KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > core > databinding > UpdateListStrategy


1 /*******************************************************************************
2  * Copyright (c) 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  ******************************************************************************/
11
12 package org.eclipse.core.databinding;
13
14 import org.eclipse.core.databinding.conversion.IConverter;
15 import org.eclipse.core.databinding.observable.list.IObservableList;
16 import org.eclipse.core.databinding.validation.ValidationStatus;
17 import org.eclipse.core.internal.databinding.BindingMessages;
18 import org.eclipse.core.runtime.IStatus;
19 import org.eclipse.core.runtime.Status;
20
21 /**
22  * Customizes a {@link Binding} between two
23  * {@link IObservableList observable lists}. The following behaviors can be
24  * customized via the strategy:
25  * <ul>
26  * <li>Conversion</li>
27  * <li>Automatic processing</li>
28  * </ul>
29  * <p>
30  * Conversion:<br/> When elements are added they can be
31  * {@link #convert(Object) converted} to the destination element type.
32  * </p>
33  * <p>
34  * Automatic processing:<br/> The processing to perform when the source
35  * observable changes. This behavior is configured via policies provided on
36  * construction of the strategy (e.g. {@link #POLICY_NEVER},
37  * {@link #POLICY_ON_REQUEST}, {@link #POLICY_UPDATE}).
38  * </p>
39  *
40  *
41  * @see DataBindingContext#bindList(IObservableList, IObservableList,
42  * UpdateListStrategy, UpdateListStrategy)
43  * @see IConverter
44  * @since 1.0
45  */
46 public class UpdateListStrategy extends UpdateStrategy {
47
48     /**
49      * Policy constant denoting that the source observable's state should not be
50      * tracked and that the destination observable's state should never be
51      * updated.
52      */
53     public static int POLICY_NEVER = notInlined(1);
54
55     /**
56      * Policy constant denoting that the source observable's state should not be
57      * tracked, but that conversion and updating the destination observable's
58      * state should be performed when explicitly requested.
59      */
60     public static int POLICY_ON_REQUEST = notInlined(2);
61
62     /**
63      * Policy constant denoting that the source observable's state should be
64      * tracked, and that conversion and updating the destination observable's
65      * state should be performed automatically on every change of the source
66      * observable state.
67      */
68     public static int POLICY_UPDATE = notInlined(8);
69
70     /**
71      * Helper method allowing API evolution of the above constant values. The
72      * compiler will not inline constant values into client code if values are
73      * "computed" using this helper.
74      *
75      * @param i
76      * an integer
77      * @return the same integer
78      */
79     private static int notInlined(int i) {
80         return i;
81     }
82
83     protected IConverter converter;
84
85     private int updatePolicy;
86
87     protected boolean provideDefaults;
88
89     /**
90      * Creates a new update list strategy for automatically updating the
91      * destination observable list whenever the source observable list changes.
92      * A default converter will be provided. The defaults can be changed by
93      * calling one of the setter methods.
94      */
95     public UpdateListStrategy() {
96         this(true, POLICY_UPDATE);
97     }
98
99     /**
100      * Creates a new update list strategy with a configurable update policy. A
101      * default converter will be provided. The defaults can be changed by
102      * calling one of the setter methods.
103      *
104      * @param updatePolicy
105      * one of {@link #POLICY_NEVER}, {@link #POLICY_ON_REQUEST}, or
106      * {@link #POLICY_UPDATE}
107      */
108     public UpdateListStrategy(int updatePolicy) {
109         this(true, updatePolicy);
110     }
111
112     /**
113      * Creates a new update list strategy with a configurable update policy. A
114      * default converter will be provided if <code>provideDefaults</code> is
115      * <code>true</code>. The defaults can be changed by calling one of the
116      * setter methods.
117      *
118      * @param provideDefaults
119      * if <code>true</code>, default validators and a default
120      * converter will be provided based on the observable list's
121      * type.
122      * @param updatePolicy
123      * one of {@link #POLICY_NEVER}, {@link #POLICY_ON_REQUEST}, or
124      * {@link #POLICY_UPDATE}
125      */
126     public UpdateListStrategy(boolean provideDefaults, int updatePolicy) {
127         this.provideDefaults = provideDefaults;
128         this.updatePolicy = updatePolicy;
129     }
130
131     /**
132      * When an element is added to the destination converts the element from the
133      * source element type to the destination element type.
134      * <p>
135      * Default implementation will use the
136      * {@link #setConverter(IConverter) converter} if one exists. If no
137      * converter exists no conversion occurs.
138      * </p>
139      *
140      * @param element
141      * @return the converted element
142      */
143     public Object JavaDoc convert(Object JavaDoc element) {
144         return converter == null ? element : converter.convert(element);
145     }
146
147     /**
148      *
149      * @param source
150      * @param destination
151      */
152     protected void fillDefaults(IObservableList source,
153             IObservableList destination) {
154         Object JavaDoc sourceType = source.getElementType();
155         Object JavaDoc destinationType = destination.getElementType();
156         if (provideDefaults && sourceType != null && destinationType != null) {
157             if (converter == null) {
158                 setConverter(createConverter(sourceType, destinationType));
159             }
160         }
161         if (converter != null) {
162             if (sourceType != null) {
163                 checkAssignable(converter.getFromType(), sourceType,
164                         "converter does not convert from type " + sourceType); //$NON-NLS-1$
165 }
166             if (destinationType != null) {
167                 checkAssignable(converter.getToType(), destinationType,
168                         "converter does not convert to type " + destinationType); //$NON-NLS-1$
169 }
170         }
171     }
172
173     /**
174      * @return the update policy
175      */
176     public int getUpdatePolicy() {
177         return updatePolicy;
178     }
179
180     /**
181      * Sets the converter to be invoked when converting added elements from the
182      * source element type to the destination element type.
183      *
184      * @param converter
185      * @return the receiver, to enable method call chaining
186      */
187     public UpdateListStrategy setConverter(IConverter converter) {
188         this.converter = converter;
189         return this;
190     }
191
192     /**
193      * Adds the given element at the given index to the given observable list.
194      * Clients may extend but must call the super implementation.
195      *
196      * @param observableList
197      * @param element
198      * @param index
199      * @return a status
200      */
201     protected IStatus doAdd(IObservableList observableList, Object JavaDoc element,
202             int index) {
203         try {
204             observableList.add(index, element);
205         } catch (Exception JavaDoc ex) {
206             return ValidationStatus.error(BindingMessages
207                     .getString("ValueBinding_ErrorWhileSettingValue"), //$NON-NLS-1$
208 ex);
209         }
210         return Status.OK_STATUS;
211     }
212
213     /**
214      * Removes the element at the given index from the given observable list.
215      * Clients may extend but must call the super implementation.
216      *
217      * @param observableList
218      * @param index
219      * @return a status
220      */
221     protected IStatus doRemove(IObservableList observableList, int index) {
222         try {
223             observableList.remove(index);
224         } catch (Exception JavaDoc ex) {
225             return ValidationStatus.error(BindingMessages
226                     .getString("ValueBinding_ErrorWhileSettingValue"), //$NON-NLS-1$
227 ex);
228         }
229         return Status.OK_STATUS;
230     }
231 }
232
Popular Tags