adapforms.runtime
Class FormInstanceImpl

java.lang.Object
  extended by adapforms.runtime.FormInstanceImpl
All Implemented Interfaces:
FormInstance

public class FormInstanceImpl
extends java.lang.Object
implements FormInstance

Concrete implementation of FormInstance, with a few added methods for internal framework use.

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

Constructor Summary
FormInstanceImpl(Form form, InstanceCallback callback, Localization localization)
          Create a new form instance, given a form.
 
Method Summary
 void addHook(FormHook hook)
          Same as FormInstance.addHook(String, FormHook), but the hook is not bound to any specific path.
 void addHook(java.lang.String pathString, FormHook hook)
          Add a hook that will be triggered whenever the value of the form element, pointed to by the given path, changes value without causing a validation problem in the process.
 FormPath addRepeatEntry(FormPath repeatPath, int repeatID, FormData initialValues)
          Create a new repeat entry.
 void checkInitialized(boolean expected)
          Check if the instance has been initialized, and throw an exception if not (if expected=true), or if the instance has already been initialized and expected=false.
 void displayMessageToUser(java.lang.String message)
          Display a simple text message to the user of the form.
 ElementState elementState(FormPath path)
          Get the mutable state of a form element, given it's runtime path.
 ElementState elementState(java.lang.String path)
           
 java.util.List<Adaptation> endAdaptationCycle()
          Called by the modality-specific layer at the end of each adaptation cycle, to collect any adaptations that have been triggered due to the recent user input.
 java.util.Map<FormPath,java.util.List<ValidationProblem>> getAllValidationErrors(FormPath parentPath)
          Get a collection of all validation errors in the given sub-form.
<T> T
getAttribute(java.lang.String key)
          Retrieve a stored attribute set on this instance.
 InstanceCallback getCallback()
           
 FormData getContents()
          Retrieve a snapshot of all the non-null values entered into the form at the time of invocation.
 AdaptationCycle getCurrentCycle()
          Get a reference to the currently active adaptation cycle.
 org.w3c.dom.Document getDOMState()
          Obtain a reference to the internal state tree in form of a DOM document.
 Form getForm()
          The form that has is an instance of.
 FormStatus getGlobalStatus()
           
 Localization getLocalization()
          Get the localization.
 java.lang.String getRole()
          Retrieve the current user role used by the instance.
 StateTree getState()
          Access the state tree for this instance.
 FormStatus getStatus()
          Determine the status of the instance.
 FormStatus getStatusComplete()
          Determine the complete status of the instance.
 java.lang.String getSubmitActionTitle()
          The title of the submit action.
 void initialize()
          Initialize the instance, inserting default values.
 void initialize(FormData initialContents)
          Initialize the form inserting the values from the given initial contents instead of using default values.
 void removeRepeatEntry(FormPath path)
           
 void setAttribute(java.lang.String key, java.lang.Object value)
          Store an attribute (name, value pair) on this instance.
 void setCallback(InstanceCallback callback)
          Define a new instance callback that will receive form events.
 void setRole(java.lang.String role)
          Change the user role of the instance.
 void setSubmitActionTitle(java.lang.String title)
          Change the title of the submission action.
 void submit()
          The user submits the form.
 void updateStatus(boolean fromInitCode)
          Update the form status.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FormInstanceImpl

public FormInstanceImpl(Form form,
                        InstanceCallback callback,
                        Localization localization)
Create a new form instance, given a form.

Parameters:
callback - Callback that receives form events (at form completion etc.)
localization - Localization, or null to use default.
Method Detail

getStatusComplete

public FormStatus getStatusComplete()
Description copied from interface: FormInstance
Determine the complete status of the instance. See class description for details.

Specified by:
getStatusComplete in interface FormInstance

getStatus

public FormStatus getStatus()
Description copied from interface: FormInstance
Determine the status of the instance. See class description for details.

Specified by:
getStatus in interface FormInstance

getGlobalStatus

public FormStatus getGlobalStatus()

checkInitialized

public void checkInitialized(boolean expected)
                      throws FormStateException
