Mercurial > projects > dwt2

comparison org.eclipse.core.databinding.observable/src/org/eclipse/core/databinding/observable/Observables.d @ 95:6208d4f6a277

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added trees for databinding.beans and observable
author Frank Benoit <benoit@tionex.de>
date Tue, 21 Apr 2009 10:55:51 +0200
parents
children b74ac5dfcc06
comparison
equal deleted inserted replaced
94:1d37a7813832 95:6208d4f6a277
1 /*******************************************************************************
2 * Copyright (c) 2006-2008 Cerner 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 * Brad Reynolds - initial API and implementation
10 * Matt Carter - bug 212518 (constantObservableValue)
11 * Matthew Hall - bugs 208332, 212518, 219909, 184830
12 * Marko Topolnik - bug 184830
13 ******************************************************************************/
14
15 package org.eclipse.core.databinding.observable;
16
17 import java.util.List;
18 import java.util.Set;
19
20 import org.eclipse.core.databinding.observable.list.IListChangeListener;
21 import org.eclipse.core.databinding.observable.list.IObservableList;
22 import org.eclipse.core.databinding.observable.list.ObservableList;
23 import org.eclipse.core.databinding.observable.map.IObservableMap;
24 import org.eclipse.core.databinding.observable.masterdetail.IObservableFactory;
25 import org.eclipse.core.databinding.observable.masterdetail.MasterDetailObservables;
26 import org.eclipse.core.databinding.observable.set.IObservableSet;
27 import org.eclipse.core.databinding.observable.set.ISetChangeListener;
28 import org.eclipse.core.databinding.observable.set.ObservableSet;
29 import org.eclipse.core.databinding.observable.value.IObservableValue;
30 import org.eclipse.core.internal.databinding.observable.ConstantObservableValue;
31 import org.eclipse.core.internal.databinding.observable.EmptyObservableList;
32 import org.eclipse.core.internal.databinding.observable.EmptyObservableSet;
33 import org.eclipse.core.internal.databinding.observable.MapEntryObservableValue;
34 import org.eclipse.core.internal.databinding.observable.ProxyObservableList;
35 import org.eclipse.core.internal.databinding.observable.ProxyObservableSet;
36 import org.eclipse.core.internal.databinding.observable.StalenessObservableValue;
37 import org.eclipse.core.internal.databinding.observable.UnmodifiableObservableList;
38 import org.eclipse.core.internal.databinding.observable.UnmodifiableObservableSet;
39 import org.eclipse.core.internal.databinding.observable.UnmodifiableObservableValue;
40 import org.eclipse.core.runtime.Assert;
41
42 /**
43 * Contains static methods to operate on or return
44 * {@link IObservable Observables}.
45 *
46 * @since 1.0
47 */
48 public class Observables {
49 /**
50 * Returns an unmodifiable observable value backed by the given observable
51 * value.
52 *
53 * @param value
54 * the value to wrap in an unmodifiable value
55 * @return an unmodifiable observable value backed by the given observable
56 * value
57 * @since 1.1
58 */
59 public static IObservableValue unmodifiableObservableValue(
60 IObservableValue value) {
61 Assert.isNotNull(value, "Argument 'value' cannot be null"); //$NON-NLS-1$
62 return new UnmodifiableObservableValue(value);
63 }
64
65 /**
66 * Returns an observable value with the given constant value.
67 *
68 * @param realm
69 * the observable's realm
70 * @param value
71 * the observable's constant value
72 * @param valueType
73 * the observable's value type
74 * @return an immutable observable value with the given constant value
75 * @since 1.1
76 */
77 public static IObservableValue constantObservableValue(Realm realm,
78 Object value, Object valueType) {
79 return new ConstantObservableValue(realm, value, valueType);
80 }
81
82 /**
83 * Returns an observable value with the given constant value.
84 *
85 * @param realm
86 * the observable's realm
87 * @param value
88 * the observable's constant value
89 * @return an immutable observable value with the given constant value
90 * @since 1.1
91 */
92 public static IObservableValue constantObservableValue(Realm realm,
93 Object value) {
94 return constantObservableValue(realm, value, null);
95 }
96
97 /**
98 * Returns an observable value with the given constant value.
99 *
100 * @param value
101 * the observable's constant value
102 * @param valueType
103 * the observable's value type
104 * @return an immutable observable value with the given constant value
105 * @since 1.1
106 */
107 public static IObservableValue constantObservableValue(Object value,
108 Object valueType) {
109 return constantObservableValue(Realm.getDefault(), value, valueType);
110 }
111
112 /**
113 * Returns an observable value with the given constant value.
114 *
115 * @param value
116 * the observable's constant value
117 * @return an immutable observable value with the given constant value
118 * @since 1.1
119 */
120 public static IObservableValue constantObservableValue(Object value) {
121 return constantObservableValue(Realm.getDefault(), value, null);
122 }
123
124 /**
125 * Returns an unmodifiable observable list backed by the given observable
126 * list.
127 *
128 * @param list
129 * the list to wrap in an unmodifiable list
130 * @return an unmodifiable observable list backed by the given observable
131 * list
132 */
133 public static IObservableList unmodifiableObservableList(
134 IObservableList list) {
135 if (list is null) {
136 throw new IllegalArgumentException("List parameter cannot be null."); //$NON-NLS-1$
137 }
138
139 return new UnmodifiableObservableList(list);
140 }
141
142 /**
143 * Returns an unmodifiable observable set backed by the given observable
144 * set.
145 *
146 * @param set
147 * the set to wrap in an unmodifiable set
148 * @return an unmodifiable observable set backed by the given observable set
149 * @since 1.1
150 */
151 public static IObservableSet unmodifiableObservableSet(IObservableSet set) {
152 if (set is null) {
153 throw new IllegalArgumentException("Set parameter cannot be null"); //$NON-NLS-1$
154 }
155
156 return new UnmodifiableObservableSet(set);
157 }
158
159 /**
160 * Returns an empty observable list. The returned list continues to work
161 * after it has been disposed of and can be disposed of multiple times.
162 *
163 * @return an empty observable list.
164 */
165 public static IObservableList emptyObservableList() {
166 return emptyObservableList(Realm.getDefault(), null);
167 }
168
169 /**
170 * Returns an empty observable list of the given element type. The returned
171 * list continues to work after it has been disposed of and can be disposed
172 * of multiple times.
173 *
174 * @param elementType
175 * the element type of the returned list
176 * @return an empty observable list
177 * @since 1.1
178 */
179 public static IObservableList emptyObservableList(Object elementType) {
180 return emptyObservableList(Realm.getDefault(), elementType);
181 }
182
183 /**
184 * Returns an empty observable list belonging to the given realm. The
185 * returned list continues to work after it has been disposed of and can be
186 * disposed of multiple times.
187 *
188 * @param realm
189 * the realm of the returned list
190 * @return an empty observable list.
191 */
192 public static IObservableList emptyObservableList(Realm realm) {
193 return emptyObservableList(realm, null);
194 }
195
196 /**
197 * Returns an empty observable list of the given element type and belonging
198 * to the given realm. The returned list continues to work after it has been
199 * disposed of and can be disposed of multiple times.
200 *
201 * @param realm
202 * the realm of the returned list
203 * @param elementType
204 * the element type of the returned list
205 * @return an empty observable list
206 * @since 1.1
207 */
208 public static IObservableList emptyObservableList(Realm realm,
209 Object elementType) {
210 return new EmptyObservableList(realm, elementType);
211 }
212
213 /**
214 * Returns an empty observable set. The returned set continues to work after
215 * it has been disposed of and can be disposed of multiple times.
216 *
217 * @return an empty observable set.
218 */
219 public static IObservableSet emptyObservableSet() {
220 return emptyObservableSet(Realm.getDefault(), null);
221 }
222
223 /**
224 * Returns an empty observable set of the given element type. The returned
225 * set continues to work after it has been disposed of and can be disposed
226 * of multiple times.
227 *
228 * @param elementType
229 * the element type of the returned set
230 * @return an empty observable set
231 * @since 1.1
232 */
233 public static IObservableSet emptyObservableSet(Object elementType) {
234 return emptyObservableSet(Realm.getDefault(), elementType);
235 }
236
237 /**
238 * Returns an empty observable set belonging to the given realm. The
239 * returned set continues to work after it has been disposed of and can be
240 * disposed of multiple times.
241 *
242 * @param realm
243 * the realm of the returned set
244 * @return an empty observable set.
245 */
246 public static IObservableSet emptyObservableSet(Realm realm) {
247 return emptyObservableSet(realm, null);
248 }
249
250 /**
251 * Returns an empty observable set of the given element type and belonging
252 * to the given realm. The returned set continues to work after it has been
253 * disposed of and can be disposed of multiple times.
254 *
255 * @param realm
256 * the realm of the returned set
257 * @param elementType
258 * the element type of the returned set
259 * @return an empty observable set
260 * @since 1.1
261 */
262 public static IObservableSet emptyObservableSet(Realm realm,
263 Object elementType) {
264 return new EmptyObservableSet(realm, elementType);
265 }
266
267 /**
268 * Returns an observable set backed by the given set.
269 *
270 * @param set
271 * the set to wrap in an IObservableSet
272 * @return an observable set backed by the given set
273 */
274 public static IObservableSet staticObservableSet(Set set) {
275 return staticObservableSet(Realm.getDefault(), set, Object.class);
276 }
277
278 /**
279 * Returns an observable set of the given element type, backed by the given
280 * set.
281 *
282 * @param set
283 * the set to wrap in an IObservableSet
284 * @param elementType
285 * the element type of the returned set
286 * @return Returns an observable set backed by the given unchanging set
287 * @since 1.1
288 */
289 public static IObservableSet staticObservableSet(Set set, Object elementType) {
290 return staticObservableSet(Realm.getDefault(), set, elementType);
291 }
292
293 /**
294 * Returns an observable set belonging to the given realm, backed by the
295 * given set.
296 *
297 * @param realm
298 * the realm of the returned set
299 * @param set
300 * the set to wrap in an IObservableSet
301 * @return an observable set backed by the given unchanging set
302 */
303 public static IObservableSet staticObservableSet(Realm realm, Set set) {
304 return staticObservableSet(realm, set, Object.class);
305 }
306
307 /**
308 * Returns an observable set of the given element type and belonging to the
309 * given realm, backed by the given set.
310 *
311 * @param realm
312 * the realm of the returned set
313 * @param set
314 * the set to wrap in an IObservableSet
315 * @param elementType
316 * the element type of the returned set
317 * @return an observable set backed by the given set
318 * @since 1.1
319 */
320 public static IObservableSet staticObservableSet(Realm realm, Set set,
321 Object elementType) {
322 return new class(realm, set, elementType) ObservableSet {
323 public void addChangeListener(IChangeListener listener) {
324 }
325
326 public void addStaleListener(IStaleListener listener) {
327 }
328
329 public void addSetChangeListener(ISetChangeListener listener) {
330 }
331 };
332 }
333
334 /**
335 * Returns an observable set that contains the same elements as the given
336 * set, and fires the same events as the given set, but can be disposed of
337 * without disposing of the wrapped set.
338 *
339 * @param target
340 * the set to wrap
341 * @return a disposable proxy for the given observable set
342 */
343 public static IObservableSet proxyObservableSet(IObservableSet target) {
344 return new ProxyObservableSet(target);
345 }
346
347 /**
348 * Returns an observable list that contains the same elements as the given
349 * list, and fires the same events as the given list, but can be disposed of
350 * without disposing of the wrapped list.
351 *
352 * @param target
353 * the list to wrap
354 * @return a disposable proxy for the given observable list
355 * @since 1.1
356 */
357 public static IObservableList proxyObservableList(IObservableList target) {
358 return new ProxyObservableList(target);
359 }
360
361 /**
362 * Returns an observable list backed by the given list.
363 *
364 * @param list
365 * the list to wrap in an IObservableList
366 * @return an observable list backed by the given unchanging list
367 */
368 public static IObservableList staticObservableList(List list) {
369 return staticObservableList(Realm.getDefault(), list, Object.class);
370 }
371
372 /**
373 * Returns an observable list of the given element type, backed by the given
374 * list.
375 *
376 * @param list
377 * the list to wrap in an IObservableList
378 * @param elementType
379 * the element type of the returned list
380 * @return an observable list backed by the given unchanging list
381 * @since 1.1
382 */
383 public static IObservableList staticObservableList(List list,
384 Object elementType) {
385 return staticObservableList(Realm.getDefault(), list, elementType);
386 }
387
388 /**
389 * Returns an observable list belonging to the given realm, backed by the
390 * given list.
391 *
392 * @param realm
393 * the realm of the returned list
394 * @param list
395 * the list to wrap in an IObservableList
396 * @return an observable list backed by the given unchanging list
397 */
398 public static IObservableList staticObservableList(Realm realm, List list) {
399 return staticObservableList(realm, list, Object.class);
400 }
401
402 /**
403 * Returns an observable list of the given element type and belonging to the
404 * given realm, backed by the given list.
405 *
406 * @param realm
407 * the realm of the returned list
408 * @param list
409 * the list to wrap in an IObservableList
410 * @param elementType
411 * the element type of the returned list
412 * @return an observable list backed by the given unchanging list
413 * @since 1.1
414 */
415 public static IObservableList staticObservableList(Realm realm, List list,
416 Object elementType) {
417 return new class(realm, list, elementType) ObservableList {
418 public void addChangeListener(IChangeListener listener) {
419 }
420
421 public void addStaleListener(IStaleListener listener) {
422 }
423
424 public void addListChangeListener(IListChangeListener listener) {
425 }
426 };
427 }
428
429 /**
430 * Returns an observable value of type <code>Boolean.TYPE</code> which
431 * tracks whether the given observable is stale.
432 *
433 * @param observable
434 * the observable to track
435 * @return an observable value which tracks whether the given observable is
436 * stale
437 *
438 * @since 1.1
439 */
440 public static IObservableValue observeStale(IObservable observable) {
441 return new StalenessObservableValue(observable);
442 }
443
444 /**
445 * Returns an observable value that tracks changes to the value of an
446 * observable map's entry specified by its key.
447 * <p>
448 * The state where the key does not exist in the map is equivalent to the
449 * state where the key exists and its value is <code>null</code>. The
450 * transition between these two states is not considered a value change and
451 * no event is fired.
452 *
453 * @param map
454 * the observable map whose entry will be tracked.
455 * @param key
456 * the key identifying the map entry to track.
457 * @param valueType
458 * the type of the value. May be <code>null</code>, meaning
459 * the value is untyped.
460 * @return an observable value that tracks the value associated with the
461 * specified key in the given map
462 * @since 1.1
463 */
464 public static IObservableValue observeMapEntry(IObservableMap map,
465 Object key, Object valueType) {
466 return new MapEntryObservableValue(map, key, valueType);
467 }
468
469 /**
470 * Returns a factory for creating obervable values tracking the value of the
471 * {@link IObservableMap observable map} entry identified by a particular
472 * key.
473 *
474 * @param map
475 * the observable map whose entry will be tracked.
476 * @param valueType
477 * the type of the value. May be <code>null</code>, meaning
478 * the value is untyped.
479 * @return a factory for creating observable values tracking the value of
480 * the observable map entry identified by a particular key object.
481 * @since 1.1
482 */
483 public static IObservableFactory mapEntryValueFactory(
484 final IObservableMap map, final Object valueType) {
485 return new class() IObservableFactory {
486 public IObservable createObservable(Object key) {
487 return observeMapEntry(map, key, valueType);
488 }
489 };
490 }
491
492 /**
493 * Helper method for <code>MasterDetailObservables.detailValue(master,
494 * mapEntryValueFactory(map, valueType), valueType)</code>.
495 *
496 * @param map
497 * the observable map whose entry will be tracked.
498 * @param master
499 * the observable value that identifies which map entry to track.
500 * @param valueType
501 * the type of the value. May be <code>null</code>, meaning
502 * the value is untyped.
503 * @return an observable value tracking the current value of the specified
504 * key in the given map an observable value that tracks the current
505 * value of the named property for the current value of the master
506 * observable value
507 * @since 1.1
508 */
509 public static IObservableValue observeDetailMapEntry(IObservableMap map,
510 IObservableValue master, Object valueType) {
511 return MasterDetailObservables.detailValue(master,
512 mapEntryValueFactory(map, valueType), valueType);
513 }
514 }