com.whitestein.lsps.vaadin.forms

Class FormComponent

java.lang.Object

com.whitestein.lsps.vaadin.forms.FormComponent

All Implemented Interfaces:

com.vaadin.event.ConnectorEventListener, com.vaadin.server.ClientConnector.AttachListener, Serializable, EventListener

Direct Known Subclasses:

ComponentWithValue, WAbstractChart, WAbstractSplitPanel, WAbstractTable, WBrowserFrame, WButton, WCalendar, WComponentGroup, WDownload, WGrid, WGridStackDashboard, WImage, WLink, WMapDisplay, WSingleComponentContainer, WUpload

public abstract class FormComponent
extends Object
implements Serializable, com.vaadin.server.ClientConnector.AttachListener

A connector between Vaadin widget and LSPS UI definition.

Differences to the old UI

• There are no scopes - the component LSPS record instances are mapped 1-to-1 to FormComponent. As a consequence, there is no Repeater component anymore - just add necessary components dynamically. Also, there are no table iterators.
• There is no listener lifecycle - just call static methods of the Forms class anytime you need, to perform navigation, submit etc.
• There is no ViewModel machinery - this has been replaced by shared record proxies
• FormComponent connectors do not extend Vaadin components themselves - they instead provide proper Vaadin component instances via getWidget(). This allows for parallel inheritance hierarchy.

Calling back and forth

To relay method calls from the LSPS UI to this connector, just call the call("methodName", [args]) method in the expression language - the call(ExecutionContext, String, Object[]) will be called. Please red the call(ExecutionContext, String, Object[]) javadoc for further information.

To call back the LSPS UI:

• Obtain the record instance, by calling rv = form.getDef(this)
• To call a closure stored in a field (say, for firing an event), just call rv.closure().noScope().call(params)
• To call a method, just call rv.call(executionContext.getNamespace(), "method", "arg1", new Decimal(2));

Calling EJBs

Just register your bean in the ComponentServiceBase, then insert this field into your component:

@EJB private YourBean bean;

The EJBs are injected right after the constructor finishes.

Author:

mvy

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected Form	form Every component maintains a link to its owner form.
static String	INTERNAL_STATE_RECORD_PROPERTY Property used to store internal state (when saving todo or form state).

Fields inherited from interface com.vaadin.server.ClientConnector.AttachListener

attachMethod

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FormComponent()

Method Summary

Modifier and Type	Method and Description
void	addDataErrorMessage(String errorMessage) Adds data validation error message.
void	addStyleName(String style)
void	attach(com.vaadin.server.ClientConnector.AttachEvent event)
Object	call(ExecutionContext ctx, String method, Object[] args) Calls a method on the underlying Java UI component.
void	clearDataErrorMessages() Removes all data error messages.
protected RecordHolder	createEvent(String type)
protected abstract com.vaadin.ui.AbstractComponent	createWidget() Called once, to create the actual Vaadin component.
boolean	equals(Object obj)
String	getCaption()
EnumerationImpl	getComponentAlignment() Gets the component alignment
ClosureHolder	getContextClickHandler() Gets the context click handler.
String	getCustomErrorMessage() Gets the component error message.
ListHolder	getDataErrorMessages()
String	getDescription()
Decimal	getExpandRatio() Gets the expand ratio of this component.
IHasChildren	getHasChildrenAdapter() Provides an adapter of this component which allows easily invoke methods on the forms::HasChildren interface.
String	getHeight() Gets the height of this component
RecordHolder	getIcon() Gets the icon of this component.
String	getModelingId() Gets the modeling ID of this component.
Namespace	getNamespace() Gets the namespace this form component should use when it needs to create LSPS objects of complex types or call record methods.
String	getStyleName()
Decimal	getTabIndex() Gets the tabulator index of this component.
com.vaadin.ui.AbstractComponent	getWidget() Gets the Vaadin representation of this component.
String	getWidth() Gets the width of this component.
int	hashCode()
boolean	isEnabled()
boolean	isReadOnly()
boolean	isVisible()
protected String	localize(String message) Utility method which simply calls LspsLocalizer to localize given string.
void	markAsDirty()
void	preventGC(Set<ValueHolder> set) Override for all components which are actively using some record holders, not directly linked to the model.
void	removeStyleName(String style)
protected void	restoreInternalState(Map<String,Object> state) Restores the UI state of this component which was previously written by writeInternalState(Map).
void	restoreState() Restores the UI state of this component from the state stored in the definition record.
void	saveState() Saves the UI state of this component to the record definition.
void	setCaption(String caption)
void	setComponentAlignment(EnumerationImpl align) Sets the component alignment.
void	setContextClickHandler(ClosureHolder clickHandler) Sets the context click handler.
void	setContextMenuItems(ListHolder itemsHolder) Sets the context menu items.
void	setCustomErrorMessage(String errorMessage) Sets custom component error message.
void	setDescription(String description)
void	setEnabled(boolean enabled)
void	setExpandRatio(Decimal ratio) Sets the expand ratio of this component.
void	setHeight(String height)
void	setIcon(RecordHolder resource) Sets the icon of this component.
void	setReadOnly(boolean readOnly)
void	setStyleName(String style)
void	setTabIndex(Decimal tabIndex) Sets the tabulator index of this component
void	setVisible(boolean visible)
void	setWidth(String width)
String	toString()
protected void	writeInternalState(Map<String,Object> state) Writes the UI state of this component to the provided map.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

