org.liquidsite.core.web
Class FormHandler

java.lang.Object
  org.liquidsite.core.web.FormHandler

Direct Known Subclasses:

org.liquidsite.app.admin.AdminFormHandler

public abstract class FormHandler

extends java.lang.Object

A form request handler. This class attempts to provide some workflow support, by making initial request parameter analysis and calling the appropriate event methods. A subclass should implement the various event methods.

Constructor Summary

FormHandler()

Method Summary

protected abstract void	display(Request request, int step) Displays a form for the specified workflow step.
protected abstract int	handle(Request request, int step) Handles a validated form for the specified workflow step.
void	process(Request request) Processes the form request.
void	processWithoutErrorHandling(Request request) Processes the form request.
protected abstract void	validate(Request request, int step) Validates a form for the specified workflow step.
protected void	workflowEntered(Request request) This method is called when the user is entering the workflow.
protected void	workflowError(Request request, FormHandlingException e) This method is called when an error was encountered during the processing.
protected void	workflowExited(Request request) This method is called when the user is exiting the workflow.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FormHandler

public FormHandler()

Method Detail

process

public final void process(Request request)

Processes the form request. This method is called for each incoming request to the form workflow, including the first one requesting presentation of the (first) form. This method handles errors by calling the error event method. To handle errors externally, use the processWithoutErrorHandling method instead.

Parameters:

request - the request object

See Also:

processWithoutErrorHandling(org.liquidsite.core.web.Request)

processWithoutErrorHandling

public final void processWithoutErrorHandling(Request request)
                                       throws FormHandlingException

Processes the form request. This method is called for each incoming request to the form workflow, including the first one requesting presentation of the (first) form. Note that this method will not trigger the error event on error, but will return an exception instead.

Parameters:

request - the request object

Throws:

FormHandlingException - if an error was encountered while processing the form

See Also:

process(org.liquidsite.core.web.Request)

display

protected abstract void display(Request request,
                                int step)
                         throws FormHandlingException

Displays a form for the specified workflow step. The special workflow step zero (0) is used for indicating display of the originating page outside the form workflow. Normally that would cause a redirect.

Parameters:

request - the request object

step - the workflow step, or zero (0)

Throws:

FormHandlingException - if an error was encountered while processing the form

validate

protected abstract void validate(Request request,
                                 int step)
                          throws FormValidationException,
                                 FormHandlingException

Validates a form for the specified workflow step. If the form validation fails in this step, the form page for the workflow step will be displayed again with an 'error' attribute containing the message in the validation exception.

Parameters:

request - the request object

step - the workflow step

Throws:

FormValidationException - if the form request data validation failed

FormHandlingException - if an error was encountered while processing the form

handle

protected abstract int handle(Request request,
                              int step)
                       throws FormHandlingException

Handles a validated form for the specified workflow step. This method returns the next workflow step, i.e. the step used when calling the display method. If the special zero (0) workflow step is returned, the workflow is assumed to have terminated. Note that this method also allows additional validation to occur. By returning the incoming workflow step number and setting the appropriate request attributes the same results as in the normal validate method can be achieved. For recoverable errors, this is the recommended course of action.

Parameters:

request - the request object

step - the workflow step

Returns:

the next workflow step, or zero (0) if the workflow has finished

Throws:

FormHandlingException - if an error was encountered while processing the form

workflowEntered

protected void workflowEntered(Request request)
                        throws FormHandlingException

This method is called when the user is entering the workflow. This event can be used for handling object locking or messaging related to the workflow. By default this method does nothing.

Parameters:

request - the request object

Throws:

FormHandlingException - if an error was encountered while processing the form

workflowExited

protected void workflowExited(Request request)
                       throws FormHandlingException

This method is called when the user is exiting the workflow. This even is triggered either by finishing the complete workflow, or by backing out to workflow step zero (0). This event can be used for handling object locking or messaging related to the workflow. By default this method does nothing.

NOTE: This method will not be called when the user exits the workflow in a non-standard way. Closing the browser window, using back buttons or causing form handling exceptions are all examples of when this method will NOT be called.

Parameters:

request - the request object

Throws:

FormHandlingException - if an error was encountered while processing the form

workflowError

protected void workflowError(Request request,
                             FormHandlingException e)

This method is called when an error was encountered during the processing. This event can be used for logging errors and displaying a simple error page. By default this method does nothing.

Parameters:

request - the request object

e - the form handling exception