com.itmill.toolkit.ui
Class AbstractField

java.lang.Object
  com.itmill.toolkit.terminal.Identifiable
      com.itmill.toolkit.ui.AbstractComponent
          com.itmill.toolkit.ui.AbstractField

All Implemented Interfaces:

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

Direct Known Subclasses:

Button, DateField, Form, ProgressIndicator, Select, TextField

public abstract class AbstractField
extends AbstractComponent
implements Field, 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 Propertyinterface. 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:

4.1.4

Author:

IT Mill Ltd.

Nested Class Summary

class

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

Nested classes/interfaces inherited from interface com.itmill.toolkit.ui.Field

Field.ValueChangeEvent

Nested classes/interfaces inherited from interface com.itmill.toolkit.ui.Component

Component.ErrorEvent, Component.ErrorListener, Component.Event, Component.Focusable, Component.Listener

Nested classes/interfaces inherited from interface com.itmill.toolkit.terminal.Paintable

Paintable.RepaintRequestEvent, Paintable.RepaintRequestListener

Nested classes/interfaces inherited from interface com.itmill.toolkit.data.Buffered

Buffered.SourceException

Nested classes/interfaces inherited from interface com.itmill.toolkit.data.Property

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

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	attach() Notifies the component that it is connected to an application.
void	commit() Updates all changes since the previous commit to the data source.
static AbstractField	constructField(Class propertyType) Creates abstract field by the type of the property.
void	discard() Discards all changes since last commit.
void	finalize() Free used resources.
protected void	fireReadOnlyStatusChange() Emits the read-only status change event.
protected void	fireValueChange() Emits the value change event.
void	focus() Asks 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.
long	getFocusableId() Gets the unique ID of focusable
Property	getPropertyDataSource() Gets the current data source of the field, if any.
int	getTabIndex() Gets the tab index of this field.
abstract Class	getType() Returns the type of the Property.
Collection	getValidators() Gets the validators of the field.
Object	getValue() Gets the current value of the field.
boolean	isInvalidAllowed() Fields allow invalid values by default.
boolean	isInvalidCommitted() Tests if the invalid data is 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	isRequired() Is this field required.
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) Removes 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 the validator from the field.
protected void	setInternalValue(Object newValue) Sets the internal field value.
void	setInvalidAllowed(boolean invalidAllowed) Fields allow invalid values by default.
void	setInvalidCommitted(boolean isCommitted) Sets 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) Changes 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	setRequired(boolean required) Sets the field required.
void	setTabIndex(int tabIndex) Gets the tab index of this field.
void	setValue(Object newValue) Sets the value of the field.
void	setWriteThrough(boolean writeTrough) Sets the object's write-through mode to the specified status.
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 com.itmill.toolkit.ui.AbstractComponent

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

Methods inherited from class com.itmill.toolkit.terminal.Identifiable

getDebugId, getUIID, setDebugId, setUIID

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.itmill.toolkit.ui.Field

getDescription, setCaption, setDescription

Methods inherited from interface com.itmill.toolkit.ui.Component

addListener, childRequestedRepaint, detach, getApplication, getCaption, getIcon, getLocale, getParent, getStyle, getWindow, isEnabled, isVisible, removeListener, setEnabled, setParent, setStyle, setVisible

Methods inherited from interface com.itmill.toolkit.terminal.Paintable

addListener, paint, removeListener, requestRepaint, requestRepaintRequests

Methods inherited from interface com.itmill.toolkit.terminal.VariableOwner

changeVariables, dependsOn, getDirectDependencies, isImmediate, removeDirectDependency

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 - the target UIDL stream where the component should paint itself to

Throws:

PaintException - if the paint operation failed.

getType

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

Specified by:

isReadOnly in interface Component

Overrides:

isReadOnly in class AbstractComponent

Returns:

true if the component is in read-only mode, false if not.

setReadOnly

public void setReadOnly(boolean readOnly)

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

Specified by:

setReadOnly in interface Property

Specified by:

setReadOnly in interface Component

Overrides:

setReadOnly in class AbstractComponent

Parameters:

readOnly - the boolean value specifying if the component should be in read-only mode after the call or not.

See Also:

Component.setReadOnly(boolean)

isInvalidCommitted

public boolean isInvalidCommitted()

Tests if the invalid data is committed to datasource.

Specified by:

isInvalidCommitted in interface BufferedValidatable

See Also:

BufferedValidatable.isInvalidCommitted()

setInvalidCommitted

public void setInvalidCommitted(boolean isCommitted)

Sets if the invalid data should be committed to datasource.

Specified by:

setInvalidCommitted in interface BufferedValidatable

See Also:

BufferedValidatable.setInvalidCommitted(boolean)

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.

Throws:

Buffered.SourceException - If the operation fails because of an exception is thrown by the data source.

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

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

Specified by:

toString in interface Property

Overrides:

toString in class Object

Returns:

String representation of the value stored in the Property

See Also:

Object.toString()

getValue

public 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(Object newValue)
              throws Property.ReadOnlyException,
                     Property.ConversionException

Sets the value of the field.

Specified by:

setValue in interface Property

Parameters:

newValue - the New value of the field.

Throws:

Property.ReadOnlyException

Property.ConversionException

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

Gets the validators of the field.

Specified by:

getValidators in interface Validatable

Returns:

the Unmodifiable collection that holds all validators for the field.

removeValidator

public void removeValidator(Validator validator)

Removes the 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

Checks the validity of the validatable

Specified by:

validate in interface Validatable

Throws:

Validator.InvalidValueException - if the value is not valid

See Also:

Validatable.validate()

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

Throws:

UnsupportedOperationException - if the setInvalidAllowed is not supported.

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

Emits the 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

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

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

Asks the terminal to place the cursor to this field.

Specified by:

focus in interface Component.Focusable

constructField

public static AbstractField constructField(Class propertyType)

Creates abstract field by the type of the property.

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

Parameters:

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

getTabIndex

public int getTabIndex()

Gets the tab index of this field. The tab index property is used to specify the natural tab ordering of fields.

Specified by:

getTabIndex in interface Component.Focusable

Returns:

the Tab index of this field. Negative value means unspecified.

setTabIndex

public void setTabIndex(int tabIndex)

Gets the tab index of this field. The tab index property is used to specify the natural tab ordering of fields.

Specified by:

setTabIndex in interface Component.Focusable

Parameters:

tabIndex - the tab order of this component. Negative value means unspecified.

setInternalValue

protected void setInternalValue(Object newValue)

Sets the internal field value. This is purely used by AbstractField to change the internal Field value. It does not trigger any events. It can be overriden by the inheriting classes to update all dependent variables.

Parameters:

newValue - the new value to be set.

getFocusableId

public long getFocusableId()

Gets the unique ID of focusable

Specified by:

getFocusableId in interface Component.Focusable

Returns:

the Unique id of focusable.

See Also:

Component.Focusable.getFocusableId()

attach

public void attach()

Notifies the component that it is connected to an application.

Specified by:

attach in interface Component

Overrides:

attach in class AbstractComponent

See Also:

Component.attach()

isRequired

public boolean isRequired()

Is this field required. Required fields must filled by the user.

Specified by:

isRequired in interface Field

Returns:

true if the field is required .otherwise false.

setRequired

public void setRequired(boolean required)

Sets the field required. Required fields must filled by the user.

Specified by:

setRequired in interface Field

Parameters:

required - Is the field required.

finalize

public void finalize()
              throws Throwable

Free used resources.

Overrides:

finalize in class Object

Throws:

Throwable

See Also:

Object.finalize()