INTERNAL_STATE_RECORD_PROPERTY

public static final String INTERNAL_STATE_RECORD_PROPERTY

Property used to store internal state (when saving todo or form state).

See Also:

Constant Field Values

form

protected final Form form

Every component maintains a link to its owner form. Not null.

Constructor Detail

FormComponent

protected FormComponent()

Method Detail

createWidget

protected abstract com.vaadin.ui.AbstractComponent createWidget()

Called once, to create the actual Vaadin component.

Returns:

the actual Vaadin component, may be null if the component has no UI counterpart.

getWidget

public com.vaadin.ui.AbstractComponent getWidget()

Gets the Vaadin representation of this component.

Returns:

the Vaadin representation of this form component.

call

public Object call(ExecutionContext ctx,
                   String method,
                   Object[] args)

Calls a method on the underlying Java UI component. Default implementation will first try to find given method reflectively on the FormComponent connector; if there is no such method, the underlying Vaadin widget is searched. If there is no such method, this method fails with an exception.

Overriding this method

To add new methods callable via this function, just add a simple java method, either to this object, or to the Vaadin component returned via getWidget(). You can override this mechanism by overriding this method, but this is not recommended, unless you somehow wish to support dynamic number of methods. In such case, do not forget to call the super method (this method).

Parameters:

ctx -

method - the method name, not null.

args - optional list of parameters, not null.

Returns:

optional method result, may be null.

Throws:

RuntimeException - if no such method exists.

getNamespace

public Namespace getNamespace()

Gets the namespace this form component should use when it needs to create LSPS objects of complex types or call record methods. The namespace does not have to be used when the component needs to create objects of simple types, such as Boolean, String, Date, Decimal. In the other hand when creating RecordHolder, CollectionHolder and any other complex type, the namespace must be used so that the created object of the complex type is also registered in the model instance.

Usage example

 getNamespace().createRecord("uicommon::FileResource");
 

Returns:

a namespace for the component

getWidth

public String getWidth()

Gets the width of this component.

Returns:

the width

getModelingId

public String getModelingId()

Gets the modeling ID of this component.

Returns:

the modeling ID

toString

public String toString()

Overrides:

toString in class Object

hashCode

public final int hashCode()

Overrides:

hashCode in class Object

equals

public final boolean equals(Object obj)

Overrides:

equals in class Object

localize

protected String localize(String message)

Utility method which simply calls LspsLocalizer to localize given string.

Parameters:

message - the message, may be null

Returns:

localized message or null if null was passed.

setCustomErrorMessage

public void setCustomErrorMessage(String errorMessage)

Sets custom component error message. Custom component error message is shown first, above data constraint error messages and validation error messages.

Parameters:

errorMessage - the error message to set

getCustomErrorMessage

public String getCustomErrorMessage()

Gets the component error message. Return value contains only custom component error message set by setErrorMessage method, it does NOT contain data constraint error messages nor validation error messages.

Returns:

the component error message

addDataErrorMessage

public void addDataErrorMessage(String errorMessage)

Adds data validation error message.

Parameters:

errorMessage -

clearDataErrorMessages

public void clearDataErrorMessages()

Removes all data error messages.

getDataErrorMessages

public ListHolder getDataErrorMessages()

Returns:

all data error messages. Returned value does NOT contain custom error message nor errors returned from validators.

createEvent

protected RecordHolder createEvent(String type)

getTabIndex

public Decimal getTabIndex()

Gets the tabulator index of this component.

Returns:

the tabulator index

setTabIndex

public void setTabIndex(Decimal tabIndex)

Sets the tabulator index of this component

Parameters:

tabIndex - the tabulator index

getHeight

public String getHeight()

Gets the height of this component

Returns:

the height

preventGC

public void preventGC(Set<ValueHolder> set)

Override for all components which are actively using some record holders, not directly linked to the model. You will need to return those record holders here, otherwise they will be garbage-collected.