Check if the instance has been initialized, and throw an exception if not (if expected=true), or if the instance has already been initialized and expected=false.

Throws:
FormStateException

initialize

public void initialize()
                throws FormStateException,
                       FormRuntimeException
Description copied from interface: FormInstance
Initialize the instance, inserting default values.

See class description for details about initialization.

Specified by:
initialize in interface FormInstance
Throws:
FormStateException - if already initialized
FormRuntimeException

initialize

public void initialize(FormData initialContents)
                throws FormStateException,
                       FormRuntimeException
Description copied from interface: FormInstance
Initialize the form inserting the values from the given initial contents instead of using default values. The primary use of this method is to resume work on an instance previously stored. See FormInstance.getContents().

If an element is not represented in the given contents, a null-value will be inserted.

See class description for details about initialization.

Specified by:
initialize in interface FormInstance
Throws:
FormStateException - if already initialized
FormRuntimeException

getLocalization

public Localization getLocalization()
Description copied from interface: FormInstance
Get the localization.

Specified by:
getLocalization in interface FormInstance

getForm

public Form getForm()
Description copied from interface: FormInstance
The form that has is an instance of.

Specified by:
getForm in interface FormInstance

getDOMState

public org.w3c.dom.Document getDOMState()
                                 throws FormStateException
Description copied from interface: FormInstance
Obtain a reference to the internal state tree in form of a DOM document. The document does not allow modifications to its structure, but allows direct real-time inspection and manipulation of the value and state parameters of each form element.

Each DOM node represents a form element, and has the following modifiable attributes:
- relevant: Relevance flag (inheritance based, true/false)
- relevantRaw: Relevance flag (raw value, true/false)
- readonly: Read-only flag (true/false)
- required: Required flag (true/false)
- value: The value of the element (string encoded, automatic type conversion)
In addition, the value may be accessed by the Node.getNodeValue() method.

Semantic rules using XPath operate on this tree.

Specified by:
getDOMState in interface FormInstance
Throws:
FormStateException

addHook

public void addHook(FormHook hook)
             throws InvalidPathException,
                    FormStateException
Description copied from interface: FormInstance
Same as FormInstance.addHook(String, FormHook), but the hook is not bound to any specific path. Instead, the hook will receive all events, regardless of which form element is affected.

Specified by:
addHook in interface FormInstance
Parameters:
hook - Hook to add
Throws:
InvalidPathException
FormStateException

elementState

public ElementState elementState(java.lang.String path)
                          throws InvalidPathException,
                                 FormStateException
Specified by:
elementState in interface FormInstance
Parameters:
path - Runtime path to use for look-up
Throws:
InvalidPathException
FormStateException
See Also:
FormInstance.elementState(FormPath)

elementState

public ElementState elementState(FormPath path)
                          throws InvalidPathException,
                                 FormStateException
Description copied from interface: FormInstance
Get the mutable state of a form element, given it's runtime path.

This allows for both inspection and transformation of the data or meta-data associated with the form element in question.

Specified by:
elementState in interface FormInstance
Parameters:
path - Runtime path to use for look-up
Returns:
State object corresponding to the node
Throws:
InvalidPathException
FormStateException

addHook

public void addHook(java.lang.String pathString,
                    FormHook hook)
             throws InvalidPathException,
                    FormStateException
Description copied from interface: FormInstance
Add a hook that will be triggered whenever the value of the form element, pointed to by the given path, changes value without causing a validation problem in the process. Multiple hooks can be added to the same path.

Hooks can only be added before the form has been initialized.

Also notice that only the static path will be used. That is. you cannot add a hook to react to a specific repeat entry. Instead, the hook will be added to the

Specified by:
addHook in interface FormInstance
Parameters:
pathString - Path to which the hook should be added
hook - Hook to add
Throws:
InvalidPathException
FormStateException

setRole

public void setRole(java.lang.String role)
             throws FormStateException
Description copied from interface: FormInstance
Change the user role of the instance. This operation is only permitted before the instance is initialized.

Specified by:
setRole in interface FormInstance
Throws:
FormStateException

getRole

