com.vaadin.data
Interface Buffered

All Superinterfaces:
Serializable
All Known Subinterfaces:
BufferedValidatable, Field<T>
All Known Implementing Classes:
AbstractField, AbstractSelect, AbstractTextField, CheckBox, ComboBox, CustomField, DateField, Form, InlineDateField, ListSelect, NativeSelect, OptionGroup, PasswordField, PopupDateField, ProgressIndicator, RichTextArea, Select, Slider, Table, TextArea, TextField, Tree, TreeTable, TwinColSelect

public interface Buffered
extends Serializable

Defines the interface to commit and discard changes to an object, supporting read-through and write-through modes.

Read-through mode means that the value read from the buffered object is constantly up to date with the data source. Write-through mode means that all changes to the object are immediately updated to the data source.

Since these modes are independent, their combinations may result in some behaviour that may sound surprising.

For example, if a Buffered object is in read-through mode but not in write-through mode, the result is an object whose value is updated directly from the data source only if it's not locally modified. If the value is locally modified, retrieving the value from the object would result in a value that is different than the one stored in the data source, even though the object is in read-through mode.

Since:
3.0
Version:
7.0.0.alpha3
Author:
Vaadin Ltd.

Nested Class Summary
static class Buffered.SourceException
          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.
 
Method Summary
 void commit()
          Updates all changes since the previous commit to the data source.
 void discard()
          Discards all changes since last commit.
 boolean isBuffered()
          Checks the buffered mode of this Object.
 boolean isModified()
          Tests if the value stored in the object has been modified since it was last updated from the data source.
 boolean isReadThrough()
          Deprecated. Use #isBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)
 boolean isWriteThrough()
          Deprecated. Use setBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)
 void setBuffered(boolean buffered)
          Sets the object's buffered mode to the specified status.
 void setReadThrough(boolean readThrough)
          Deprecated. Use setBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)
 void setWriteThrough(boolean writeThrough)
          Deprecated. Use setBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)
 

Method Detail

commit

void commit()
            throws Buffered.SourceException,
                   Validator.InvalidValueException
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 commit is called.

Throws:
Buffered.SourceException - if the operation fails because of an exception is thrown by the data source. The cause is included in the exception.
Validator.InvalidValueException - if the operation fails because validation is enabled and the values do not validate

discard

void discard()
             throws Buffered.SourceException
Discards all changes since last commit. The object updates its value from the data source.

Throws:
Buffered.SourceException - if the operation fails because of an exception is thrown by the data source. The cause is included in the exception.

isWriteThrough

@Deprecated
boolean isWriteThrough()
Deprecated. Use setBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)

Tests if the object is in write-through mode. If the object is in write-through mode, all modifications to it will result in commit being called after the modification.

Returns:
true if the object is in write-through mode, false if it's not.

setWriteThrough

@Deprecated
void setWriteThrough(boolean writeThrough)
                     throws Buffered.SourceException,
                            Validator.InvalidValueException
Deprecated. Use setBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)

Sets the object's write-through mode to the specified status. When switching the write-through mode on, the commit operation will be performed.

Parameters:
writeThrough - Boolean value to indicate if the object should be in write-through mode after the call.
Throws:
Buffered.SourceException - If the operation fails because of an exception is thrown by the data source.
Validator.InvalidValueException - If the implicit commit operation fails because of a validation error.

isReadThrough

@Deprecated
boolean isReadThrough()
Deprecated. Use #isBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)

Tests if the object is in read-through mode. If the object is in read-through mode, retrieving its value will result in the value being first updated from the data source to the object.

The only exception to this rule is that when the object is not in write-through mode and it's buffer contains a modified value, the value retrieved from the object will be the locally modified value in the buffer which may differ from the value in the data source.

Returns:
true if the object is in read-through mode, false if it's not.

setReadThrough

@Deprecated
void setReadThrough(boolean readThrough)
                    throws Buffered.SourceException
Deprecated. Use setBuffered(boolean) instead. Note that setReadThrough(true), setWriteThrough(true) equals setBuffered(false)

Sets the object's read-through mode to the specified status. When switching read-through mode on, the object's value is updated from the data source.

Parameters:
readThrough - Boolean value to indicate if the object should be in read-through mode after the call.
Throws:
Buffered.SourceException - If the operation fails because of an exception is thrown by the data source. The cause is included in the exception.

setBuffered

void setBuffered(boolean buffered)
Sets the object's buffered mode to the specified status.

When the object is in buffered mode, an internal buffer will be used to store changes until commit() is called. Calling discard() will revert the internal buffer to the value of the data source.

This is an easier way to use setReadThrough(boolean) and setWriteThrough(boolean) and not as error prone. Changing buffered mode will change both the read through and write through state of the object.

Mixing calls to setBuffered(boolean)/isBuffered() and setReadThrough(boolean)/isReadThrough() or setWriteThrough(boolean)/isWriteThrough() is generally a bad idea.

Parameters:
buffered - true if buffered mode should be turned on, false otherwise
Since:
7.0

isBuffered

boolean isBuffered()
Checks the buffered mode of this Object.

This method only returns true if both read and write buffering is used.

Returns:
true if buffered mode is on, false otherwise
Since:
7.0

isModified

boolean isModified()
Tests if the value stored in the object has been modified since it was last updated from the data source.

Returns:
true if the value in the object has been modified since the last data source update, false if not.


Copyright © 2000-2011 Vaadin Ltd. All Rights Reserved.