com.whitestein.lsps.vaadin.forms

Class Form

java.lang.Object

com.whitestein.lsps.vaadin.forms.Form

All Implemented Interfaces:

LspsScreen, Serializable

public class Form
extends Object
implements LspsScreen

A form which owns all components created by the Forms form. Maintains a 1-to-1 relationship between LSPS Record instances and FormComponent instances; there are no scopes and no potential 1-to-many relationship like in the old UI.

To construct the form, you will need to:

• Create the form instance;
• Call callInForm(Form, Runnable); in the Runnable call createComponent(Variant.RecordVariant) on the root FormComponent definition, to initialize the component graph
• Call setRootComponent(RecordHolder) to set the root component

Author:

mvy

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
Form(FormComponentFactory componentFactory, LspsContextHolder context) Creates the new form.

Method Summary

Modifier and Type	Method and Description
void	addBrowserWindowResizeListener(Variant.ScopedClosureVariant listener) Adds a resize listener to the browser window.
void	addComponentToRefresh(UIComponent component) Schedules a component to be refreshed during next call to LspsScreen.triggerEventProcessing(com.whitestein.lsps.vaadin.ui.events.UIEvent).
void	addUploadedBinaryData(long binaryDataId) Adds a temporary file to the list of files to be deleted once the screen is closed.
<R> R	call(Callable<R> callable) Call any listener body in this, in order for the methods called from the listener to have access to the form instance (via get()).
<R> R	callDontCatch(Callable<R> callable) Call any listener body in this, in order for the methods called from the listener to have access to the form instance (via get()).
static void	callInForm(Form form, Runnable runnable) Call any listener body in this, in order for the methods called from the listener to have access to the form instance (via get()).
void	cleanup() Called after the screen content is removed from the Vaadin UI or submitted.
void	clearErrorMessages(RecordHolder component) Clears error messages on the component and all it's descendants.
void	createComponent(Variant.RecordVariant def) INTERNAL, DO NOT CALL.
UIComponent	createUIComponent(UIComponent parent, RecordHolder componentDefinition, UIComponentScope scope) Creates a Vaadin component based on the provided component definition.
void	fireApplicationEvent(UIApplicationEvent appEvent) Schedules given application event to be fired on all registered components that have an application event listener.
void	fireBrowserWindowResizeEvent(Dimension dimension) A browser window resize has been detected.
int	gc() Runs a full GC, both over the Form and over the model.
static Form	get() Returns the current form the expression is executing in.
Set<UIComponent>	getAllComponents() Returns all components contained in this screen.
FormComponent	getComponent(com.vaadin.ui.Component component) Returns the FormComponent which produced given Vaadin component.
FormComponent	getComponent(RecordHolder rh) Gets a FormComponent corresponding to the given form component definition.
FormComponentFactory	getComponentFactory() Gets factory for form components.
Set<UIComponent>	getComponentsForDefinition(RecordHolder componentDefinition, UIComponent scopeComponent) Returns all component instances for the given component definition, visible from the scope of the given component.
LspsContextHolder	getContext() Gets the context holder.
LspsContextHolder	getContextHolder() Returns the the LSPS context which produced this screen.
Variant.RecordVariant	getDef(FormComponent component) Returns the LSPS Record instance, mapped one-to-one to given Vaadin Form Component instance.
Locale	getLocale() Gets the locale set to the root component widget.
static Form	getNull() Gets the current form from bound to the current thread the expression is executed in or null if there is no form instance bound to the current thread.
FormComponent	getRootComponent() Gets the root component of thsi form.
UIComponentScope	getRootScope() Returns the root scope.
ContextWrapper	getScreenContext() Deprecated.
UIComponent	getTopmostComponent() Returns the topmost component.
Set<ValueHolder>	getValuesToRetain() Returns the set of value holders that should not be garbage collected even if they are not referenced from any variables in the model.
boolean	isFormComponent(com.vaadin.ui.Component component) Returns true if the component is a widget of a FormComponent contained in this form.
boolean	isInvalid(UIComponent component) Checks whether given component is marked as invalid, by calling LspsScreen.markComponentAsInvalid(com.whitestein.lsps.vaadin.ui.components.UIComponent).
static void	listener(FormComponent component, Runnable runnable) Call any listener body in this, in order for the methods called from the listener to have access to the form instance (via get()).
void	markComponentAsInvalid(UIComponent component) Marks the component as invalid.
void	markComponentAsValid(UIComponent component) Marks the component as valid again.
void	registerUIComponent(UIComponent component) Register the given UI component and its children in this screen.
void	registerValueToRetain(Handle handle) Registers the value for the given handle as one to be kept during garbage collection.
com.vaadin.ui.Component	render() Called when the screen content should be added to the Vaadin UI.
void	resume() Called after the screen component has been added to Vaadin UI.
RecordHolder	save(ExecutionContext ctx) Saves the current Todo/Document.
void	setRootComponent(RecordHolder rootDef) Sets the root component of this form.
void	showConstraintViolations(ListHolder constraintViolations, RecordHolder root) Displays constraint violations in the forms.
boolean	triggerEventProcessing(UIEvent triggeringEvent) Process all events in the queue - invokes standard LSPS ui lifecycle
void	unregisterUIComponent(UIComponent component) Unregister the given UI component and its children from this screen.
void	unregisterValueToRetain(Handle handle) Unregisters the value for the given handle as one to be kept during garbage collection.
void	updateContextFor(UIComponentData componentData) Updates context dependent variables for the given componentData.

Methods inherited from class java.lang.Object

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

Constructor Detail

Form

public Form(FormComponentFactory componentFactory,
            LspsContextHolder context)

Creates the new form.

Parameters:

componentFactory - the factory which produces actual instances of UI components and renderers, not null.

context - LSPS context, not null.

Method Detail

getComponentFactory

public FormComponentFactory getComponentFactory()

Gets factory for form components.

Returns:

a form component factory

getComponent

public FormComponent getComponent(RecordHolder rh)

Gets a FormComponent corresponding to the given form component definition.

Parameters:

rh - the form component definition

Returns:

a form component

getComponent

public FormComponent getComponent(com.vaadin.ui.Component component)

Returns the FormComponent which produced given Vaadin component.

Parameters:

component - the component, not null

Returns:

the form component, never null.

Throws:

IllegalArgumentException - if given Vaadin component is not registered in this form.

isFormComponent

public boolean isFormComponent(com.vaadin.ui.Component component)

Returns true if the component is a widget of a FormComponent contained in this form. In other words it checks whether the component was returned by one of the forms components when calling FormComponent.getWidget().

If this method returns false then calling getComponent(Component) with the same component argument will throw an exception.

Parameters:

component - the component to check

Returns:

true if the component is a widget of a FormComponent contianed in this form

createComponent

public void createComponent(Variant.RecordVariant def)

INTERNAL, DO NOT CALL. Internally called from the "createNative()" call which is placed in every forms::FormComponent constructor. Therefore, if you have obtained a forms::FormComponent Record instance, the component is already instantiated - use getComponent(RecordHolder) to retrieve the FormComponent counterpart.

Parameters:

def - the definition, not null.

get

public static Form get()

Returns the current form the expression is executing in.

Returns:

the form, never null.

Throws:

IllegalStateException - if this is not called from UI.

getNull

public static Form getNull()

Gets the current form from bound to the current thread the expression is executed in or null if there is no form instance bound to the current thread.

Returns:

a form bound to the current thread or null

See Also:

get()

getContext

public LspsContextHolder getContext()

Gets the context holder.

Returns:

the context holder which holds contextual information for this form.

setRootComponent

public void setRootComponent(RecordHolder rootDef)

Sets the root component of this form.

Parameters:

rootDef -

render

public com.vaadin.ui.Component render()

Description copied from interface: LspsScreen

Called when the screen content should be added to the Vaadin UI. Typically will be called shortly after the screen is created.

