org.norther.tammi.spray.template
Interface FormFilter

All Superinterfaces:

AccessController, CacheClient, Filter, KeyFilter, Refreshable, SecureFilter, SecureKeyFilter

All Known Implementing Classes:

DefaultFormFilter

public interface FormFilter
extends SecureKeyFilter, CacheClient

FormFilter supports rendering and validation of form-based input. The filter configuration defines default templates for forms, and controls within forms, applied to page templates. Forms are rendered as variables and controls as their named attributes.

Form and control templates may be grouped into themes defining different layout and other visual properties for the corresponding forms. Default templates are applied when a form theme is not specified.

Variables and attributes may be protected by an access controller. Permissions for a variable are granted using its variable type as a resource. Permissions for an attribute are granted using a concatenation of its variable type and name as a resource.

Templates are defined separately for forms, infos (read-only forms), input controls and output controls (read-only controls). The defined template may, but need to, have a qualifier, which specifies its application context. Components of a qualifier are always separated by a dot.

Absolute template paths point to the root of the template engine. Relative template paths are relative to the path of the current page template. The default form template is specified without a qualifier. A variable specific template is specified by using the variable type as a qualifier.

The default input control template is specified without a qualifier. A type specific input control template is specified by using a class name as a qualifier. Controls for primitive types are qualified with the corresponding class types. A generic control for enumerations is qualified with 'enum'. Array types are qualified separately from component types. A generic control for arrays is qualified with '['. Note that any interfaces or superclasses of the type can be used as qualifiers as well.

An attribute specific input control template is specified by using a concatenation of the class name, variable type and attribute name, or any combination of them, as a qualifier.

Optional info and output templates correspond to form and input templates when resolving templates for requests having only read access to the active page template.

Form themes are specified by prefixing the corresponding qualifier with the name of the theme using a dot as a separator.

Properties may be defined to provide additional parameters for specifying template specific styles, formatting and other control. The naming rules of template qualifiers apply but the last component of the qualifier is the name of the property. Note that the name of the property may not contain dots. The corresponding templates are responsible for applying the defined properties.

In addition, property qualifiers may be prefixed with the resolved template name in dot format without the leading slash/dot to apply more fine grained selection of properties. Note that info and output template names can't be applied as additional property selectors.

Localization of forms is enabled by setting the localized forms property. The localization resource bundles are resolved by ResourceFilter by using the concatenation of the corresponding variable type and attribute name as the qualifier.

If a form theme is given as a request attribute or parameter, it will override any default templates.

Author:

Ilkka Priha

Field Summary

static String	FORM_ID_NAME The recommended form id field name.
static String	FORM_INDEX_NAME The recommended form index field name.

Method Summary