For example, WTabSheet maintains a set of opened tabs. These tab records are not referenced directly from forms::TabSheet and will therefore be garbage-collected. We however need those records to not to be GCed as the user may ask for them simply by calling getTab(Integer).

Please note that the component definition records (e.g. forms::Button) are already GC-protected and they do not need to be added to this set. Also, any child components currently attached to the UI are automatically protected and are not required to be registered in the set.

Parameters:

set - a set of records which are to be GC-prevented, never null. The component should add any records here. Default implementation does nothing.

attach

public void attach(com.vaadin.server.ClientConnector.AttachEvent event)

Specified by:

attach in interface com.vaadin.server.ClientConnector.AttachListener

setExpandRatio

public void setExpandRatio(Decimal ratio)

Sets the expand ratio of this component. The expand ratio is applied only if this component has a parent and the parent supports expand ratio for it's children.

Parameters:

ratio - the expand ratio to set

getExpandRatio

public Decimal getExpandRatio()

Gets the expand ratio of this component.

Returns:

the expand ratio set for this component

setComponentAlignment

public void setComponentAlignment(EnumerationImpl align)

Sets the component alignment. The parent component must implement Layout.AlignmentHandler.

Parameters:

align - the alignment to set

getComponentAlignment

public EnumerationImpl getComponentAlignment()

Gets the component alignment

Returns:

the component alignment

setIcon

public void setIcon(RecordHolder resource)

Sets the icon of this component.

Parameters:

resource - the icon.

getIcon

public RecordHolder getIcon()

Gets the icon of this component.

Returns:

the component icon or null

setContextClickHandler

public void setContextClickHandler(ClosureHolder clickHandler)

Sets the context click handler. The handler is called when a context click occurs.

Parameters:

clickHandler - the context click handler

getContextClickHandler

public ClosureHolder getContextClickHandler()

Gets the context click handler.

Returns:

the context click handler or null if none is installed

setContextMenuItems

public void setContextMenuItems(ListHolder itemsHolder)

Sets the context menu items. The context menu items are displayed in the component's context menu which is shown when a context click occurs.

Parameters:

itemsHolder - a list of context menu items

getHasChildrenAdapter

public IHasChildren getHasChildrenAdapter()

Provides an adapter of this component which allows easily invoke methods on the forms::HasChildren interface. If this component does not implement the interface then and adapter returning no children is returned.

Returns:

adapter of this component which implements the IHasChildren interface, never null.

saveState

public final void saveState()

Saves the UI state of this component to the record definition. It also asks any child components to do the same (recursively).

See Also:

writeInternalState(Map)

restoreState

public final void restoreState()

Restores the UI state of this component from the state stored in the definition record. It asks any child components to do the same (recursively).

See Also:

restoreInternalState(Map)

writeInternalState

protected void writeInternalState(Map<String,Object> state)

Writes the UI state of this component to the provided map. The written state is later used to restore the UI when a saved document or saved Todo is reopened.

Many UI attributes such as size, caption, etc. are not held in the records but are stored exclusively in the Vaadin components. In the records the getter/setter methods of such attributes directly delegate to the underlying component. For the purposes of the Save Document/Todo use case the state of such attributes has to be preserved.

Subclasses should override this method. The overriding method should call super.writeInternalState(state) to store the state form the super class as well. The attributes should be written to the provided state parameter. The type of the values written to the state can only by Java representation of LSPS types. That is java.util.Date, java.lang.String, Decimal, RecordHolder, ListHolder, ... The name of the attributes stored in the map should be unique and should not collide with the names used by any of the superclass. It is the responsibility of the overridden method to ensure that.

Subclasses overriding this method should also override restoreInternalState(Map) and restore the state written by this method.

Parameters:

state - a map to which this method should write the component's UI state.

See Also:

restoreInternalState(Map), saveState()

restoreInternalState

protected void restoreInternalState(Map<String,Object> state)

Restores the UI state of this component which was previously written by writeInternalState(Map). Subclasses should override and call super.restoreInternalState(state);

Parameters:

state - a map of attributes and their values

See Also:

writeInternalState(Map)

isVisible

public boolean isVisible()

setVisible

public void setVisible(boolean visible)

setWidth

public void setWidth(String width)

setHeight

public void setHeight(String height)

getCaption

public String getCaption()

setCaption

public void setCaption(String caption)

isReadOnly

public boolean isReadOnly()

setReadOnly

public void setReadOnly(boolean readOnly)

getStyleName

public String getStyleName()

setStyleName

public void setStyleName(String style)

addStyleName

public void addStyleName(String style)

removeStyleName

public void removeStyleName(String style)

isEnabled

public boolean isEnabled()

setEnabled

public void setEnabled(boolean enabled)

getDescription

public String getDescription()

setDescription

public void setDescription(String description)

markAsDirty

public void markAsDirty()