org.millstone.base.ui
Class AbstractField

java.lang.Object
  |
  +--org.millstone.base.ui.AbstractComponent
        |
        +--org.millstone.base.ui.AbstractField

All Implemented Interfaces:

Buffered, BufferedValidatable, Component, java.util.EventListener, MethodEventSource, Paintable, Property, Property.Editor, Property.ReadOnlyStatusChangeNotifier, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer, Validatable, VariableOwner

Direct Known Subclasses:

Button, DateField, Select, TextField

public abstract class AbstractField

extends AbstractComponent

implements BufferedValidatable, Property, Property.Editor, Property.ValueChangeNotifier, Property.ValueChangeListener, Property.ReadOnlyStatusChangeNotifier

Abstract field component for implementing buffered property editors. The field may hold an internal value, or it may be connected to any data source that implements the Property interface. AbstractField implements that interface itself, too, so accessing the Property value represented by it is straightforward.

AbstractField also provides the Buffered interface for buffering the data source value. By default the Field is in write through-mode and setWriteThrough(boolean) should be called to enable buffering.

The class also supports validators to make sure the value contained in the field is valid.

Since:

3.0

Version:

3.0.3

Author:

IT Mill Ltd.

Nested Class Summary

class	AbstractField.ReadOnlyStatusChangeEvent An Event object specifying the Property whose read-only status has changed.
class	AbstractField.ValueChangeEvent An Event object specifying the Property whose value has been changed.

Nested classes inherited from class org.millstone.base.data.Buffered

Buffered.SourceException

Nested classes inherited from class org.millstone.base.data.Property

Property.ConversionException, Property.Editor, Property.ReadOnlyException, Property.ReadOnlyStatusChangeListener, Property.ReadOnlyStatusChangeNotifier, Property.ValueChangeListener, Property.ValueChangeNotifier, Property.Viewer

Nested classes inherited from class org.millstone.base.ui.Component

Component.Listener

Nested classes inherited from class org.millstone.base.terminal.Paintable

Paintable.RepaintRequestEvent, Paintable.RepaintRequestListener

Constructor Summary

AbstractField()

Method Summary

void	addListener(Property.ReadOnlyStatusChangeListener listener) Registers a new read-only status change listener for this Property.
void	addListener(Property.ValueChangeListener listener) Registers a new value change listener for this Property.
void	addValidator(Validator validator) Adds a new validator for the field's value.
void	commit() Updates all changes since the previous commit to the data source.
static AbstractField	constructField(java.lang.Class propertyType) Create field by the type of the property.
void	discard() Discards all changes since last commit.
protected void	fireReadOnlyStatusChange() Emit a read-only status change event.
protected void	fireValueChange() Emit a value change event.
void	focus() Ask the terminal to place the cursor to this field.
ErrorMessage	getErrorMessage() Error messages shown by the fields are composites of the error message thrown by the superclasses (that is the component error message), validation errors and buffered source errors.
Property	getPropertyDataSource() Gets the current data source of the field, if any.
abstract java.lang.Class	getType() Returns the type of the Property.
java.util.Collection	getValidators() Gets the validators of the field.
java.lang.Object	getValue() Gets the current value of the field.
boolean	isInvalidAllowed() Fields allow invalid values by default.
boolean	isInvalidCommitted() Is the invalid data committed to datasource.
boolean	isModified() Tests if the value stored in the object has been modified since it was last updated from the data source.
boolean	isReadOnly() The abstract field is read only also if the data source is in readonly mode.
boolean	isReadThrough() Tests if the object is in read-through mode.
boolean	isValid() Tests the current value against all registered validators.
boolean	isWriteThrough() Tests if the object is in write-through mode.
void	paintContent(PaintTarget target) Paints any needed component-specific things to the given UIDL stream.
void	removeListener(Property.ReadOnlyStatusChangeListener listener) Remove a previously registered read-only status change listener.
void	removeListener(Property.ValueChangeListener listener) Removes a previously registered value change listener.
void	removeValidator(Validator validator) Removes a validator from the field.
void	setInvalidAllowed(boolean invalidAllowed) Fields allow invalid values by default.
void	setInvalidCommitted(boolean isCommitted) Set if the invalid data should be committed to datasource.
void	setPropertyDataSource(Property newDataSource) Sets the specified Property as the data source for the field.
void	setReadOnly(boolean readOnly) Change the readonly state and throw read-only status change events.
void	setReadThrough(boolean readTrough) Sets the object's read-through mode to the specified status.
void	setValue(java.lang.Object newValue) Set the value of the field.
void	setWriteThrough(boolean writeTrough) Sets the object's write-through mode to the specified status.
java.lang.String	toString() Returns the value of the Property in human readable textual format.
void	validate() Checks the validity of the validatable.
void	valueChange(Property.ValueChangeEvent event) This method listens to data source value changes and passes the changes forwards.