public java.lang.String getRole()
Description copied from interface: FormInstance
Retrieve the current user role used by the instance.

Specified by:
getRole in interface FormInstance
See Also:
FormInstance.getRole()

getContents

public FormData getContents()
                     throws FormStateException
Description copied from interface: FormInstance
Retrieve a snapshot of all the non-null values entered into the form at the time of invocation. Only possible on initialized instances. See FormInstance.initialize(FormData) for a possible use scenario.

Specified by:
getContents in interface FormInstance
Throws:
FormStateException

updateStatus

public void updateStatus(boolean fromInitCode)
Update the form status.

Parameters:
fromInitCode - Called from initialization code?

getCallback

public InstanceCallback getCallback()

setCallback

public void setCallback(InstanceCallback callback)
                 throws FormStateException
Description copied from interface: FormInstance
Define a new instance callback that will receive form events. Setting a new callback will replace the existing one.

Specified by:
setCallback in interface FormInstance
Throws:
FormStateException

endAdaptationCycle

public java.util.List<Adaptation> endAdaptationCycle()
                                              throws FormStateException
Called by the modality-specific layer at the end of each adaptation cycle, to collect any adaptations that have been triggered due to the recent user input.

Throws:
FormStateException

getAllValidationErrors

public java.util.Map<FormPath,java.util.List<ValidationProblem>> getAllValidationErrors(FormPath parentPath)
                                                                                 throws InvalidPathException,
                                                                                        FormStateException
Get a collection of all validation errors in the given sub-form. Only relevant elements are considered

Throws:
InvalidPathException
FormStateException

displayMessageToUser

public void displayMessageToUser(java.lang.String message)
                          throws FormStateException
Description copied from interface: FormInstance
Display a simple text message to the user of the form.

Specified by:
displayMessageToUser in interface FormInstance
Throws:
FormStateException

getSubmitActionTitle

public java.lang.String getSubmitActionTitle()
Description copied from interface: FormInstance
The title of the submit action. This usually means the text on the submission button, but is up to the modality chosen.

Specified by:
getSubmitActionTitle in interface FormInstance

setSubmitActionTitle

public void setSubmitActionTitle(java.lang.String title)
                          throws FormStateException
Description copied from interface: FormInstance
Change the title of the submission action. The title may be changed while the form is being adapted.

Specified by:
setSubmitActionTitle in interface FormInstance
Throws:
FormStateException
See Also:
FormInstance.getSubmitActionTitle()

getAttribute

public <T> T getAttribute(java.lang.String key)
Description copied from interface: FormInstance
Retrieve a stored attribute set on this instance.

Specified by:
getAttribute in interface FormInstance
See Also:
If the attribute is not found, null is returned.

setAttribute

public void setAttribute(java.lang.String key,
                         java.lang.Object value)
Description copied from interface: FormInstance
Store an attribute (name, value pair) on this instance. This is merely a convenient way for the domain application to attach extra information to the instance, and will have no effect on the operation of the framework.

There can be any number of values stored, one for each key.

Specified by:
setAttribute in interface FormInstance
See Also:
FormInstance.getAttribute(java.lang.String)

addRepeatEntry

public FormPath addRepeatEntry(FormPath repeatPath,
                               int repeatID,
                               FormData initialValues)
                        throws FormStateException,
                               TypeException,
                               InvalidPathException
Create a new repeat entry.

Parameters:
repeatPath - Path to repeat element
repeatID - Locally unique ID number of the entry
initialValues - Initial values to use - null if not applicable
Throws:
FormStateException
TypeException
InvalidPathException

removeRepeatEntry

public void removeRepeatEntry(FormPath path)
                       throws FormStateException,
                              TypeException,
                              InvalidPathException
Throws:
FormStateException
TypeException
InvalidPathException

getCurrentCycle

public AdaptationCycle getCurrentCycle()
Get a reference to the currently active adaptation cycle.


submit

public void submit()
The user submits the form.

This method is not called by the domain application directly, but by the user indirectly via the UI layer.


getState

public StateTree getState()
Access the state tree for this instance.