001 /**
002 * <copyright>
003 *
004 * Copyright (c) 2002-2006 IBM Corporation and others.
005 * All rights reserved. This program and the accompanying materials
006 * are made available under the terms of the Eclipse Public License v1.0
007 * which accompanies this distribution, and is available at
008 * http://www.eclipse.org/legal/epl-v10.html
009 *
010 * Contributors:
011 * IBM - Initial API and implementation
012 *
013 * </copyright>
014 *
015 * $Id: Notification.java,v 1.4 2007/06/12 20:56:17 emerks Exp $
016 */
017 package org.eclipse.emf.common.notify;
018
019
020 /**
021 * A description of a feature change that has occurred for some notifier.
022 * @see Adapter#notifyChanged
023 * @see Notifier
024 */
025 public interface Notification
026 {
027 /**
028 * Returns the object affected by the change.
029 * @return the object affected by the change.
030 */
031 Object getNotifier();
032
033 /**
034 * An {@link Notification#getEventType event type} indicating that
035 * the notifier has been created.
036 * @see Notification#getEventType
037 * @deprecated
038 */
039 @Deprecated
040 int CREATE = 0;
041
042 /**
043 * An {@link Notification#getEventType event type} indicating that
044 * a feature of the notifier has been set.
045 * This applies for simple features.
046 * @see Notification#getEventType
047 */
048 int SET = 1;
049
050 /**
051 * An {@link Notification#getEventType event type} indicating that
052 * a feature of the notifier has been unset.
053 * This applies for unsettable features.
054 * @see Notification#getEventType
055 */
056 int UNSET = 2;
057
058 /**
059 * An {@link Notification#getEventType event type} indicating that
060 * a value has been inserted into a list-based feature of the notifier.
061 * @see Notification#getEventType
062 */
063 int ADD = 3;
064
065 /**
066 * An {@link Notification#getEventType event type} indicating that
067 * a value has been removed from a list-based feature of the notifier.
068 * @see Notification#getEventType
069 */
070 int REMOVE = 4;
071
072 /**
073 * An {@link Notification#getEventType event type} indicating that
074 * a several values have been added into a list-based feature of the notifier.
075 * @see Notification#getEventType
076 */
077 int ADD_MANY = 5;
078
079 /**
080 * An {@link Notification#getEventType event type} indicating that
081 * a several values have been removed from a list-based feature of the notifier.
082 * @see Notification#getEventType
083 */
084 int REMOVE_MANY = 6;
085
086 /**
087 * An {@link Notification#getEventType event type} indicating that
088 * a value has been moved within a list-based feature of the notifier.
089 * @see Notification#getEventType
090 */
091 int MOVE = 7;
092
093 /**
094 * An {@link Notification#getEventType event type} indicating that
095 * an adapter is being removed from the notifier.
096 * @see Notification#getEventType
097 */
098 int REMOVING_ADAPTER = 8;
099
100 /**
101 * An {@link Notification#getEventType event type} indicating that
102 * a feature of the notifier has been resolved from a proxy.
103 * @see Notification#getEventType
104 */
105 int RESOLVE = 9;
106
107 /**
108 * The number of built-in {@link Notification#getEventType event types}.
109 * User defined event types should start from this value.
110 * Clients are expected to ignore types they don't recognize.
111 * @see Notification#getEventType
112 */
113 int EVENT_TYPE_COUNT = 10;
114
115 /**
116 * Returns the type of change that has occurred.
117 * The valid types of events are defined by the constants in this class.
118 * @return the type of change that has occurred.
119 * @see Notifier
120 */
121 int getEventType();
122
123 /**
124 * An {@link Notification#getFeatureID ID} indicating that
125 * no feature ID information is applicable.
126 * @see Notification#getFeatureID
127 */
128 int NO_FEATURE_ID = -1;
129
130 /**
131 * Returns the numeric ID of the feature relative to the given class, or {@link #NO_FEATURE_ID} when not applicable.
132 * @param expectedClass the class to which the ID is relative.
133 * @return the numeric ID of the feature.
134 * @see #NO_FEATURE_ID
135 */
136 int getFeatureID(Class<?> expectedClass);
137
138 /**
139 * Returns the object representing the feature of the notifier that has changed.
140 * @return the feature that has changed.
141 */
142 Object getFeature();
143
144 /**
145 * Returns the value of the notifier's feature before the change occurred.
146 * For a list-based feature, this represents a value, or a list of values, removed from the list.
147 * For a move, this represents the old position of the moved value.
148 * @return the old value of the notifier's feature.
149 */
150 Object getOldValue();
151
152 /**
153 * Returns the value of the notifier's feature after the change occurred.
154 * For a list-based feature, this represents a value, or a list of values, added to the list.
155 * @return the new value of the notifier's feature.
156 */
157 Object getNewValue();
158
159 /**
160 * Returns whether the notifier's feature was considered set before the change occurred.
161 * @return whether the notifier's feature was considered set before the change occurred.
162 */
163 boolean wasSet();
164
165 /**
166 * Returns true if this notification represents an event that did not change the state of the notifying object.
167 * For the events {@link #ADD}, {@link #ADD_MANY}, {@link #REMOVE}, {@link #REMOVE_MANY}, {@link #MOVE},
168 * it always returns false.
169 * For the events {@link #RESOLVE} and {@link #REMOVING_ADAPTER} it always returns true.
170 * For the events {@link #SET} and {@link #UNSET} it returns true if the old and the new value are equal;
171 * In addition, for certain types of features there may be a distinction between
172 * being set to a default value and not being set at all, which implies that it has the default value.
173 * In this situation, even in the case that the old and new values are equal,
174 * isTouch may never the less return false in order to indicate that, although the value has not changed,
175 * the feature has gone from simply having a default value to being set to that same default value,
176 * or has gone from being set to the default value back to being unset.
177 * @return whether or not this is a state changing modification.
178 */
179 boolean isTouch();
180
181 /**
182 * Returns true if the notification's feature has been set to its default value.
183 * @return whether or not this is a feature reset event.
184 */
185 boolean isReset();
186
187 /**
188 * An {@link Notification#getPosition index} indicating that
189 * no position information is applicable.
190 * @see Notification#getPosition
191 */
192 int NO_INDEX = -1;
193
194 /**
195 * Returns the position within a list-based feature at which the change occurred.
196 * It returns {@link #NO_INDEX} when not applicable.
197 * @return the position at which the change occurred.
198 */
199 int getPosition();
200
201 /**
202 * Returns whether the notification can be and has been merged with this one.
203 * @return whether the notification can be and has been merged with this one.
204 */
205 boolean merge(Notification notification);
206
207 /**
208 * Returns the old value of the notifier's feature, if it is of type <code>boolean</code>.
209 * @return the old value of the notifier's feature.
210 * @exception IllegalStateException if the feature isn't <code>boolean</code>.
211 */
212 boolean getOldBooleanValue();
213
214 /**
215 * Returns the new value of the notifier's feature, if it is of type <code>boolean</code>.
216 * @return the new value of the notifier's feature.
217 * @exception IllegalStateException if the feature isn't <code>boolean</code>.
218 */
219 boolean getNewBooleanValue();
220
221 /**
222 * Returns the old value of the notifier's feature, if it is of type <code>byte</code>.
223 * @return the old value of the notifier's feature.
224 * @exception IllegalStateException if the feature isn't <code>byte</code>.
225 */
226 byte getOldByteValue();
227
228 /**
229 * Returns the new value of the notifier's feature, if it is of type <code>byte</code>.
230 * @return the new value of the notifier's feature.
231 * @exception IllegalStateException if the feature isn't <code>byte</code>.
232 */
233 byte getNewByteValue();
234
235 /**
236 * Returns the old value of the notifier's feature, if it is of type <code>char</code>.
237 * @return the old value of the notifier's feature.
238 * @exception IllegalStateException if the feature isn't <code>char</code>.
239 */
240 char getOldCharValue();
241
242 /**
243 * Returns the new value of the notifier's feature, if it is of type <code>char</code>.
244 * @return the new value of the notifier's feature.
245 * @exception IllegalStateException if the feature isn't <code>char</code>.
246 */
247 char getNewCharValue();
248
249 /**
250 * Returns the old value of the notifier's feature, if it is of type <code>double</code>.
251 * @return the old value of the notifier's feature.
252 * @exception IllegalStateException if the feature isn't <code>double</code>.
253 */
254 double getOldDoubleValue();
255
256 /**
257 * Returns the new value of the notifier's feature, if it is of type <code>double</code>.
258 * @return the new value of the notifier's feature.
259 * @exception IllegalStateException if the feature isn't <code>double</code>.
260 */
261 double getNewDoubleValue();
262
263 /**
264 * Returns the old value of the notifier's feature, if it is of type <code>float</code>.
265 * @return the old value of the notifier's feature.
266 * @exception IllegalStateException if the feature isn't <code>float</code>.
267 */
268 float getOldFloatValue();
269
270 /**
271 * Returns the new value of the notifier's feature, if it is of type <code>float</code>.
272 * @return the new value of the notifier's feature.
273 * @exception IllegalStateException if the feature isn't <code>float</code>.
274 */
275 float getNewFloatValue();
276
277 /**
278 * Returns the old value of the notifier's feature, if it is of type <code>int</code>.
279 * @return the old value of the notifier's feature.
280 * @exception IllegalStateException if the feature isn't <code>int</code>.
281 */
282 int getOldIntValue();
283
284 /**
285 * Returns the new value of the notifier's feature, if it is of type <code>int</code>.
286 * @return the new value of the notifier's feature.
287 * @exception IllegalStateException if the feature isn't <code>int</code>.
288 */
289 int getNewIntValue();
290
291 /**
292 * Returns the old value of the notifier's feature, if it is of type <code>long</code>.
293 * @return the old value of the notifier's feature.
294 * @exception IllegalStateException if the feature isn't <code>long</code>.
295 */
296 long getOldLongValue();
297
298 /**
299 * Returns the new value of the notifier's feature, if it is of type <code>long</code>.
300 * @return the new value of the notifier's feature.
301 * @exception IllegalStateException if the feature isn't <code>long</code>.
302 */
303 long getNewLongValue();
304
305 /**
306 * Returns the old value of the notifier's feature, if it is of type <code>short</code>.
307 * @return the old value of the notifier's feature.
308 * @exception IllegalStateException if the feature isn't <code>short</code>.
309 */
310 short getOldShortValue();
311
312 /**
313 * Returns the new value of the notifier's feature, if it is of type <code>short</code>.
314 * @return the new value of the notifier's feature.
315 * @exception IllegalStateException if the feature isn't <code>short</code>.
316 */
317 short getNewShortValue();
318
319 /**
320 * Returns the old value of the notifier's feature as a String.
321 * @return the old value of the notifier's feature.
322 */
323 String getOldStringValue();
324
325 /**
326 * Returns the new value of the notifier's feature as a String.
327 * @return the new value of the notifier's feature.
328 */
329 String getNewStringValue();
330 }