void	clearControlAttributes() Clears all control attributes.
void	clearFormProperties() Clears all form properties.
void	clearFormTemplates() Clears all form templates.
void	clearInfoTemplates() Clears all info templates.
void	clearInputTemplates() Clears all input templates.
void	clearOutputTemplates() Clears all output templates.
void	clearParameterMap(ServletRequest request, ServletResponse response, FilterChain chain) Clears the parameter map of the specified request.
void	clearParameterMap(String prefix, ServletRequest request, ServletResponse response, FilterChain chain) Clears the prefixed parameter map of the specified request.
Set	controlAttributeSet() Returns a read-only set of control attribute qualifiers.
Variable	createVariable(String type) Creates a new variable instance of the specified type.
Set	formPropertySet() Returns a read-only set of form property qualifiers.
Set	formQualifierSet() Returns a read-only set of form template qualifiers.
String	getControlAttribute(String qualifier) Gets the qualified control attribute.
String	getCurrentForm(ServletRequest request, ServletResponse response, FilterChain chain) Gets the current form of the specified request.
String	getDefaultFormName() Gets the theme of the default form.
String	getFormIdName() Gets the name of the form id field.
String	getFormIndexName() Gets the name of the form index field.
String	getFormProperty(String qualifier) Gets the qualified form property.
String	getFormTemplate() Gets the default form template.
String	getFormTemplate(String qualifier) Gets the qualified form template.
String	getInfoTemplate() Gets the default info template.
String	getInfoTemplate(String qualifier) Gets the qualified info template.
String	getInputTemplate() Gets the default input template.
String	getInputTemplate(String qualifier) Gets the qualified input template.
String	getOutputTemplate() Gets the default output template.
String	getOutputTemplate(String qualifier) Gets the qualified output template.
Map	getParameterMap(ServletRequest request, ServletResponse response, FilterChain chain) Gets the parameter map of the specified request.
Map	getParameterMap(String prefix, ServletRequest request, ServletResponse response, FilterChain chain) Gets the prefixed parameter map of the specified request.
Map	getParameterMap(Variable variable, String prefix, ServletRequest request, ServletResponse response, FilterChain chain) Gets the parameter map of the specified variable.
Map	getValidationMap(Variable variable, String prefix, ServletRequest request, ServletResponse response, FilterChain chain) Gets the validation map of the specified variable.
ObjectName	getVariableRegistryName() Gets the the variable registry of this filter.
Set	infoQualifierSet() Returns a read-only set of info template qualifiers.
Set	inputQualifierSet() Returns a read-only set of input template qualifiers.
boolean	isLocalizedForms() Gets the localized forms flag.
boolean	isValidated(Variable variable, String prefix, ServletRequest request, ServletResponse response, FilterChain chain) Checks whether the specified variable is validated.
Set	outputQualifierSet() Returns a read-only set of output template qualifiers.
void	removeControlAttribute(String qualifier) Removes the qualified control attribute.
void	removeFormProperty(String qualifier) Removes the qualified form property.
void	removeFormTemplate(String qualifier) Removes the qualified form template.
void	removeInfoTemplate(String qualifier) Removes the qualified info template.
void	removeInputTemplate(String qualifier) Removes the qualified input template.
void	removeOutputTemplate(String qualifier) Removes the qualified output template.
void	removeVariable(String prefix, Variable variable, ServletRequest request, ServletResponse response, FilterChain chain) Removes the specified form variable from a session.
void	render(String name, Variable variable, boolean readonly, ServletRequest request, ServletResponse response, FilterChain chain) Renders a form as Variable.
void	render(String name, Variable variable, MBeanAttributeInfo attribute, boolean readonly, ServletRequest request, ServletResponse response, FilterChain chain) Renders a control as the specified attribute of Variable.
void	render(String template, Variable variable, MBeanAttributeInfo attribute, ServletRequest request, ServletResponse response, FilterChain chain) Renders a control as the specified attribute of Variable using a fixed template.
void	render(String template, Variable variable, ServletRequest request, ServletResponse response, FilterChain chain) Renders a form as Variable using a fixed template.
String	resetCurrentForm(ServletRequest request, ServletResponse response, FilterChain chain) Resets the current form of the specified request to the default form.
String	resetCurrentForm(String name, ServletRequest request, ServletResponse response, FilterChain chain) Resets the current form of the specified request to the named form.
void	resetParameterMap(ServletRequest request, ServletResponse response, FilterChain chain) Resets the parameter map of the specified request.
void	resetParameterMap(String prefix, ServletRequest request, ServletResponse response, FilterChain chain) Resets the prefixed parameter map of the specified request.
ConcurrentMap	resolve(String name, Variable variable, MBeanAttributeInfo attribute) Resolves form properties of the specified attribute of Variable.
Variable	restoreVariable(String prefix, String type, boolean create, ServletRequest request, ServletResponse response, FilterChain chain) Restores a saved form variable from a session or optionally creates a missing one.
void	saveVariable(String prefix, Variable variable, ServletRequest request, ServletResponse response, FilterChain chain) Saves the specified form variable to a session.
void	setControlAttribute(String qualifier, String attribute) Sets the qualified control property.
void	setDefaultFormName(String name) Sets the theme of the default form.
void	setFormIdName(String name) Sets the name of the form id field to post the unique name of the submitted form.
void	setFormIndexName(String name) Sets the name of the form index field to post variable indeces of the submitted form.
void	setFormProperty(String qualifier, String property) Sets the qualified form property.
void	setFormTemplate(String template) Sets the default form template.
void	setFormTemplate(String qualifier, String template) Sets the qualified form template.
void	setInfoTemplate(String template) Sets the default info template.
void	setInfoTemplate(String qualifier, String template) Sets the qualified info template.
void	setInputTemplate(String template) Sets the default input template.
void	setInputTemplate(String qualifier, String template) Sets the qualified input template.
void	setLocalizedForms(boolean flag) Sets the localized forms flag.
void	setOutputTemplate(String template) Sets the default output template.
void	setOutputTemplate(String qualifier, String template) Sets the qualified output template.
void	setVariableRegistryName(ObjectName registry) Sets the variable registry of this filter.
boolean	updateForm(Variable variable, String prefix, ServletRequest request, ServletResponse response, FilterChain chain) Updates the specified variable with request parameters.
boolean	validateForm(Variable variable, String prefix, ServletRequest request, ServletResponse response, FilterChain chain) Validates the specified variable with request parameters.

