org.millstone.base.data
Interface Buffered

All Known Subinterfaces:

BufferedValidatable

All Known Implementing Classes:

AbstractField, Form

public interface Buffered

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:

3.0.3

Author:

IT Mill 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.

Method Summary

void	commit() Updates all changes since the previous commit to the data source.
void	discard() Discards all changes since last commit.
boolean	isModified() Tests if the value stored in the object has been modified since it was last updated from the data source.
boolean	isReadThrough() Tests if the object is in read-through mode.
boolean	isWriteThrough() Tests if the object is in write-through mode.
void	setReadThrough(boolean readThrough) Sets the object's read-through mode to the specified status.
void	setWriteThrough(boolean writeThrough) Sets the object's write-through mode to the specified status.

Method Detail

commit

public void commit()
            throws Buffered.SourceException

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.

discard

public 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

public boolean isWriteThrough()

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

public void setWriteThrough(boolean writeThrough)
                     throws Buffered.SourceException

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.

Buffered.SourceException

isReadThrough

public boolean isReadThrough()

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

public void setReadThrough(boolean readThrough)
                    throws Buffered.SourceException

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.

isModified

public 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.