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
|
/*
* Copyright 2000-2014 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;
import com.vaadin.data.Validator.InvalidValueException;
/**
* <p>
* Defines the interface to commit and discard changes to an object, supporting
* buffering.
*
* <p>
* In <i>buffered</i> mode the initial value is read from the data source and
* then buffered. Any subsequential writes or reads will be done on the buffered
* value. Calling {@link #commit()} will write the buffered value to the data
* source while calling {@link #discard()} while discard the buffered value and
* re-read the value from the data source.
*
* <p>
* In <i>non-buffered</i> mode the value is always read directly from the data
* source. Any write is done directly to the data source with no buffering in
* between. Reads are also done directly from the data source. Calling
* {@link #commit()} or {@link #discard()} in this mode is efficiently a no-op.
*
* @author Vaadin Ltd.
* @since 3.0
*/
public interface Buffered extends Serializable {
/**
* Updates all changes since the previous commit to the data source. The
* value stored in the object will always be updated into the data source
* when <code>commit</code> is called.
*
* @throws SourceException
* if the operation fails because of an exception is thrown by
* the data source. The cause is included in the exception.
* @throws InvalidValueException
* if the operation fails because validation is enabled and the
* values do not validate
*/
public void commit() throws SourceException, InvalidValueException;
/**
* Discards all changes since last commit. The object updates its value from
* the data source.
*
* @throws SourceException
* if the operation fails because of an exception is thrown by
* the data source. The cause is included in the exception.
*/
public void discard() throws SourceException;
/**
* Sets the buffered mode to the specified status.
* <p>
* When in buffered mode, an internal buffer will be used to store changes
* until {@link #commit()} is called. Calling {@link #discard()} will revert
* the internal buffer to the value of the data source.
* <p>
* When in non-buffered mode both read and write operations will be done
* directly on the data source. In this mode the {@link #commit()} and
* {@link #discard()} methods serve no purpose.
*
* @param buffered
* true if buffered mode should be turned on, false otherwise
* @since 7.0
*/
public void setBuffered(boolean buffered);
/**
* Checks the buffered mode
*
* @return true if buffered mode is on, false otherwise
* @since 7.0
*/
public boolean isBuffered();
/**
* Tests if the value stored in the object has been modified since it was
* last updated from the data source.
*
* @return <code>true</code> if the value in the object has been modified
* since the last data source update, <code>false</code> if not.
*/
public boolean isModified();
/**
* An exception that signals that one or more exceptions occurred while a
* buffered object tried to access its data source or if there is a problem
* in processing a data source.
*
* @author Vaadin Ltd.
* @since 3.0
*/
@SuppressWarnings("serial")
public class SourceException extends RuntimeException implements
Serializable {
/** Source class implementing the buffered interface */
private final Buffered source;
/** Original cause of the source exception */
private Throwable[] causes = {};
/**
* Creates a source exception that does not include a cause.
*
* @param source
* the source object implementing the Buffered interface.
*/
public SourceException(Buffered source) {
this.source = source;
}
/**
* Creates a source exception from multiple causes.
*
* @param source
* the source object implementing the Buffered interface.
* @param causes
* the original causes for this exception.
*/
public SourceException(Buffered source, Throwable... causes) {
this.source = source;
this.causes = causes;
}
/**
* Gets the cause of the exception.
*
* @return The (first) cause for the exception, null if no cause.
*/
@Override
public final Throwable getCause() {
if (causes.length == 0) {
return null;
}
return causes[0];
}
/**
* Gets all the causes for this exception.
*
* @return throwables that caused this exception
*/
public final Throwable[] getCauses() {
return causes;
}
/**
* Gets a source of the exception.
*
* @return the Buffered object which generated this exception.
*/
public Buffered getSource() {
return source;
}
}
}
|
