net.xoetrope.xui.validation
Class XValidationHandler

java.lang.Object
  net.xoetrope.xui.validation.XValidationHandler

All Implemented Interfaces:

XExceptionHandler

public class XValidationHandler

extends java.lang.Object

implements XExceptionHandler

Provides a means of managing validations. This class is intended as a mixin class for the panel classes such as XPage. Validations are integrated with the event handler so that when the event with which the validation is associated is triggered the validation is invoked. Failure of a validation results in subsequent event handler methods being blocked.

Validations are also invoked at page transition and all validations rules are checked. If all validations are not passed then the page transition can be blocked.

If a validation failes then an exception is thrown. The exception is by default handled by this class but it can be redirected to a custom exception handler with the setExceptionHandler method. This interface allows exceptions to handled in a variety of different ways.

Copyright: Copyright (c) Xoetrope Ltd., 1998-2003
License: see license.txt $Revision: 2.10 $

validationFactory

protected XValidationFactory validationFactory

The project XValidationFactory

validations

protected java.util.Hashtable validations

Hashtable of project validations

customExceptionHandler

protected XExceptionHandler customExceptionHandler

The XExceptionHandler which will handle validation exceptions

container

protected java.lang.Object container

For accessing function validations

XValidationHandler

public XValidationHandler(java.lang.Object c)

Create a new validation handler for the specified container. The container provides the context in which the validation operate. Therefore validation methods are found by reflection in the specified container. Normally the container is the current XPage or a derived class.

Parameters:

c - the container

setupEventHandler

public void setupEventHandler(XuiEventHandler eh)

Set the event handler instance. This class needs to interact with the event handler to manage focus and to gain access to the current event

Parameters:

eh - the event handler

setExceptionHandler

public void setExceptionHandler(XExceptionHandler eh)

Set the exception handler called when a validation exception is trapped

Parameters:

eh - The ExceptionHandler to be used

clearValidations

public void clearValidations()

Reset/removes all validations

addValidation

public XValidator addValidation(XuiEventHandler eventHandler,
                                java.lang.Object comp,
                                java.lang.String validationName,
                                java.lang.String method,
                                int mask,
                                XmlElement pageEle)

Adds a validation to this page.

Parameters:

eventHandler - the current event handler that this handler will use to listen to for events that should trigger validations

comp - the component being validated

validationName - the name of the validation in the validation file

method - the method used to get the component's value if any

mask - the event mask used to filter the events that trigger the validation

pageEle - the XML element which is declared in the page

Returns:

the new and initialized XValidator

getValidation

public XValidator getValidation(java.lang.String validationName,
                                java.lang.String method,
                                int mask,
                                XmlElement pageEle)

Adds a validation to this page.

Parameters:

method - The Method to be called for a function validation

validationName - the name of the validation in the validation file

mask - the event mask used to filter the events that trigger the validation

Returns:

the new and initialized XValidator

getValidation

public XValidator getValidation(java.lang.String validationName,
                                java.lang.String method)

Gets a XValidator object. The parameters of the object are read from the validation file

Parameters:

validationName - the name of the validation in the validation file

method - the method used to get the component's value if any

Returns:

the new and initialized XValidator

getValidations

public java.util.Vector getValidations(java.lang.Object comp)

Gets all the validations installed for a component

Parameters:

comp - the target component

Returns:

a Vector of XValidators

removeValidations

public void removeValidations(java.lang.Object comp)

Remove any validations bound to the passed component

Parameters:

comp - The component being validated

addValidation

public XValidator addValidation(XuiEventHandler eventHandler,
                                java.lang.Object comp,
                                java.lang.String validationName,
                                java.lang.String method)

Adds a validation to this page. It is assumed that the validation will be invoked in response to FocusEvent.FOCUS_LOST events

Parameters:

eventHandler - the current event handler that this handler will use to listen to for events that should trigger validations

comp - the component being validated

validationName - the name of the validation in the validation file

method - the method used to get the component's value if any

Returns:

the new and initialized XValidator

addValidation

public XValidator addValidation(XuiEventHandler eventHandler,
                                java.lang.Object comp,
                                java.lang.String validationName)

Adds a validation to this page. It is assumed that the validation will be invoked in response to FocusEvent.FOCUS_LOST events

Parameters:

eventHandler - the current event handler that this handler will use to listen to for events that should trigger validations

comp - the component being validated

validationName - the name of the validation in the validation file

Returns:

the new and initialized XValidator

setValidationFactory

public void setValidationFactory(XValidationFactory vf)

Sets the factory used to create XValidator objects

Parameters:

vf - The ValidationFactory to be used

validationHandler

public int validationHandler(XuiEventHandler eventHandler)

Invoke the validators for the last event. Multiple validations are checked in the order in which they were added.

Parameters:

the - event handler

Returns:

the maximum level returned by the validators

checkValidations

public int checkValidations()

Check all validations for this page. Typically this method should be invoked prior to a page transition or a critical transaction.

Returns:

the maximum error level raised by the validators

accumulateMessages

public int accumulateMessages(boolean accumulate,
                              int level)

informs the handler when a page validation is starting or stopping. Typically when it starts the page will begin to accumulate messages which are to be displayed. When the parameter is false the page will usually display the accumulated messages

Specified by:

accumulateMessages in interface XExceptionHandler

Parameters:

level - The worst level of validation resulting from prior validations

accumulate - boolean to indicate whether the accumulation is started or stopped.

Returns:

The result of the validation

handleException

public boolean handleException(java.lang.Object comp,
                               java.lang.Exception ex,
                               java.lang.Object validator)

A method called when a validation exeption has been trapped.

Specified by:

handleException in interface XExceptionHandler

Parameters:

comp - Component being validated

ex - The exception caused

validator - The validator being used to validate.

Returns:

true to continue with error validation or false to suppress further validation.

handleEventHandlerException

public boolean handleEventHandlerException(XProject project,
                                           java.lang.Object container,
                                           java.lang.Throwable error)

Handle an exception during the invocation of a page's event handler. The page normally implements this interface and has the first chance at handling the error. Thereafter if false is returned a central (optional) exception handler owned by the project is invoked.

Specified by:

handleEventHandlerException in interface XExceptionHandler

Parameters:

project - the current project

container - the page

error - the exception or error that was thrown

Returns:

true to continue processing, false to stop processing