Classes
enum	State

Public Member Functions
native boolean	finish ()

native Field	getCurrentField ()

native Form	getForm ()

native State	getState ()

native int	getVisibleFieldIndex (Field field)

native boolean	moveToField (Field field)

native boolean	moveToNext ()

native boolean	moveToPrevious (boolean responseRequired)

native boolean	resume ()

native boolean	start ()

	StepSequencer (Form form)

native boolean	stop (boolean responseRequired)

Protected Member Functions
void	finalize () throws Throwable

Detailed Description

StepSequencer manages a progress of forms in the application. When subjects start and stop forms, the sequencer:

Stamps the form with the time that the subject started/completed the form.

Forms that are previously started and stopped can be resumed so as to pick up progress from where subjects left off filling them in.

The step sequencer uses the rules engine to determine which fields are visible according to the edit checks. While stepping through the form fields, for each field the sequencer:

Ensures that responses are valid.
Stamps the field with the time subjects enter responses.
Applies the checks to determine whether affected fields are visible.
Moves to the next or previous field, as requested.

At each state the sequencer provides the current field. The view should use the field to let users respond. The sequencer does not move forward until the response for the current field is found valid. When moving backward or stopping, the current response’s validity is an option left to the caller.

Once subjects respond to all the fields, the sequencer enters the reviewing state. In this state, subjects can revisit the fields at will to edit their responses. If subjects’ editing of responses changes the visibility of any field, the sequencer returns to stepping through the fields.

State diagram:

                  ┌───────────┐
   ┌──┬──┬───────>│  STOPPED  │<──────────────┐
   │  │  │        └───────────┘               │
   │  │  │              │ start()             │
   │  │  │              │ resume()            │
   │  │  │              ├─────────────────────┘
   │  │  │              V
   │  │  │ stop() ┌───────────┐
   │  │  └────────│ STEPPING  │<──────────────┬──┬──┐
   │  │           └───────────┘               │  │  │
   │  │                 │ moveToNext()        │  │  │
   │  │                 │ moveToPrevious()    │  │  │
   │  │                 ├─────────────────────┘  │  │
   │  │                 V                        │  │
   │  │    stop() ┌───────────┐ moveToPrevious() │  │
   │  └───────────│ REVIEWING │──────────────────┘  │
   │              └───────────┘<─────────────────┐  │
   │                    │                        │  │
   │                    │ moveToStep()           │  │
   │                    │                        │  │
   │       stop()       V                        │  │
   │     finish() ┌───────────┐ moveToNext()     │  │
   └──────────────│  EDITING  │──────────────────┴──┘
                  └───────────┘

Constructor & Destructor Documentation

com.mdsol.babbage.model.StepSequencer.StepSequencer ( Form form )

Constructs a step sequencer to manage the progress of a given form.

Parameters

Create the form to manage.

Member Function Documentation

void com.mdsol.babbage.model.StepSequencer.finalize ( ) throws Throwable

protected

native boolean com.mdsol.babbage.model.StepSequencer.finish ( )

Finishes the sequence of fields for the form. This method has no effect if the sequencer is not in the REVIEWING state.

If the form requires a signature, the sequencer verifies that the signature is valid. If it is not, the method returns

false

.

The sequencer timestamps and persists the form.

Upon returning

true

, the sequencer is in the STOPPED state, and getCurrentField() returns

null

.

Returns: Whether the sequence of fields finished successfully.

native Field com.mdsol.babbage.model.StepSequencer.getCurrentField ( )

Gets the current field in the form sequence. Method returns a field if the sequencer is in the

STEPPING

or

EDITING

state. Otherwise, it returns

null

.

Returns: Current field or null.

native Form com.mdsol.babbage.model.StepSequencer.getForm ( )

Gets the form managed by the step sequencer.

Returns: Managed form.

native State com.mdsol.babbage.model.StepSequencer.getState ( )

Gets the current state of the step sequencer.

Returns: Sequencer state.