This method only creates the Vaadin UI component graph and returns it - it should not attempt to show the component in some Vaadin UI.

The LspsScreen.resume() method is called after this method.

This method must be called exactly once.

Specified by:

render in interface LspsScreen

Returns:

the root component to show, never null. Returns Vaadin component instead of UIComponent because custom screens may use components other than UIComponent.

getRootComponent

public FormComponent getRootComponent()

Gets the root component of thsi form.

Returns:

the root component

resume

public void resume()

Description copied from interface: LspsScreen

Called after the screen component has been added to Vaadin UI. Called when the screen content is shown:

• either it is shown for the first time: in such case the LspsScreen.render() method has already been called
• or it is re-shown, e.g. when the user navigates back to a previously-shown screen from which he navigated away without submitting

Specified by:

resume in interface LspsScreen

cleanup

public void cleanup()

Description copied from interface: LspsScreen

Called after the screen content is removed from the Vaadin UI or submitted.

After this method is called, no other methods may be called.

Specified by:

cleanup in interface LspsScreen

registerValueToRetain

public void registerValueToRetain(Handle handle)

Description copied from interface: LspsScreen

Registers the value for the given handle as one to be kept during garbage collection. See LspsScreen.getValuesToRetain().

Specified by:

registerValueToRetain in interface LspsScreen

Parameters:

handle - a handle to the model object, not null.

unregisterValueToRetain

public void unregisterValueToRetain(Handle handle)

Description copied from interface: LspsScreen

Unregisters the value for the given handle as one to be kept during garbage collection. See LspsScreen.getValuesToRetain().

Specified by:

unregisterValueToRetain in interface LspsScreen

Parameters:

handle - a handle to the model object, not null.

gc

public int gc()

Runs a full GC, both over the Form and over the model.

Returns:

number of Vaadin components which were GC-ed.

getValuesToRetain

public Set<ValueHolder> getValuesToRetain()

Description copied from interface: LspsScreen

Returns the set of value holders that should not be garbage collected even if they are not referenced from any variables in the model. Typically this should contain the UI definition (as defined in the model, either as a task or document attribute).

Specified by:

getValuesToRetain in interface LspsScreen

Returns:

values to retain during garbage collection

getAllComponents

public Set<UIComponent> getAllComponents()

Description copied from interface: LspsScreen

Returns all components contained in this screen. A shortcut for getRootScope().getRegisteredComponents()

Specified by:

getAllComponents in interface LspsScreen

Returns:

all components, never null.

getRootScope

public UIComponentScope getRootScope()

Description copied from interface: LspsScreen

Returns the root scope.

Specified by:

getRootScope in interface LspsScreen

Returns:

the root scope, never null.

fireBrowserWindowResizeEvent

public void fireBrowserWindowResizeEvent(Dimension dimension)

Description copied from interface: LspsScreen

A browser window resize has been detected. Application event is fired, with name of internal_windowresize, having payload of type hu::Dimension which holds new window dimension. The event originator component is set to ROOT.

Warning: browsers on Android return value in DPs instead of pixels. From Android documentation: Density-independent Pixels - an abstract unit that is based on the physical density of the screen. These units are relative to a 160 dpi screen, so one dp is one pixel on a 160 dpi screen. The ratio of dp-to-pixel will change with the screen density, but not necessarily in direct proportion. Example: a screen width of 720 on a 320 DPI screen will be reported as 360 DPs.

Therefore, to render special page for small devices, compare screen width to the value of 400. If equal or smaller, provide small screen version.

Specified by:

fireBrowserWindowResizeEvent in interface LspsScreen

Parameters:

dimension - the new dimension, in pixels (on desktop OS) or DPs (on Android phones).

getScreenContext

@Deprecated
public ContextWrapper getScreenContext()

Deprecated.

Description copied from interface: LspsScreen

Returns the "0:1" execution context for the screen. The screen runs in this context until submitted or persisted - then it is merged to the main "0" execution context.

Specified by:

getScreenContext in interface LspsScreen

Returns:

the context wrapper, never null.

getContextHolder

