adapforms.runtime.state
Class StateTreeNode

java.lang.Object
  extended by adapforms.runtime.state.StateTreeNode
All Implemented Interfaces:
ElementState

public class StateTreeNode
extends java.lang.Object
implements ElementState

Holds all data and meta-data about a single node in a StateTree.

The public interface of the class (exposed to the domain application) is defined in ElementState.

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

Constructor Summary
StateTreeNode(StateTree tree, StateTreeNode parent, FormPath path, boolean isMeta)
          Create a new data node
 
Method Summary
 void addHook(FormHook hook)
           
 FormPath addRepeatEntry()
          Create a new entry for a RepeatElement.
 FormPath addRepeatEntry(int repeatID)
           
 boolean canHoldValue()
          Determine if the form element type this element refers to, actually can hold a value.
 StateTreeNode findChild(java.lang.String pathPart, boolean createNonExisting, boolean isMeta)
          Local node lookup
 java.util.Map<java.lang.String,StateTreeNode> getChildren()
          Get the map of the children in the tree.
(package private)  org.w3c.dom.Element getDOMElement()
          Get the DOM Element representation of this node.
 java.util.List<FormHook> getHooks()
          List all hooks registered with the given path.
 FormPath getPath()
          Get the form path to which this state belongs.
 BooleanExpression getReadOnly()
           
 BooleanExpression getRelevant()
           
 java.util.List<java.lang.Integer> getRepeatEntries()
          Return the ID's of all repeat entries that exist for the element.
 BooleanExpression getRequired()
           
 FormElement getStaticElement()
          Get a reference to the static form element this node represents.
 java.util.List<ValidationProblem> getValidationProblems()
          List of current validation problems, if any.
(package private)  java.util.List<ValidationRule> getValidationRules()
          Get the list of complex validation rules.
<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 ElementState.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.
 void initializeValidationRules(java.util.List<ValidationRule> rules)
          Set list of complex validation rules for this element, The list will be deep-cloned.
 boolean isMeta()
          Determine if this is merely a meta node .
 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 removeChild(java.lang.String child)
          Remove a child from the tree
 void removeHook(FormHook hook)
          Remove a given hook from the element, if it exists in the list.
 void removeRepeatEntry(int repeatID)
          Remove the tree under a repeat entry, denoted by the given path.
 void setMeta(boolean meta)
          Toggle the meta-bit on this node.
 void setReadOnly(boolean readonly)
          Set the "read-only" flag of a form element.
 void setReadOnly(BooleanExpression readonly, boolean fromInit)
          Same as setReadOnly(boolean), but allows XPath expressions too.
 void setRelevant(boolean relevant)
          Set the "relevant" flag of the element.
 void setRelevant(BooleanExpression relevant, boolean fromInit)
          Same as setRelevant(boolean), but allows XPath expressions too.
 void setRequired(boolean required)
          Set the "required" flag of the element.
 void setRequired(BooleanExpression required, boolean fromInit)
          Same as setRequired(boolean), but allows XPath expressions too.
 void setSingleValidationProblem(ValidationLevel level, ValidationProblem problem, boolean fromInit)
          Set a single validation problem only (clearing any existing ones).
 void setValidationProblem(ValidationProblem problem)
          Set a validation problem message for the element.
 void setValidationProblems(ValidationLevel level, java.util.List<ValidationProblem> problems, boolean fromInit)
          Set a validation problem, or clear it.
 void setValue(java.lang.Object value)
          Change the value of the element.
 void setValue(java.lang.Object value, boolean fromInit)
          Same as setValue(Object), but allows calls from initialization code that does not trigger hooks etc.
 void setValueFromBean(java.lang.Object bean)
          Change the value of a form bean element (BeanElement).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

StateTreeNode

StateTreeNode(StateTree tree,
              StateTreeNode parent,
              FormPath path,
              boolean isMeta)
Create a new data node

Parameters:
tree - The tree to which the node belongs
path - The path this node represents
isMeta - Is this simply a meta node?
Method Detail

getPath