Methods inherited from class org.millstone.base.ui.AbstractComponent

addListener, addListener, addListener, addListener, attach, changeVariables, childRequestedRepaint, dependsOn, detach, fireComponentEvent, fireEvent, getApplication, getCaption, getComponentError, getDescription, getDirectDependencies, getIcon, getLocale, getParent, getStyle, getTag, getWindow, isEnabled, isImmediate, isVisible, paint, removeDirectDependency, removeListener, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintRequests, setCaption, setComponentError, setDescription, setEnabled, setIcon, setImmediate, setLocale, setParent, setStyle, setVisible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

AbstractField

public AbstractField()

Method Detail

paintContent

public void paintContent(PaintTarget target)
                  throws PaintException

Description copied from class: AbstractComponent

Paints any needed component-specific things to the given UIDL stream. The more general AbstractComponent.paint(PaintTarget) method handles all general attributes common to all components, and it calls this method to paint any component-specific attributes to the UIDL stream.

Overrides:

paintContent in class AbstractComponent

Parameters:

target - target UIDL stream where the component should paint itself to

Throws:

PaintException - if the operation failed

getType

public abstract java.lang.Class getType()

Description copied from interface: Property

Returns the type of the Property. The methods getValue and setValue must be compatible with this type: one must be able to safely cast the value returned from getValue to the given type and pass any variable assignable to this type as an argument to setValue.

Specified by:

getType in interface Property

Returns:

type of the Property

isReadOnly

public boolean isReadOnly()

The abstract field is read only also if the data source is in readonly mode.

Specified by:

isReadOnly in interface Property

Overrides:

isReadOnly in class AbstractComponent

Returns:

true if the Property is in read-only mode, false if it's not

setReadOnly

public void setReadOnly(boolean readOnly)

Change the readonly state and throw read-only status change events.

Specified by:

setReadOnly in interface Property

Overrides:

setReadOnly in class AbstractComponent

Parameters:

readOnly - new read-only status of the Property

See Also:

Component.setReadOnly(boolean)

isInvalidCommitted

public boolean isInvalidCommitted()

Description copied from interface: BufferedValidatable

Is the invalid data committed to datasource. The default is false.

Specified by:

isInvalidCommitted in interface BufferedValidatable

setInvalidCommitted

public void setInvalidCommitted(boolean isCommitted)

Description copied from interface: BufferedValidatable

Set if the invalid data should be committed to datasource. The default is false.

Specified by:

setInvalidCommitted in interface BufferedValidatable

commit

public void commit()
            throws Buffered.SourceException

Description copied from interface: Buffered

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.

Specified by:

commit in interface Buffered

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

Description copied from interface: Buffered

Discards all changes since last commit. The object updates its value from the data source.

Specified by:

discard in interface Buffered

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()

Description copied from interface: Buffered

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

Specified by:

isModified in interface Buffered

Returns:

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

isWriteThrough

public boolean isWriteThrough()

Description copied from interface: Buffered

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.

Specified by:

isWriteThrough in interface Buffered

Returns:

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

setWriteThrough

public void setWriteThrough(boolean writeTrough)
                     throws Buffered.SourceException

Description copied from interface: Buffered

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

Specified by:

setWriteThrough in interface Buffered

Parameters:

writeTrough - Boolean value to indicate if the object should be in write-through mode after the call.

Buffered.SourceException

isReadThrough

public boolean isReadThrough()

Description copied from interface: Buffered

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.

Specified by:

isReadThrough in interface Buffered

Returns:

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

setReadThrough

public void setReadThrough(boolean readTrough)
                    throws Buffered.SourceException

Description copied from interface: Buffered

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.

Specified by:

setReadThrough in interface Buffered

Parameters:

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

toString

public java.lang.String toString()

Returns the value of the Property in human readable textual format.

Specified by:

toString in interface Property

Overrides:

toString in class java.lang.Object

Returns:

String representation of the value stored in the Property

getValue

public java.lang.Object getValue()

Gets the current value of the field. This is the visible, modified and possible invalid value the user have entered to the field. In the read-through mode, the abstract buffer is also updated and validation is performed.

Specified by:

getValue in interface Property

Returns:

the current value of the field

setValue

public void setValue(java.lang.Object newValue)
              throws Property.ReadOnlyException,
                     Property.ConversionException

Set the value of the field.

Specified by:

setValue in interface Property

Parameters:

newValue - New value of the field.

Throws:

Property.ConversionException - if newValue can't be converted into the Property's native type directly or through String

Property.ReadOnlyException - if the object is in read-only mode

getPropertyDataSource

public Property getPropertyDataSource()

Gets the current data source of the field, if any.

Specified by:

getPropertyDataSource in interface Property.Viewer

Returns:

The current data source as a Property, or null if none defined.

setPropertyDataSource

public void setPropertyDataSource(Property newDataSource)

Sets the specified Property as the data source for the field. All uncommitted changes to the field are discarded and the value is refreshed from the new data source.

