1 /******************************************************************************* 2 * Copyright (c) 2008, 2015 Matthew Hall and others. 3 * 4 * This program and the accompanying materials 5 * are made available under the terms of the Eclipse Public License 2.0 6 * which accompanies this distribution, and is available at 7 * https://www.eclipse.org/legal/epl-2.0/ 8 * 9 * SPDX-License-Identifier: EPL-2.0 10 * 11 * Contributors: 12 * Matthew Hall - initial API and implementation (bug 194734) 13 * Matthew Hall - bug 195222 14 * Stefan Xenos <sxenos@gmail.com> - Bug 335792 15 ******************************************************************************/ 16 17 package org.eclipse.core.databinding.property.value; 18 19 import org.eclipse.core.databinding.observable.Realm; 20 import org.eclipse.core.databinding.observable.list.IObservableList; 21 import org.eclipse.core.databinding.observable.map.IObservableMap; 22 import org.eclipse.core.databinding.observable.masterdetail.IObservableFactory; 23 import org.eclipse.core.databinding.observable.set.IObservableSet; 24 import org.eclipse.core.databinding.observable.value.IObservableValue; 25 import org.eclipse.core.databinding.property.IProperty; 26 import org.eclipse.core.databinding.property.list.IListProperty; 27 import org.eclipse.core.databinding.property.map.IMapProperty; 28 import org.eclipse.core.databinding.property.set.ISetProperty; 29 30 /** 31 * Interface for value-typed properties 32 * 33 * @param <S> type of the source object 34 * @param <T> type of the value of the property 35 * 36 * @since 1.2 37 * @noimplement This interface is not intended to be implemented by clients. 38 * Clients should instead subclass one of the classes that 39 * implement this interface. 40 * <p> 41 * Authors of extensions to the databinding framework may extend 42 * this interface and indirectly implement it, but if doing so must 43 * also extend one of the framework classes. (Use an API problem 44 * filter to suppress the resulting warning.) 45 * <p> 46 * Direct implementers of this interface outside of the framework 47 * will be broken in future releases when methods are added to this 48 * interface. 49 * @see ValueProperty 50 * @see SimpleValueProperty 51 */ 52 public interface IValueProperty<S, T> extends IProperty { 53 /** 54 * Returns the value type of the property, or <code>null</code> if untyped. 55 * 56 * @return the value type of the property, or <code>null</code> if untyped. 57 */ getValueType()58 Object getValueType(); 59 60 /** 61 * Returns the current value of this property on the specified property 62 * source. 63 * 64 * @param source 65 * the property source (may be null) 66 * @return the current value of this property on the specified property 67 * source. 68 * @since 1.3 69 */ getValue(S source)70 T getValue(S source); 71 72 /** 73 * Sets this property on the specified property source to the specified 74 * value. 75 * <p> 76 * <b>Note:</b> This method is made available to facilitate basic property 77 * access. However if the property source lacks property change 78 * notification, then observables on the source object may not be notified 79 * of the change. In most cases it is preferable to call 80 * {@link IObservableValue#setValue(Object)} on the observable instead. 81 * 82 * @param source 83 * the property source (may be null) 84 * @param value 85 * the new property value 86 * @since 1.3 87 */ setValue(S source, T value)88 void setValue(S source, T value); 89 90 /** 91 * Returns an observable value observing this value property on the given 92 * property source. 93 * 94 * @param source 95 * the property source 96 * @return an observable value observing this value property on the given 97 * property source 98 */ observe(S source)99 IObservableValue<T> observe(S source); 100 101 /** 102 * Returns an observable value observing this value property on the given 103 * property source 104 * 105 * @param realm 106 * the observable's realm 107 * @param source 108 * the property source 109 * @return an observable value observing this value property on the given 110 * property source 111 */ observe(Realm realm, S source)112 IObservableValue<T> observe(Realm realm, S source); 113 114 /** 115 * Returns a factory for creating observable values tracking this property 116 * of a particular property source. 117 * 118 * @return a factory for creating observable values tracking this property 119 * of a particular property source. 120 */ valueFactory()121 IObservableFactory<S, IObservableValue<T>> valueFactory(); 122 123 /** 124 * Returns a factory for creating observable values in the given realm, 125 * tracking this property of a particular property source. 126 * 127 * @param realm 128 * the realm 129 * 130 * @return a factory for creating observable values in the given realm, 131 * tracking this property of a particular property source. 132 */ valueFactory(Realm realm)133 IObservableFactory<S, IObservableValue<T>> valueFactory(Realm realm); 134 135 /** 136 * Returns an observable value on the master observable's realm which tracks 137 * this property on the current value of <code>master</code>. 138 * 139 * @param master 140 * the master observable 141 * @return an observable value which tracks this property of the current 142 * value of <code>master</code>. 143 */ observeDetail(IObservableValue<M> master)144 <M extends S> IObservableValue<T> observeDetail(IObservableValue<M> master); 145 146 /** 147 * Returns an observable list on the master observable's realm which tracks 148 * this property on each element of <code>master</code>. 149 * 150 * @param master 151 * the master observable 152 * @return an observable list which tracks this property on each element of 153 * the master observable. 154 */ observeDetail(IObservableList<M> master)155 <M extends S> IObservableList<T> observeDetail(IObservableList<M> master); 156 157 /** 158 * Returns an observable map on the master observable's realm where the 159 * map's key set is the specified master set, and where each key maps to the 160 * current property value for each element. 161 * 162 * @param master 163 * the master observable 164 * @return an observable map that tracks the current value of this property 165 * for the elements in the given set. 166 */ observeDetail(IObservableSet<M> master)167 <M extends S> IObservableMap<M, T> observeDetail(IObservableSet<M> master); 168 169 /** 170 * Returns an observable map on the master observable's realm where the 171 * map's key set is the same as the master observable map, and where each 172 * value is the property value of the corresponding value in the master 173 * observable map. 174 * 175 * @param master 176 * the master observable 177 * @return an observable map on the master observable's realm which tracks 178 * the current value of this property for the elements in the given 179 * map's values collection 180 */ observeDetail(IObservableMap<K, V> master)181 <K, V extends S> IObservableMap<K, T> observeDetail(IObservableMap<K, V> master); 182 183 /** 184 * Returns the nested combination of this property and the specified detail 185 * value property. Value modifications made through the returned property 186 * are delegated to the detail property, using the value of this property as 187 * the source. 188 * 189 * @param detailValue 190 * the detail property 191 * @return the nested combination of the master and detail properties 192 */ value(IValueProperty<? super T, M> detailValue)193 <M> IValueProperty<S, M> value(IValueProperty<? super T, M> detailValue); 194 195 /** 196 * Returns the nested combination of this property and the specified detail 197 * list property. List modifications made through the returned property are 198 * delegated to the detail property, using the value of the master property 199 * as the source. 200 * 201 * @param detailList 202 * the detail property 203 * @return the nested combination of the master value and detail list 204 * properties 205 */ list(IListProperty<? super T, E> detailList)206 <E> IListProperty<S, E> list(IListProperty<? super T, E> detailList); 207 208 /** 209 * Returns the nested combination of this property and the specified detail 210 * set property. Set modifications made through the returned property are 211 * delegated to the detail property, using the value of the master property 212 * as the source. 213 * 214 * @param detailSet 215 * the detail property 216 * @return the nested combination of the master value and detail set 217 * properties 218 */ set(ISetProperty<? super T, E> detailSet)219 <E> ISetProperty<S, E> set(ISetProperty<? super T, E> detailSet); 220 221 /** 222 * Returns the nested combination of this property and the specified detail 223 * map property. Map modifications made through the returned property are 224 * delegated to the detail property, using the value of the master property 225 * as the source. 226 * 227 * @param detailMap 228 * the detail property 229 * @return the nested combination of the master value and detial map 230 * properties 231 */ map(IMapProperty<? super T, K, V> detailMap)232 <K, V> IMapProperty<S, K, V> map(IMapProperty<? super T, K, V> detailMap); 233 } 234