public FormPath getPath()
Description copied from interface: ElementState
Get the form path to which this state belongs.

Specified by:
getPath in interface ElementState

hasNonEmptyValue

public boolean hasNonEmptyValue()
Description copied from interface: ElementState
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.

Specified by:
hasNonEmptyValue in interface ElementState
See Also:
ElementState.getValue()

getValue

public <T> T getValue()
           throws TypeException
Description copied from interface: ElementState
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.

Specified by:
getValue in interface ElementState
Type Parameters:
T - Expected value type
Throws:
TypeException
See Also:
ElementState.hasNonEmptyValue()

setRelevant

public void setRelevant(boolean relevant)
Description copied from interface: ElementState
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.

Specified by:
setRelevant in interface ElementState
See Also:
ElementState.isRelevant(boolean)

setRelevant

public void setRelevant(BooleanExpression relevant,
                        boolean fromInit)
Same as setRelevant(boolean), but allows XPath expressions too.

Parameters:
fromInit - Called from initialization code?

isReadOnly

public boolean isReadOnly()
                   throws TypeException
Description copied from interface: ElementState
Determine if the user is allowed to change the value of the form element.

Specified by:
isReadOnly in interface ElementState
Throws:
TypeException

getReadOnly

public BooleanExpression getReadOnly()
                              throws TypeException
Throws:
TypeException

setReadOnly

public void setReadOnly(BooleanExpression readonly,
                        boolean fromInit)
                 throws TypeException,
                        FormStateException
Same as setReadOnly(boolean), but allows XPath expressions too.

Parameters:
fromInit - Called from initialization code?
Throws:
TypeException
FormStateException

setReadOnly

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

Specified by:
setReadOnly in interface ElementState
Throws:
FormStateException - if you are not allowed to change the ReadOnly flag
TypeException

isRequired

public boolean isRequired()
                   throws TypeException
Description copied from interface: ElementState
Determine if the user must enter a value into the element.

Specified by:
isRequired in interface ElementState
Throws:
TypeException

getRequired

public BooleanExpression getRequired()
                              throws TypeException
Throws:
TypeException

setRequired

public void setRequired(boolean required)
                 throws TypeException
Description copied from interface: ElementState
Set the "required" flag of the element. That is, decide if the user must enter a value into the element.

Specified by:
setRequired in interface ElementState
Throws:
TypeException

setRequired

public void setRequired(BooleanExpression required,
                        boolean fromInit)
                 throws TypeException
Same as setRequired(boolean), but allows XPath expressions too.

Parameters:
fromInit - Called from initialization code?
Throws:
TypeException

getRelevant

public BooleanExpression getRelevant()

isRelevant

public boolean isRelevant(boolean honorInheritance)
Description copied from interface: ElementState
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.

Specified by:
isRelevant in interface ElementState
Parameters:
honorInheritance - Whether relevance should be honored (true), or if the specific relevance is requested (false)

setValue

public void setValue(java.lang.Object value)
              throws TypeException
Description copied from interface: ElementState
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.

Specified by:
setValue in interface ElementState
Throws:
TypeException - if the given value cannot be type-converted automatically.

setValue

public void setValue(java.lang.Object value,
                     boolean fromInit)
              throws TypeException
Same as setValue(Object), but allows calls from initialization code that does not trigger hooks etc.

Parameters:
fromInit - Called from initialization code?
Throws:
TypeException

addHook

public void addHook(FormHook hook)
See Also:
FormInstance.addHook(String, FormHook)

removeHook

public void removeHook(FormHook hook)
Remove a given hook from the element, if it exists in the list.


getHooks

public java.util.List<FormHook> getHooks()
List all hooks registered with the given path.


getValidationProblems

public java.util.List<ValidationProblem> getValidationProblems()
List of current validation problems, if any. The list is empty if validation is OK.


setValidationProblems

public void setValidationProblems(ValidationLevel level,
                                  java.util.List<ValidationProblem> problems,
                                  boolean fromInit)
Set a validation problem, or clear it. Use null to specify that validation is OK (clear error).


