adapforms.runtime
Interface ElementState

All Known Implementing Classes:
StateTreeNode

public interface ElementState

Holds the current state of a form element within an active form instance. This interface provides the primary means of inspecting and manipulating the state of the form instance.

To obtain an instance corresponding to a desired form element, see FormInstance.elementState(FormPath)

Depending on the type of element, some of the methods provided will not be applicable. In particular, many methods only makes sense in the event that the element is capable of holding a value.

If you try to invoke a method that does not apply to the specific type of element, a TypeException will be thrown.

Author:
Henrik Gammelmark, geemark@cs.au.dk

Method Summary
 FormPath addRepeatEntry()
          Create a new entry for a RepeatElement.
 FormPath getPath()
          Get the form path to which this state belongs.
 java.util.List<java.lang.Integer> getRepeatEntries()
          Return the ID's of all repeat entries that exist for the element.
<T> T
getValue()
          Retrieve the value entered into the form element.
<T> T
getValueAsBean()
          Given the path to a BeanElement in the form, retrieve its values as a newly instantiated value bean.
<T> T
getValueAsBean(T bean)
          Same as getValueAsBean(), but instead of instantiating a new bean, the instance given as a parameter will be updated by calling the relevant set-methods.
 boolean hasNonEmptyValue()
          Determine if the element currently has a non-empty value.
 boolean isReadOnly()
          Determine if the user is allowed to change the value of the form element.
 boolean isRelevant(boolean honorInheritance)
          Check if an element is currently relevant, optionally taking inheritance into account.
 boolean isRequired()
          Determine if the user must enter a value into the element.
 void removeRepeatEntry(int repeatID)
          Remove the tree under a repeat entry, denoted by the given path.
 void setReadOnly(boolean readonly)
          Set the "read-only" flag of a form element.
 void setRelevant(boolean relevant)
          Set the "relevant" flag of the element.
 void setRequired(boolean required)
          Set the "required" flag of the element.
 void setValidationProblem(ValidationProblem problem)
          Set a validation problem message for the element.
 void setValue(java.lang.Object value)
          Change the value of the element.
 void setValueFromBean(java.lang.Object bean)
          Change the value of a form bean element (BeanElement).
 

Method Detail

isReadOnly

boolean isReadOnly()
                   throws TypeException
Determine if the user is allowed to change the value of the form element.

Throws:
TypeException

setReadOnly

void setReadOnly(boolean readonly)
                 throws TypeException,
                        FormStateException
Set the "read-only" flag of a form element. That is, decide if the user is allowed to change the value of the element.

Throws:
FormStateException - if you are not allowed to change the ReadOnly flag
TypeException

isRelevant

boolean isRelevant(boolean honorInheritance)
Check if an element is currently relevant, optionally taking inheritance into account.

Negative relevance is inherited, meaning that any element container that is not relevant, dictates that none of the contained elements are relevant either.

Parameters:
honorInheritance - Whether relevance should be honored (true), or if the specific relevance is requested (false)

setRelevant

void setRelevant(boolean relevant)
Set the "relevant" flag of the element. The state is changed on the single form element only, but due to relevance inheritance, child elements may also be affected.

See Also:
isRelevant(boolean)

getPath

FormPath getPath()
Get the form path to which this state belongs.


isRequired

boolean isRequired()
                   throws TypeException
Determine if the user must enter a value into the element.

Throws:
TypeException

setRequired

void setRequired(boolean required)
                 throws TypeException
Set the "required" flag of the element. That is, decide if the user must enter a value into the element.

Throws:
TypeException

setValidationProblem

void setValidationProblem(ValidationProblem problem)
Set a validation problem message for the element. Use null to clear the problem.

Note this this validation mechanism is an addition to the built-in validation, and thus does not influence the automatic validation. This is merely a way to perform complex validation, possibly based on external factors.

Parameters:
problem - Validation error to set (or null to remove)

getValue

<T> T getValue()
           throws TypeException
Retrieve the value entered into the form element.

The actual type of the value returned, depends on the type of the form element. If the element has no value, null is returned.

Type Parameters:
T - Expected value type
Throws:
TypeException
See Also:
hasNonEmptyValue()

setValue

void setValue(java.lang.Object value)
              throws TypeException
Change the value of the element.

The value must be of the type expected by the form element. The framework will, however, perform conversion if possible.

Throws:
TypeException - if the given value cannot be type-converted automatically.

setValueFromBean

void setValueFromBean(java.lang.Object bean)
                      throws TypeException,
                             InvalidPathException
Change the value of a form bean element (BeanElement). Each property of the bean is inserted into the form at the path of the bean element.

Notice that this will only work, if the path specified is actually a bean element, and that the given bean is of the same type (or subtype) that was used when creating the element.

Throws:
TypeException - if the element is not a bean element, or the given bean is of the wrong type.
InvalidPathException

getValueAsBean

<T> T getValueAsBean()
                 throws InvalidPathException,
                        TypeException,
                        FormStateException
Given the path to a BeanElement in the form, retrieve its values as a newly instantiated value bean. A new instance of the bean is created, and for each child element of the bean element that currently has a value, the corresponding set-method will be invoked with the value from the form.

Type Parameters:
T - Bean type
Throws:
TypeException - if the given path is not a bean type, or the generic type T is not type-compatible with the actual bean type
InvalidPathException
FormStateException

getValueAsBean

<T> T getValueAsBean(T bean)
                 throws InvalidPathException,
                        TypeException,
                        FormStateException
Same as getValueAsBean(), but instead of instantiating a new bean, the instance given as a parameter will be updated by calling the relevant set-methods.

Throws:
InvalidPathException
TypeException
FormStateException

addRepeatEntry

FormPath addRepeatEntry()
                        throws FormStateException,
                               TypeException,
                               InvalidPathException
Create a new entry for a RepeatElement. That is, given a path to a repeat element, create a new entry of the given sub-form.

Returns:
The path to the newly created entry
Throws:
TypeException - If the given path does not point to a repeat element
FormStateException
InvalidPathException

removeRepeatEntry

void removeRepeatEntry(int repeatID)
                       throws FormStateException,
                              TypeException,
                              InvalidPathException
Remove the tree under a repeat entry, denoted by the given path.

Parameters:
repeatID - The ID of the repeat entry
Throws:
TypeException - If the given path does not point to a repeat element entry
FormStateException
InvalidPathException

getRepeatEntries

java.util.List<java.lang.Integer> getRepeatEntries()
                                                   throws InvalidPathException,
                                                          TypeException
Return the ID's of all repeat entries that exist for the element.

The full path to the repeat entries will be the path of this element appended with "[entry-id]".

Only applicable for repeat elements.

Throws:
InvalidPathException
TypeException

hasNonEmptyValue

boolean hasNonEmptyValue()
Determine if the element currently has a non-empty value. The definition if an empty value depends on the element type in question, but is usually represented with either the empty string or null.

If this element is not capable of holding any value, false is always returned.

See Also:
getValue()