public LspsContextHolder getContextHolder()

Description copied from interface: LspsScreen

Returns the the LSPS context which produced this screen.

Specified by:

getContextHolder in interface LspsScreen

Returns:

context holder, never null.

createUIComponent

public UIComponent createUIComponent(UIComponent parent,
                                     RecordHolder componentDefinition,
                                     UIComponentScope scope)

Description copied from interface: LspsScreen

Creates a Vaadin component based on the provided component definition. Shortcut to UIComponentFactory.createComponent(LspsScreen, com.whitestein.lsps.vaadin.ui.components.UIComponent, com.whitestein.lsps.lang.exec.RecordHolder, com.whitestein.lsps.vaadin.ui.UIComponentScope) .

Specified by:

createUIComponent in interface LspsScreen

Parameters:

parent - parent of the component in the LSPS component hierarchy

componentDefinition - definition of the component to create

scope - component scope; if null, same scope as parent will be used

Returns:

created component

triggerEventProcessing

public boolean triggerEventProcessing(UIEvent triggeringEvent)

Description copied from interface: LspsScreen

Process all events in the queue - invokes standard LSPS ui lifecycle

Specified by:

triggerEventProcessing in interface LspsScreen

Parameters:

triggeringEvent - the event that triggered this round of processing; can be null if there is no such event.

Returns:

