adapforms.runtime
Interface FormInstance

All Known Implementing Classes:
FormInstanceImpl

public interface FormInstance

An instantiated form, that holds form data, state etc. and can be adapted. To instantiate a loaded form, use the Form.createInstance(adapforms.runtime.events.InstanceCallback) methods.

Form status
The instance can be in one of a given number of states. This can be inspected by either a call to getStatusComplete() or getStatus() or by listening to InstanceCallback.onStatusChange(FormInstance) events. The different states are described in more detail in the FormStatus enum.

The difference between getStatusComplete() and getStatus() is, that they give the status for the complete instance (taking all elements into account) and the status of the part of the instance the user can currently see (according to role), respectively.

Upon creation of the instance, the status is set to FormStatus.Uninitialized, meaning that it is not "ready for use" yet. In this state, you may perform any pre-initialization operations required. This includes adding form hooks (via addHook(String, FormHook)), changing user role, language, callback etc.

When you are ready to initialize the instance for use, and start the adaptation system, you must invoke initialize() (or an overloaded version of it), at which point most other methods become eligible for use.
During the initialization the relevant hooks will be triggered when inserting default values and/or values restored from a previous session. This means, that the developer in most cases do not need to write any extra code to allow for resuming partially stored forms, as this will be handled transparently by getContents() and initialize(FormData).

Accessing form data and state
The primary means of accessing the state of the form instance (most notably the user-entered values) is through the ElementState interface. Access is usually gained via calls to elementState(FormPath).

In order to read the entire set of values from the form (e.g. upon user submission), using getDOMState() or getContents() may be more convenient than reading each value independently.

General comments about the methods
Unless otherwise specified, methods that take a "path" parameter, expects it to be the full path to the form element that should be inspected or changed.

Most methods can throw a common set of exceptions:
- InvalidPathException is thrown if a form path is supplied, that does not map to a form element.
- FormStateException is thrown if the called method expects the instance to be initialized, but it is not (or vice versa).

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

Method Summary
 void addHook(FormHook hook)
          Same as addHook(String, FormHook), but the hook is not bound to any specific path.
 void addHook(java.lang.String path, 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.
 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)
           
<T> T
getAttribute(java.lang.String key)
          Retrieve a stored attribute set on this instance.
 FormData getContents()
          Retrieve a snapshot of all the non-null values entered into the form at the time of invocation.
 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.
 Localization getLocalization()
          Get the localization.
 java.lang.String getRole()
          Retrieve the current user role used by the 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 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.
 

Method Detail

getForm

Form getForm()
The form that has is an instance of.


getLocalization

Localization getLocalization()
Get the localization.


getStatusComplete

FormStatus getStatusComplete()
Determine the complete status of the instance. See class description for details.


getStatus

FormStatus getStatus()
Determine the status of the instance. See class description for details.


initialize

void initialize()
                throws FormStateException,
                       FormRuntimeException
Initialize the instance, inserting default values.

See class description for details about initialization.

Throws:
FormStateException - if already initialized
FormRuntimeException

initialize

void initialize(FormData initialContents)
                throws FormStateException,
                       FormRuntimeException
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 getContents().

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

See class description for details about initialization.

Throws:
FormStateException - if already initialized
FormRuntimeException

addHook

void addHook(java.lang.String path,
             FormHook hook)
             throws InvalidPathException,
                    FormStateException
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

Parameters:
path - Path to which the hook should be added
hook - Hook to add
Throws:
InvalidPathException
FormStateException

addHook

void addHook(FormHook hook)
             throws InvalidPathException,
                    FormStateException
Same as 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.

Parameters:
hook - Hook to add
Throws:
InvalidPathException
FormStateException

setCallback

void setCallback(InstanceCallback callback)
                 throws FormStateException
Define a new instance callback that will receive form events. Setting a new callback will replace the existing one.

Throws:
FormStateException

getAttribute

<T> T getAttribute(java.lang.String key)
Retrieve a stored attribute set on this instance.

See Also:
If the attribute is not found, null is returned.

setAttribute

void setAttribute(java.lang.String key,
                  java.lang.Object value)
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.

See Also:
getAttribute(java.lang.String)

getRole

java.lang.String getRole()
Retrieve the current user role used by the instance.

See Also:
getRole()

setRole

void setRole(java.lang.String role)
             throws FormStateException
Change the user role of the instance. This operation is only permitted before the instance is initialized.

Throws:
FormStateException

elementState

ElementState elementState(FormPath path)
                          throws InvalidPathException,
                                 FormStateException
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.

Parameters:
path - Runtime path to use for look-up
Returns:
State object corresponding to the node
Throws:
InvalidPathException
FormStateException

elementState

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

displayMessageToUser

void displayMessageToUser(java.lang.String message)
                          throws FormStateException
Display a simple text message to the user of the form.

Throws:
FormStateException

getContents

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

Throws:
FormStateException

getDOMState

org.w3c.dom.Document getDOMState()
                                 throws FormStateException
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.

Throws:
FormStateException

getSubmitActionTitle

java.lang.String getSubmitActionTitle()
The title of the submit action. This usually means the text on the submission button, but is up to the modality chosen.


setSubmitActionTitle

void setSubmitActionTitle(java.lang.String title)
                          throws FormStateException
Change the title of the submission action. The title may be changed while the form is being adapted.

Throws:
FormStateException
See Also:
getSubmitActionTitle()