If the datasource has any validators, the same validators are added to the field. Because the default behavior of the field is to allow invalid values, but not to allow committing them, this only adds visual error messages to fields and do not allow committing them as long as the value is invalid. After the value is valid, the error message is not shown and the commit can be done normally.

Specified by:

setPropertyDataSource in interface Property.Viewer

Parameters:

newDataSource - the new data source Property

addValidator

public void addValidator(Validator validator)

Adds a new validator for the field's value. All validators added to a field are checked each time the its value changes.

Specified by:

addValidator in interface Validatable

Parameters:

validator - the new validator to be added

getValidators

public java.util.Collection getValidators()

Gets the validators of the field.

Specified by:

getValidators in interface Validatable

Returns:

Unmodifiable collection that holds all validators for the field.

removeValidator

public void removeValidator(Validator validator)

Removes a validator from the field.

Specified by:

removeValidator in interface Validatable

Parameters:

validator - the validator to remove

isValid

public boolean isValid()

Tests the current value against all registered validators.

Specified by:

isValid in interface Validatable

Returns:

true if all registered validators claim that the current value is valid, false otherwise

validate

public void validate()
              throws Validator.InvalidValueException

Description copied from interface: Validatable

Checks the validity of the validatable. If the validatable is valid this method should do nothing, and if it's not valid, it should throw Validator.InvalidValueException

Specified by:

validate in interface Validatable

Throws:

Validator.InvalidValueException - if the value is not valid

isInvalidAllowed

public boolean isInvalidAllowed()

Fields allow invalid values by default. In most cases this is wanted, because the field otherwise visually forget the user input immediately.

Specified by:

isInvalidAllowed in interface Validatable

Returns:

true iff the invalid values are allowed.

See Also:

Validatable.isInvalidAllowed()

setInvalidAllowed

public void setInvalidAllowed(boolean invalidAllowed)
                       throws java.lang.UnsupportedOperationException

Fields allow invalid values by default. In most cases this is wanted, because the field otherwise visually forget the user input immediately. In common setting where the user wants to assure the correctness of the datasource, but allow temporarily invalid contents in the field, the user should add the validators to datasource, that should not allow invalid values. The validators are automatically copied to the field when the datasource is set.

Specified by:

setInvalidAllowed in interface Validatable

java.lang.UnsupportedOperationException

See Also:

Validatable.setInvalidAllowed(boolean)

getErrorMessage

public ErrorMessage getErrorMessage()

Error messages shown by the fields are composites of the error message thrown by the superclasses (that is the component error message), validation errors and buffered source errors.

Overrides:

getErrorMessage in class AbstractComponent

Returns:

ErrorMessage containing the description of the error state of the component or null, if the component contains no errors. Extending classes should override this method if they support other error message types such as validation errors or buffering errors. The returned error message contains information about all the errors.

See Also:

AbstractComponent.getErrorMessage()

addListener

public void addListener(Property.ValueChangeListener listener)

Description copied from interface: Property.ValueChangeNotifier

Registers a new value change listener for this Property.

Specified by:

addListener in interface Property.ValueChangeNotifier

Parameters:

listener - the new Listener to be registered

removeListener

public void removeListener(Property.ValueChangeListener listener)

Description copied from interface: Property.ValueChangeNotifier

Removes a previously registered value change listener.

Specified by:

removeListener in interface Property.ValueChangeNotifier

Parameters:

listener - listener to be removed

fireValueChange

protected void fireValueChange()

Emit a value change event. The value contained in the field is validated before the event is created.

addListener

public void addListener(Property.ReadOnlyStatusChangeListener listener)

Description copied from interface: Property.ReadOnlyStatusChangeNotifier

Registers a new read-only status change listener for this Property.

Specified by:

addListener in interface Property.ReadOnlyStatusChangeNotifier

Parameters:

listener - the new Listener to be registered

removeListener

public void removeListener(Property.ReadOnlyStatusChangeListener listener)

Description copied from interface: Property.ReadOnlyStatusChangeNotifier

Remove a previously registered read-only status change listener.

Specified by:

removeListener in interface Property.ReadOnlyStatusChangeNotifier

Parameters:

listener - listener to be removed

fireReadOnlyStatusChange

protected void fireReadOnlyStatusChange()

Emit a read-only status change event. The value contained in the field is validated before the event is created.

valueChange

public void valueChange(Property.ValueChangeEvent event)

This method listens to data source value changes and passes the changes forwards.

Specified by:

valueChange in interface Property.ValueChangeListener

Parameters:

event - the value change event telling the data source contents have changed

focus

public void focus()

Ask the terminal to place the cursor to this field.

constructField

public static AbstractField constructField(java.lang.Class propertyType)

Create field by the type of the property.

This returns most suitable field type for editing property of given type

Parameters:

propertyType - Type of the property, that needs to be edited.