setSingleValidationProblem

public void setSingleValidationProblem(ValidationLevel level,
                                       ValidationProblem problem,
                                       boolean fromInit)
Set a single validation problem only (clearing any existing ones).

Parameters:
level - Validation level
problem - The single problem to set, or null to clear all
fromInit - Called form initialization code?

setValidationProblem

public void setValidationProblem(ValidationProblem problem)
Description copied from interface: ElementState
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.

Specified by:
setValidationProblem in interface ElementState
Parameters:
problem - Validation error to set (or null to remove)

findChild

public StateTreeNode findChild(java.lang.String pathPart,
                               boolean createNonExisting,
                               boolean isMeta)
Local node lookup

Parameters:
pathPart - Local part of path
createNonExisting - Create child if not found?
isMeta - Are we looking to create a meta node?

removeChild

public void removeChild(java.lang.String child)
Remove a child from the tree


getRepeatEntries

public java.util.List<java.lang.Integer> getRepeatEntries()
                                                   throws InvalidPathException,
                                                          TypeException
Description copied from interface: ElementState
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.

Specified by:
getRepeatEntries in interface ElementState
Throws:
InvalidPathException
TypeException

isMeta

public boolean isMeta()
Determine if this is merely a meta node .

That is, it is not corresponding to a concrete form element, but a placeholder for hooks or similar meta-data.


getChildren

public java.util.Map<java.lang.String,StateTreeNode> getChildren()
Get the map of the children in the tree.


canHoldValue

public boolean canHoldValue()
Determine if the form element type this element refers to, actually can hold a value. E.g. groups can not.


setValueFromBean

public void setValueFromBean(java.lang.Object bean)
                      throws TypeException,
                             InvalidPathException
Description copied from interface: ElementState
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.

Specified by:
setValueFromBean in interface ElementState
Throws:
TypeException - if the element is not a bean element, or the given bean is of the wrong type.
InvalidPathException

getValueAsBean

public <T> T getValueAsBean()
                 throws InvalidPathException,
                        TypeException,
                        FormStateException
Description copied from interface: ElementState
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.

Specified by:
getValueAsBean in interface ElementState
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

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

Specified by:
getValueAsBean in interface ElementState
Throws:
InvalidPathException
TypeException
FormStateException

setMeta

public void setMeta(boolean meta)
Toggle the meta-bit on this node.

See Also:
isMeta()

addRepeatEntry

public FormPath addRepeatEntry()
                        throws FormStateException,
                               TypeException,
                               InvalidPathException
Description copied from interface: ElementState
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.

Specified by:
addRepeatEntry in interface ElementState
Returns:
The path to the newly created entry
Throws:
TypeException - If the given path does not point to a repeat element
FormStateException
InvalidPathException

addRepeatEntry

public FormPath addRepeatEntry(int repeatID)
                        throws TypeException,
                               InvalidPathException,
                               FormStateException
Throws:
TypeException
InvalidPathException
FormStateException

removeRepeatEntry

public void removeRepeatEntry(int repeatID)
                       throws TypeException,
                              InvalidPathException,
                              FormStateException
Description copied from interface: ElementState
Remove the tree under a repeat entry, denoted by the given path.

Specified by:
removeRepeatEntry in interface ElementState
Parameters:
repeatID - The ID of the repeat entry
Throws:
TypeException - If the given path does not point to a repeat element entry
InvalidPathException
FormStateException

getStaticElement

public FormElement getStaticElement()
Get a reference to the static form element this node represents. null if unknown or not applicable (some meta nodes for instance),


getDOMElement

org.w3c.dom.Element getDOMElement()
Get the DOM Element representation of this node.


initializeValidationRules

public void initializeValidationRules(java.util.List<ValidationRule> rules)
Set list of complex validation rules for this element, The list will be deep-cloned. Used at initialization only.

Throws:
java.lang.IllegalStateException - if already set

getValidationRules

java.util.List<ValidationRule> getValidationRules()
Get the list of complex validation rules. If none exist, the empty list is returned.