Methods inherited from interface org.norther.tammi.spray.filter.SecureFilter

checkPermission, checkPermission, checkPermission

Methods inherited from interface org.norther.tammi.core.security.AccessController

addAllowedPermission, addDeniedPermission, allowedPermissions, allowedRoleSet, checkPermission, checkPermission, checkPermission, clearAllowedPermissions, clearDeniedPermissions, deniedPermissions, deniedRoleSet, getPermissibleRoles, getPermissibleRoles, getPermissibleRoles, isProtected, removeAllowedPermissions, removeDeniedPermissions, setAllowedPermissions, setDeniedPermissions

Methods inherited from interface javax.servlet.Filter

destroy, doFilter, init

Methods inherited from interface org.norther.tammi.spray.filter.KeyFilter

getKey, getKeyValue, getKeyValues, isLinkedKey, setKey, setLinkedKey

Methods inherited from interface javax.servlet.Filter

destroy, doFilter, init

Methods inherited from interface org.norther.tammi.core.cache.CacheClient

clearCached, expireCached, expireFraction, getCache, isCachingDisabled, removeCache, setCachingDisabled

Methods inherited from interface org.norther.tammi.core.base.Refreshable

getRefreshed, refresh

Field Detail

FORM_ID_NAME

static final String FORM_ID_NAME

The recommended form id field name.

See Also:

Constant Field Values

FORM_INDEX_NAME

static final String FORM_INDEX_NAME

The recommended form index field name.

See Also:

Constant Field Values

Method Detail

isLocalizedForms

boolean isLocalizedForms()

Gets the localized forms flag.

Returns:

the localized forms flag.

setLocalizedForms

void setLocalizedForms(boolean flag)

Sets the localized forms flag.

Parameters:

flag - the localized forms flag.

getDefaultFormName

String getDefaultFormName()

Gets the theme of the default form.

Returns:

the default form.

setDefaultFormName

void setDefaultFormName(String name)

Sets the theme of the default form.

Parameters:

name - the default form.

getFormIdName

String getFormIdName()

Gets the name of the form id field.

Returns:

the form id attribute name.

setFormIdName

void setFormIdName(String name)

Sets the name of the form id field to post the unique name of the submitted form.

Parameters:

name - the form id attribute name.

getFormIndexName

String getFormIndexName()

Gets the name of the form index field.

Returns:

the form index attribute name.

setFormIndexName

void setFormIndexName(String name)

Sets the name of the form index field to post variable indeces of the submitted form.

Parameters:

name - the form id attribute name.

getFormTemplate

String getFormTemplate()

Gets the default form template.

Returns:

the default template or null.

setFormTemplate

void setFormTemplate(String template)

Sets the default form template.

Parameters:

template - the default template.

getInfoTemplate

String getInfoTemplate()

Gets the default info template.

Returns:

the default template or null.

setInfoTemplate

void setInfoTemplate(String template)

Sets the default info template.

Parameters:

template - the default template.

getInputTemplate

String getInputTemplate()

Gets the default input template.

Returns:

the default template or null.

setInputTemplate

void setInputTemplate(String template)

Sets the default input template.

Parameters:

template - the default template.

getOutputTemplate

String getOutputTemplate()

Gets the default output template.

Returns:

the default template or null.

setOutputTemplate

void setOutputTemplate(String template)

Sets the default output template.

Parameters:

template - the default template.

getFormTemplate

String getFormTemplate(String qualifier)

Gets the qualified form template.

Parameters:

qualifier - the qualifier.

Returns:

the template or null.

setFormTemplate

void setFormTemplate(String qualifier,
                     String template)

Sets the qualified form template.

Parameters:

qualifier - the qualifier.

template - the template.

removeFormTemplate

void removeFormTemplate(String qualifier)

Removes the qualified form template.

Parameters:

qualifier - the qualifier.

clearFormTemplates

void clearFormTemplates()

Clears all form templates.

formQualifierSet

Set formQualifierSet()

Returns a read-only set of form template qualifiers.

Returns:

a set of template qualifiers.

getInfoTemplate

String getInfoTemplate(String qualifier)

Gets the qualified info template.

Parameters:

qualifier - the qualifier.

Returns:

the template or null.

