1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
|
/*
* Copyright 2000-2016 Vaadin Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License"); you may not
* use this file except in compliance with the License. You may obtain a copy of
* the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
* License for the specific language governing permissions and limitations under
* the License.
*/
package com.vaadin.data;
import java.io.Serializable;
/**
* <p>
* The <code>Property</code> is a simple data object that contains one typed
* value. This interface contains methods to inspect and modify the stored value
* and its type, and the object's read-only state.
* </p>
*
* <p>
* The <code>Property</code> also defines the events
* <code>ReadOnlyStatusChangeEvent</code> and <code>ValueChangeEvent</code>, and
* the associated <code>listener</code> and <code>notifier</code> interfaces.
* </p>
*
* <p>
* The <code>Property.Viewer</code> interface should be used to attach the
* Property to an external data source. This way the value in the data source
* can be inspected using the <code>Property</code> interface.
* </p>
*
* <p>
* The <code>Property.editor</code> interface should be implemented if the value
* needs to be changed through the implementing class.
* </p>
*
* @param T
* type of values of the property
*
* @author Vaadin Ltd
* @since 3.0
*/
public interface Property<T> extends Serializable {
/**
* Gets the value stored in the Property. The returned object is compatible
* with the class returned by getType().
*
* @return the value stored in the Property
*/
public T getValue();
/**
* Sets the value of the Property.
* <p>
* Implementing this functionality is optional. If the functionality is
* missing, one should declare the Property to be in read-only mode and
* throw <code>Property.ReadOnlyException</code> in this function.
* </p>
*
* Note : Since Vaadin 7.0, setting the value of a non-String property as a
* String is no longer supported.
*
* @param newValue
* New value of the Property. This should be assignable to the
* type returned by getType
*
* @throws Property.ReadOnlyException
* if the object is in read-only mode
*/
public void setValue(T newValue) throws Property.ReadOnlyException;
/**
* Returns the type of the Property. The methods <code>getValue</code> and
* <code>setValue</code> must be compatible with this type: one must be able
* to safely cast the value returned from <code>getValue</code> to the given
* type and pass any variable assignable to this type as an argument to
* <code>setValue</code>.
*
* @return type of the Property
*/
public Class<? extends T> getType();
/**
* Tests if the Property is in read-only mode. In read-only mode calls to
* the method <code>setValue</code> will throw
* <code>ReadOnlyException</code> and will not modify the value of the
* Property.
*
* @return <code>true</code> if the Property is in read-only mode,
* <code>false</code> if it's not
*/
public boolean isReadOnly();
/**
* Sets the Property's read-only mode to the specified status.
*
* This functionality is optional, but all properties must implement the
* <code>isReadOnly</code> mode query correctly.
*
* @param newStatus
* new read-only status of the Property
*/
public void setReadOnly(boolean newStatus);
/**
* A Property that is capable of handle a transaction that can end in commit
* or rollback.
*
* Note that this does not refer to e.g. database transactions but rather
* two-phase commit that allows resetting old field values (in e.g. a
* FieldGroup) if the commit of one of the properties fails after other
* properties have already been committed.
*
* @param <T>
* The type of the property
* @author Vaadin Ltd
* @since 7.0
*/
public interface Transactional<T> extends Property<T> {
/**
* Starts a transaction.
*
* <p>
* If the value is set during a transaction the value must not replace
* the original value until {@link #commit()} is called. Still,
* {@link #getValue()} must return the current value set in the
* transaction. Calling {@link #rollback()} while in a transaction must
* rollback the value to what it was before the transaction started.
* </p>
* <p>
* {@link ValueChangeEvent}s must not be emitted for internal value
* changes during a transaction. If the value changes as a result of
* {@link #commit()}, a {@link ValueChangeEvent} should be emitted.
* </p>
*/
public void startTransaction();
/**
* Commits and ends the transaction that is in progress.
* <p>
* If the value is changed as a result of this operation, a
* {@link ValueChangeEvent} is emitted if such are supported.
* <p>
* This method has no effect if there is no transaction is in progress.
* <p>
* This method must never throw an exception.
*/
public void commit();
/**
* Aborts and rolls back the transaction that is in progress.
* <p>
* The value is reset to the value before the transaction started. No
* {@link ValueChangeEvent} is emitted as a result of this.
* <p>
* This method has no effect if there is no transaction is in progress.
* <p>
* This method must never throw an exception.
*/
public void rollback();
}
/**
* <code>Exception</code> object that signals that a requested Property
* modification failed because it's in read-only mode.
*
* @author Vaadin Ltd.
* @since 3.0
*/
@SuppressWarnings("serial")
public class ReadOnlyException extends RuntimeException {
/**
* Constructs a new <code>ReadOnlyException</code> without a detail
* message.
*/
public ReadOnlyException() {
}
/**
* Constructs a new <code>ReadOnlyException</code> with the specified
* detail message.
*
* @param msg
* the detail message
*/
public ReadOnlyException(String msg) {
super(msg);
}
}
/**
* Interface implemented by the viewer classes capable of using a Property
* as a data source.
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface Viewer extends Serializable {
/**
* Sets the Property that serves as the data source of the viewer.
*
* @param newDataSource
* the new data source Property
*/
public void setPropertyDataSource(Property newDataSource);
/**
* Gets the Property serving as the data source of the viewer.
*
* @return the Property serving as the viewers data source
*/
public Property getPropertyDataSource();
}
/**
* Interface implemented by the editor classes capable of editing the
* Property.
* <p>
* Implementing this interface means that the Property serving as the data
* source of the editor can be modified through the editor. It does not
* restrict the editor from editing the Property internally, though if the
* Property is in a read-only mode, attempts to modify it will result in the
* <code>ReadOnlyException</code> being thrown.
* </p>
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface Editor extends Property.Viewer, Serializable {
}
/* Value change event */
/**
* An <code>Event</code> object specifying the Property whose value has been
* changed.
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface ValueChangeEvent extends Serializable {
/**
* Retrieves the Property that has been modified.
*
* @return source Property of the event
*/
public Property getProperty();
}
/**
* The <code>listener</code> interface for receiving
* <code>ValueChangeEvent</code> objects.
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface ValueChangeListener extends Serializable {
/**
* Notifies this listener that the Property's value has changed.
*
* @param event
* value change event object
*/
public void valueChange(Property.ValueChangeEvent event);
}
/**
* The interface for adding and removing <code>ValueChangeEvent</code>
* listeners. If a Property wishes to allow other objects to receive
* <code>ValueChangeEvent</code> generated by it, it must implement this
* interface.
* <p>
* Note : The general Java convention is not to explicitly declare that a
* class generates events, but to directly define the
* <code>addListener</code> and <code>removeListener</code> methods. That
* way the caller of these methods has no real way of finding out if the
* class really will send the events, or if it just defines the methods to
* be able to implement an interface.
* </p>
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface ValueChangeNotifier extends Serializable {
/**
* Registers a new value change listener for this Property.
*
* @param listener
* the new Listener to be registered
*/
public void addValueChangeListener(
Property.ValueChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #addValueChangeListener(ValueChangeListener)}
**/
@Deprecated
public void addListener(Property.ValueChangeListener listener);
/**
* Removes a previously registered value change listener.
*
* @param listener
* listener to be removed
*/
public void removeValueChangeListener(
Property.ValueChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #removeValueChangeListener(ValueChangeListener)}
**/
@Deprecated
public void removeListener(Property.ValueChangeListener listener);
}
/* ReadOnly Status change event */
/**
* An <code>Event</code> object specifying the Property whose read-only
* status has been changed.
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface ReadOnlyStatusChangeEvent extends Serializable {
/**
* Property whose read-only state has changed.
*
* @return source Property of the event.
*/
public Property getProperty();
}
/**
* The listener interface for receiving
* <code>ReadOnlyStatusChangeEvent</code> objects.
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface ReadOnlyStatusChangeListener extends Serializable {
/**
* Notifies this listener that a Property's read-only status has
* changed.
*
* @param event
* Read-only status change event object
*/
public void readOnlyStatusChange(
Property.ReadOnlyStatusChangeEvent event);
}
/**
* The interface for adding and removing
* <code>ReadOnlyStatusChangeEvent</code> listeners. If a Property wishes to
* allow other objects to receive <code>ReadOnlyStatusChangeEvent</code>
* generated by it, it must implement this interface.
* <p>
* Note : The general Java convention is not to explicitly declare that a
* class generates events, but to directly define the
* <code>addListener</code> and <code>removeListener</code> methods. That
* way the caller of these methods has no real way of finding out if the
* class really will send the events, or if it just defines the methods to
* be able to implement an interface.
* </p>
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface ReadOnlyStatusChangeNotifier extends Serializable {
/**
* Registers a new read-only status change listener for this Property.
*
* @param listener
* the new Listener to be registered
*/
public void addReadOnlyStatusChangeListener(
Property.ReadOnlyStatusChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #addReadOnlyStatusChangeListener(ReadOnlyStatusChangeListener)}
**/
@Deprecated
public void addListener(Property.ReadOnlyStatusChangeListener listener);
/**
* Removes a previously registered read-only status change listener.
*
* @param listener
* listener to be removed
*/
public void removeReadOnlyStatusChangeListener(
Property.ReadOnlyStatusChangeListener listener);
/**
* @deprecated As of 7.0, replaced by
* {@link #removeReadOnlyStatusChangeListener(ReadOnlyStatusChangeListener)}
**/
@Deprecated
public void removeListener(
Property.ReadOnlyStatusChangeListener listener);
}
}
|