false if processing could not be started, either because the event processing is already in progress, or any of the components to process is marked as invalid (via LspsScreen.markComponentAsInvalid(com.whitestein.lsps.vaadin.ui.components.UIComponent).

markComponentAsInvalid

public void markComponentAsInvalid(UIComponent component)

Description copied from interface: LspsScreen

Marks the component as invalid. This will cause LspsScreen.triggerEventProcessing(com.whitestein.lsps.vaadin.ui.events.UIEvent) to return false for events which processes given component.

Note that this will not cause the component to show an error icon.

Specified by:

markComponentAsInvalid in interface LspsScreen

Parameters:

component - the component, not null.

markComponentAsValid

public void markComponentAsValid(UIComponent component)

Description copied from interface: LspsScreen

Marks the component as valid again.

Note that this will not cause the component to hide an error icon.

Specified by:

markComponentAsValid in interface LspsScreen

Parameters:

component - the component, not null.

isInvalid

public boolean isInvalid(UIComponent component)

Description copied from interface: LspsScreen

Checks whether given component is marked as invalid, by calling LspsScreen.markComponentAsInvalid(com.whitestein.lsps.vaadin.ui.components.UIComponent).

Specified by:

isInvalid in interface LspsScreen

Parameters:

component - the component, not null.

Returns:

true if the component is marked invalid, false if it has not yet been marked as invalid or has been marked as valid, by calling LspsScreen.markComponentAsValid(com.whitestein.lsps.vaadin.ui.components.UIComponent).

registerUIComponent

public void registerUIComponent(UIComponent component)

Description copied from interface: LspsScreen

Register the given UI component and its children in this screen. Registration of components is needed, so that the application is able to use references between lsps objects and vaadin components for various reasons (such as refresh functionality).

Specified by:

registerUIComponent in interface LspsScreen

Parameters:

component - not null. The component parent must already be registered.

unregisterUIComponent

public void unregisterUIComponent(UIComponent component)

Description copied from interface: LspsScreen

Unregister the given UI component and its children from this screen.

Specified by:

unregisterUIComponent in interface LspsScreen

Parameters:

component - not null. The component parent must already be registered.

addComponentToRefresh

public void addComponentToRefresh(UIComponent component)

Description copied from interface: LspsScreen

Schedules a component to be refreshed during next call to LspsScreen.triggerEventProcessing(com.whitestein.lsps.vaadin.ui.events.UIEvent).

Specified by:

addComponentToRefresh in interface LspsScreen

Parameters:

component - the component, not null. The component must be initialized.

updateContextFor

public void updateContextFor(UIComponentData componentData)

Description copied from interface: LspsScreen

Updates context dependent variables for the given componentData. See UIComponentScope.updateContext().

Specified by:

updateContextFor in interface LspsScreen

Parameters:

componentData - a component data, may not be null

getTopmostComponent

public UIComponent getTopmostComponent()

Description copied from interface: LspsScreen

Returns the topmost component.

Specified by:

getTopmostComponent in interface LspsScreen

Returns:

the topmost component, never null.

fireApplicationEvent

public void fireApplicationEvent(UIApplicationEvent appEvent)

Description copied from interface: LspsScreen

Schedules given application event to be fired on all registered components that have an application event listener.

The event is not fired until LspsScreen.triggerEventProcessing(com.whitestein.lsps.vaadin.ui.events.UIEvent) is called.

Specified by:

fireApplicationEvent in interface LspsScreen

Parameters:

appEvent - the event, not null.

getComponentsForDefinition

public Set<UIComponent> getComponentsForDefinition(RecordHolder componentDefinition,
                                                   UIComponent scopeComponent)

Description copied from interface: LspsScreen

Returns all component instances for the given component definition, visible from the scope of the given component.

Specified by:

getComponentsForDefinition in interface LspsScreen

Parameters:

componentDefinition - the definition, not null.

scopeComponent - find the components in this scope only. Not null.

Returns:

instances of UIComponent associated with the given component definition. Never null, never contains nulls.

addUploadedBinaryData

public void addUploadedBinaryData(long binaryDataId)

Description copied from interface: LspsScreen

Adds a temporary file to the list of files to be deleted once the screen is closed.

Specified by:

addUploadedBinaryData in interface LspsScreen

getDef

public Variant.RecordVariant getDef(FormComponent component)

Returns the LSPS Record instance, mapped one-to-one to given Vaadin Form Component instance.

Parameters:

component - the form component, not null. Fails if given form component is not registered in this form instance.

Returns:

the LSPS "Definition" Record, not null.

callInForm

public static void callInForm(Form form,
                              Runnable runnable)

Call any listener body in this, in order for the methods called from the listener to have access to the form instance (via get()).

Parameters:

form - calling some listener in this form, not null.

runnable - the listener body, not null.

call

public <R> R call(Callable<R> callable)

Call any listener body in this, in order for the methods called from the listener to have access to the form instance (via get()).

Type Parameters:

R - return type value of the callable

Parameters:

callable - the listener body, not null.

Returns:

any result produced by the callable.

callDontCatch

public <R> R callDontCatch(Callable<R> callable)
                    throws Exception

Call any listener body in this, in order for the methods called from the listener to have access to the form instance (via get()).

Type Parameters:

R - return type value of the callable

Parameters:

callable - the listener body, not null.

Returns:

any result produced by the callable.

Throws:

Exception - an exception thrown by the callable

listener

public static void listener(FormComponent component,
                            Runnable runnable)

Call any listener body in this, in order for the methods called from the listener to have access to the form instance (via get()).

Parameters:

component - calling some listener of this component.

runnable - the listener body, not null.

getLocale

public Locale getLocale()

Gets the locale set to the root component widget.

Returns:

the form locale

addBrowserWindowResizeListener

public void addBrowserWindowResizeListener(Variant.ScopedClosureVariant listener)

Adds a resize listener to the browser window.

Parameters:

listener - the listener to add

save

public RecordHolder save(ExecutionContext ctx)
                  throws ErrorException

Saves the current Todo/Document. If the save action fails for any reason the current transaction is marked as rollback only.

Parameters:

ctx -

Returns:

the saved Todo/Document

Throws:

ErrorException - if the save action fails.

showConstraintViolations

public void showConstraintViolations(ListHolder constraintViolations,
                                     RecordHolder root)

Displays constraint violations in the forms. This method tries to map the violations to the components bound to the record properties which are source of the constraint violations.

Parameters:

constraintViolations -

root - the component defining the root of the sub-component-tree where to start.

clearErrorMessages

public void clearErrorMessages(RecordHolder component)

Clears error messages on the component and all it's descendants.

Parameters:

component -