setInfoTemplate

void setInfoTemplate(String qualifier,
                     String template)

Sets the qualified info template.

Parameters:

qualifier - the qualifier.

template - the template.

removeInfoTemplate

void removeInfoTemplate(String qualifier)

Removes the qualified info template.

Parameters:

qualifier - the qualifier.

clearInfoTemplates

void clearInfoTemplates()

Clears all info templates.

infoQualifierSet

Set infoQualifierSet()

Returns a read-only set of info template qualifiers.

Returns:

a set of template qualifiers.

getInputTemplate

String getInputTemplate(String qualifier)

Gets the qualified input template.

Parameters:

qualifier - the qualifier.

Returns:

the template or null.

setInputTemplate

void setInputTemplate(String qualifier,
                      String template)

Sets the qualified input template.

Parameters:

qualifier - the qualifier.

template - the template.

removeInputTemplate

void removeInputTemplate(String qualifier)

Removes the qualified input template.

Parameters:

qualifier - the qualifier.

clearInputTemplates

void clearInputTemplates()

Clears all input templates.

inputQualifierSet

Set inputQualifierSet()

Returns a read-only set of input template qualifiers.

Returns:

a set of template qualifiers.

getOutputTemplate

String getOutputTemplate(String qualifier)

Gets the qualified output template.

Parameters:

qualifier - the qualifier.

Returns:

the template or null.

setOutputTemplate

void setOutputTemplate(String qualifier,
                       String template)

Sets the qualified output template.

Parameters:

qualifier - the qualifier.

template - the template.

removeOutputTemplate

void removeOutputTemplate(String qualifier)

Removes the qualified output template.

Parameters:

qualifier - the qualifier.

clearOutputTemplates

void clearOutputTemplates()

Clears all output templates.

outputQualifierSet

Set outputQualifierSet()

Returns a read-only set of output template qualifiers.

Returns:

a set of template qualifiers.

getFormProperty

String getFormProperty(String qualifier)

Gets the qualified form property.

Parameters:

qualifier - the qualifier.

Returns:

the property or null.

setFormProperty

void setFormProperty(String qualifier,
                     String property)

Sets the qualified form property.

Parameters:

qualifier - the qualifier.

property - the property.

removeFormProperty

void removeFormProperty(String qualifier)

Removes the qualified form property.

Parameters:

qualifier - the qualifier.

clearFormProperties

void clearFormProperties()

Clears all form properties.

formPropertySet

Set formPropertySet()

Returns a read-only set of form property qualifiers.

Returns:

a set of property qualifiers.

getControlAttribute

String getControlAttribute(String qualifier)

Gets the qualified control attribute.

Parameters:

qualifier - the qualifier.

Returns:

the attribute or null.

setControlAttribute

void setControlAttribute(String qualifier,
                         String attribute)

Sets the qualified control property.

Parameters:

qualifier - the qualifier.

attribute - the attribute.

removeControlAttribute

void removeControlAttribute(String qualifier)

Removes the qualified control attribute.

Parameters:

qualifier - the qualifier.

clearControlAttributes

void clearControlAttributes()

Clears all control attributes.

controlAttributeSet

Set controlAttributeSet()

Returns a read-only set of control attribute qualifiers.

Returns:

a set of attribute qualifiers.

getVariableRegistryName

ObjectName getVariableRegistryName()

Gets the the variable registry of this filter.

Returns:

the object name of the variable registry or a query.

setVariableRegistryName

void setVariableRegistryName(ObjectName registry)

Sets the variable registry of this filter. If it is not set, the default one will be used.

Parameters:

registry - the object name of the variable registry or a query.

clearParameterMap

void clearParameterMap(ServletRequest request,
                       ServletResponse response,
                       FilterChain chain)

Clears the parameter map of the specified request.

Parameters:

request - the servlet request.

response - the servlet response.

chain - the filter chain.

clearParameterMap

void clearParameterMap(String prefix,
                       ServletRequest request,
                       ServletResponse response,
                       FilterChain chain)

Clears the prefixed parameter map of the specified request.

Parameters:

prefix - the parameter name prefix.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

resetParameterMap

void resetParameterMap(ServletRequest request,
                       ServletResponse response,
                       FilterChain chain)

Resets the parameter map of the specified request.

Parameters:

request - the servlet request.

response - the servlet response.

chain - the filter chain.

resetParameterMap

void resetParameterMap(String prefix,
                       ServletRequest request,
                       ServletResponse response,
                       FilterChain chain)

Resets the prefixed parameter map of the specified request.

Parameters:

prefix - the parameter name prefix.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

getParameterMap

Map getParameterMap(ServletRequest request,
                    ServletResponse response,
                    FilterChain chain)

Gets the parameter map of the specified request.

Parameters:

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Returns:

the parameter map.

getParameterMap

Map getParameterMap(String prefix,
                    ServletRequest request,
                    ServletResponse response,
                    FilterChain chain)

Gets the prefixed parameter map of the specified request.

Parameters:

prefix - the parameter name prefix.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Returns:

the parameter map.

getParameterMap

Map getParameterMap(Variable variable,
                    String prefix,
                    ServletRequest request,
                    ServletResponse response,
                    FilterChain chain)

Gets the parameter map of the specified variable. Localized values are converted into internal form if localized forms are enabled.

Parameters:

variable - the variable.

prefix - an optional prefix.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Returns:

the parameter map.

isValidated

boolean isValidated(Variable variable,
                    String prefix,
                    ServletRequest request,
                    ServletResponse response,
                    FilterChain chain)

Checks whether the specified variable is validated.

Parameters:

variable - the variable.

prefix - an optional prefix.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Returns:

the validation map.

getValidationMap

Map getValidationMap(Variable variable,
                     String prefix,
                     ServletRequest request,
                     ServletResponse response,
                     FilterChain chain)

Gets the validation map of the specified variable.

Parameters:

variable - the variable.

prefix - an optional prefix.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Returns:

the validation map.

validateForm

boolean validateForm(Variable variable,
                     String prefix,
                     ServletRequest request,
                     ServletResponse response,
                     FilterChain chain)

Validates the specified variable with request parameters.

Parameters:

variable - the variable.

prefix - an optional prefix.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Returns:

true for a validated and valid form.

updateForm

boolean updateForm(Variable variable,
                   String prefix,
                   ServletRequest request,
                   ServletResponse response,
                   FilterChain chain)

Updates the specified variable with request parameters.

Parameters:

variable - the variable.

prefix - an optional prefix.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Returns:

true for a valid form.

createVariable

Variable createVariable(String type)
                        throws ConstructionException

Creates a new variable instance of the specified type.

Parameters:

type - the type of the variable.

Returns:

the variable MBean instance.

Throws:

ConstructionException - if construction fails.

restoreVariable

Variable restoreVariable(String prefix,
                         String type,
                         boolean create,
                         ServletRequest request,
                         ServletResponse response,
                         FilterChain chain)
                         throws ConstructionException

Restores a saved form variable from a session or optionally creates a missing one. Created variables are automatically saved into the session if available.

Parameters:

prefix - an optional prefix.

type - the variable type.

create - the create option.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Returns:

the form variable MBean.

Throws:

ConstructionException - if construction fails.

saveVariable

void saveVariable(String prefix,
                  Variable variable,
                  ServletRequest request,
                  ServletResponse response,
                  FilterChain chain)

Saves the specified form variable to a session.

Parameters:

prefix - an optional prefix.

variable - the variable.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

removeVariable

void removeVariable(String prefix,
                    Variable variable,
                    ServletRequest request,
                    ServletResponse response,
                    FilterChain chain)

Removes the specified form variable from a session.

Parameters:

prefix - an optional prefix.

variable - the variable.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

render

void render(String name,
            Variable variable,
            boolean readonly,
            ServletRequest request,
            ServletResponse response,
            FilterChain chain)
            throws TemplateException

Renders a form as Variable.

Parameters:

name - an optional theme.

variable - the variable.

readonly - the readonly option.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Throws:

TemplateException - on errors.

render

void render(String template,
            Variable variable,
            ServletRequest request,
            ServletResponse response,
            FilterChain chain)
            throws TemplateException

Renders a form as Variable using a fixed template.

Parameters:

template - the template.

variable - the variable.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Throws:

TemplateException - on errors.

render

void render(String name,
            Variable variable,
            MBeanAttributeInfo attribute,
            boolean readonly,
            ServletRequest request,
            ServletResponse response,
            FilterChain chain)
            throws TemplateException

Renders a control as the specified attribute of Variable.

Parameters:

name - an optional theme.

variable - the variable.

attribute - the attribute.

readonly - the read-only option.

request - the servlet request.

response - the servlet response.

chain - the filter chain.

Throws:

TemplateException - on errors.

render

void render(String template,
            Variable variable,
            MBeanAttributeInfo attribute,