native int com.mdsol.babbage.model.StepSequencer.getVisibleFieldIndex ( Field field )

Gets the index of a given field in the sequence of fields that are currently visible. The visible index depends on the current state of the form, its previously entered fields, and associated checks. If the field is not visible, this method returns -1.

Parameters

field Field to look up.

Returns: Visibility index of the field or -1.

native boolean com.mdsol.babbage.model.StepSequencer.moveToField ( Field field )

Progresses to a given field in the sequence for the form. This method has no effect if the sequencer is not in the REVIEWING state or if the given field is not visible.

The sequencer moves to the given field and the state changes to the EDITING state.

Parameters

field Field to progress to.

Returns: Whether the current field moved to the given one successfully.

native boolean com.mdsol.babbage.model.StepSequencer.moveToNext ( )

Progresses to the next field in the sequence for the form. This method has no effect if the sequencer is in the STOPPED or REVIEWING state.

If the sequencer is in the STEPPING or EDITING state, it verifies that the response for the current field is valid. If it is not, the method returns

false

. Otherwise the sequencer timestamps and persists the field before applying the checks and deciding what the following field and state should be.

If the sequencer is in the STEPPING state, two outcomes are possible. If another field follows, the state remains as STEPPING. Otherwise the current field is the last one and the sequencer moves to the REVIEWING state.

If the sequencer is in the EDITING state, two outcomes are also possible. If the new response causes the visibility of other fields to change, the current field moves to the next field and the sequencer moves to the STEPPING state. Otherwise, the sequencer returns to the REVIEWING state.

Returns: Whether the current field moved to the next one successfully.

native boolean com.mdsol.babbage.model.StepSequencer.moveToPrevious ( boolean responseRequired )

Progresses to the previous field in the sequence for the form. This method has no effect if the sequencer is in the STOPPED or EDITING state.

If the sequencer is in the STEPPING state, it verifies that the response for the current field is valid. If it is not and the

responseRequired

parameter is

true

, the method returns

false

. The sequencer then timestamps and persists the field before applying the checks and deciding what the following field and state should be.

If the sequencer is in the STEPPING state, the sequencer moves to the previous field if there is one. The state remains the same.

If the sequencer is in the REVIEWING state, the sequencer moves to the last field of the sequence and the state changes to STEPPING.

Parameters

responseRequired Whether to require valid responses.

Returns: Whether the current field moved to the previous one successfully.

native boolean com.mdsol.babbage.model.StepSequencer.resume ( )

Resumes the sequence of fields for the form. This method has no effect if the sequencer is not in the STOPPED state, or if the form has already completed.

If any of the fields already have responses, they are preserved and the current field sets to the first visible field that doesn’t already have a response. If all fields already have a response, the current field is set to the last one.

Upon returning, the sequencer has applied the setup checks, is in the STEPPING state, and the caller can use getCurrentField() to handle the current field.

Returns: Whether the sequence of fields resumed successfully.

native boolean com.mdsol.babbage.model.StepSequencer.start ( )

Starts the sequence of fields for the form. This method has no effect if the sequencer is not in the STOPPED state, or if the form is complete.

If any of the fields already has responses, they are cleared and the current field is set to the first visible one in the sequence.

Upon returning, the sequencer has applied the setup checks, is in the STEPPING state, and the caller can use getCurrentField() to handle the current field.

Returns: Whether the sequence of fields started successfully.

native boolean com.mdsol.babbage.model.StepSequencer.stop ( boolean responseRequired )

Stops progressing through the sequence of fields for the form. This method has no effect if the sequencer is already in the STOPPED state.

If the sequencer is in the STEPPING or EDITING state, it verifies that the response for the current field is valid. If it is not and the

responseRequired

parameter is

true

, the method returns

false

. The sequencer then timestamps and persists the field.

Upon returning

true

, the sequencer is in the STOPPED state and getCurrentField() returns

null

.

Parameters

responseRequired Whether to require valid responses.

Returns: Whether the sequence of fields stopped successfully.

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation