To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Wraps the parameters and uploaded files of a single form submission, giving controllers and JS controller functions typed, cleaned access to request data instead of reading the servlet request directly. Provides typed accessor methods (string, long, date, boolean, list and so on) that trim and sanitise raw parameter values, plus helpers for copying the parameter set with a subset of names included or excluded by prefix, suffix or exact match. Created per request via create() and passed as the standard first argument to JS controller functions and Java "do..." handler methods that process a form post.
Properties
| Property | Returns | Description |
|---|---|---|
| currentUser | Profile | The profile of the currently authenticated user for the request this form was submitted in. |
| files | Map<String,FileItem> | The uploaded files of this form submission, keyed by their form field name. Null if this FormContext was not created from an HTTP request carrying file uploads. |
| parameters | Map<String,String> | Returns this FormContext's parameters as a map of name to string value, converting any non-string (typed) parameter values to their string form. Values are not cleaned or sanitised. |
| request | Request | The underlying Milton HTTP request this FormContext was built from. Null if this FormContext was constructed without a request, for example from explicitly supplied ReportParams. |
| rollback | boolean | Whether the transaction processing this form submission should be rolled back. False by default; a controller sets it via setRollback when it determines the submission should not be persisted. |
Methods
newValidationContext() · newValidationContext(boolean strictMode) · newFormContext(Map<String,String> params) · excludeBySuffix(String suffix) · excludeByPrefix(String prefix) · excludeByContains(String contains) · typedParam(String name, String type) · typedParam(String name, String type, boolean strictMode) · exclude(String names) · subContext(String prefix) · getParameters() · getFiles() · getRequest() · isRollback() · setRollback(boolean rollback) · listParam(String paramName) · setParam(String paramName) · csvParam(String paramName) · listLongsParam(String paramName) · cleanedParam(String paramName) · cleanedParam(String paramName, Boolean strictMode) · rawParam(String paramName) · dateParam(String paramName) · integerParam(String paramName) · longParam(String paramName) · bigDecimalParam(String paramName) · doubleParam(String paramName) · booleanParam(String paramName) · booleanParam(String paramName, boolean defaultVal) · getCurrentUser() · parseList(String indicatorParamPrefix) · findMapFromSuffix(String suffix) · findMapFromPrefix(String prefix) · databind(Object ob, DataBinderField fields) · databind(Object ob, boolean isTrusted, DataBinderField fields) · databind(Object ob, TrustType trustType, DataBinderField fields) · databind(Object ob, String prefix) · hasParamsWithPrefix(String prefix) · paramsWithPreffix(String prefix) · paramsWithPreffix(String prefix, boolean removePrefix) · containsParam(String name) · hasValue(String paramName) · parseTerms() · toQueryParams() · toCleanedMap()
newValidationContext()
Returns: ValidationContext
Creates a new ValidationContext bound to this FormContext's parameters, with strictMode set to false so some HTML tags are still allowed through. Use this to validate a set of named parameters and build a JsonResult describing any validation failures.
newValidationContext(boolean strictMode)
Returns: ValidationContext
Creates a new ValidationContext bound to this FormContext's parameters, with the given strictMode. If false, some HTML tags are still allowed through string values. Use this to validate a set of named parameters and build a JsonResult describing any validation failures.
| Parameter | Description |
|---|---|
strictMode | true to escape HTML entities in cleaned string values, false to allow some tags |
newFormContext(Map<String,String> params)
Returns: FormContext
Creates a new FormContext which starts as a copy of this one's parameters, with the given params added on top, overwriting any existing params with the same key. The session, files and request references are carried over unchanged.
| Parameter | Description |
|---|---|
params | extra params to add, or overwrite, on top of this FormContext's own params; may be null |
excludeBySuffix(String suffix)
Returns: FormContext
Returns a new FormContext containing only the parameters of this one whose name does not end with the given suffix. The session, files and request references are carried over unchanged.
| Parameter | Description |
|---|---|
suffix | the suffix to exclude parameter names by |
excludeByPrefix(String prefix)
Returns: FormContext
Returns a new FormContext containing only the parameters of this one whose name does not start with the given prefix. The session, files and request references are carried over unchanged.
| Parameter | Description |
|---|---|
prefix | the prefix to exclude parameter names by |
excludeByContains(String contains)
Returns: FormContext
Returns a new FormContext containing only the parameters of this one whose name does not contain the given string. The session, files and request references are carried over unchanged.
| Parameter | Description |
|---|---|
contains | the substring to exclude parameter names by |
typedParam(String name, String type)
Returns: Object
Returns the named parameter converted to the type named by the type argument, using strictMode=false. Supported type names are the TYPE_* constants: string, long, integer, date, boolean, double, bigdecimal, list, listLongs and raw_string.
| Parameter | Description |
|---|---|
name | the parameter name to look up |
type | one of the TYPE_* constant values naming the conversion to apply |
typedParam(String name, String type, boolean strictMode)
Returns: Object
Returns the named parameter converted to the type named by the type argument, honouring strictMode for string conversions. Supported type names are the TYPE_* constants: string, long, integer, date, boolean, double, bigdecimal, list, listLongs and raw_string.
| Parameter | Description |
|---|---|
name | the parameter name to look up |
type | one of the TYPE_* constant values naming the conversion to apply |
strictMode | when converting to a string, true to escape HTML entities in the cleaned value |
exclude(String names)
Returns: FormContext
Creates a copy of this FormContext, but with the listed param names excluded. The session, files and request references are carried over unchanged.
| Parameter | Description |
|---|---|
names | the exact parameter names to exclude |
subContext(String prefix)
Returns: FormContext
Creates a new FormContext containing only the parameters of this one whose name starts with the given prefix, with the prefix stripped from each retained parameter's name. Useful for splitting a single form post into logically separate groups of fields sharing a common prefix.
| Parameter | Description |
|---|---|
prefix | the prefix identifying which parameters to keep, and to strip from their names |
getParameters()
Returns: Map<String,String>
Returns this FormContext's parameters as a map of name to string value, converting any non-string (typed) parameter values to their string form. Values are not cleaned or sanitised.
getFiles()
Returns: Map<String,FileItem>
The uploaded files of this form submission, keyed by their form field name. Null if this FormContext was not created from an HTTP request carrying file uploads.
getRequest()
Returns: Request
The underlying Milton HTTP request this FormContext was built from. Null if this FormContext was constructed without a request, for example from explicitly supplied ReportParams.
isRollback()
Returns: boolean
Whether the transaction processing this form submission should be rolled back. False by default; a controller sets it via setRollback when it determines the submission should not be persisted.
setRollback(boolean rollback)
Returns: void
Flags whether the transaction processing this form submission should be rolled back rather than committed.
| Parameter | Description |
|---|---|
rollback | true to request that the current transaction be rolled back |
listParam(String paramName)
Returns: List<String>
Returns the named parameter's value split into a cleaned list of strings, supporting both a comma-separated single value and jQuery-style "name[]" array submission.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
setParam(String paramName)
Returns: Set<String>
Returns the named parameter's value split into a set of cleaned strings, with duplicates removed but insertion order preserved.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
csvParam(String paramName)
Returns: List<String[]>
Parses the named parameter's raw value as CSV text and returns the cleaned rows, each row as an array of column values.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
listLongsParam(String paramName)
Returns: List<Long>
Returns the named parameter's value split and parsed into a list of Longs, supporting both a comma-separated single value and jQuery-style "name[]" array submission.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
cleanedParam(String paramName)
Returns: String
Returns the named parameter's value, trimmed and with disallowed HTML content stripped, in non-strict mode. Returns null if the parameter is absent or its trimmed value is empty.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
cleanedParam(String paramName, Boolean strictMode)
Returns: String
Returns the named parameter's value, trimmed and with disallowed HTML content stripped. If strictMode is true, any remaining HTML entities in the cleaned value are also escaped. Returns null if the parameter is absent or its trimmed value is empty.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
strictMode | true to escape HTML entities in the cleaned value, false or null to leave them as is |
rawParam(String paramName)
Returns: String
Returns the named parameter's value trimmed, but without any HTML cleaning or sanitisation applied. Returns null if the parameter is absent or its trimmed value is empty. Prefer cleanedParam for values that will be stored or displayed; use this only where the raw, unsanitised value is genuinely needed.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
dateParam(String paramName)
Returns: Date
Parses the named parameter's value as a Date.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
integerParam(String paramName)
Returns: Integer
Safely attempts to parse the named parameter's value as an Integer. Returns null if the parameter does not exist, is blank, or is not a valid integer value.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
longParam(String paramName)
Returns: Long
Safely attempts to parse the named parameter's value as a Long. Returns null if the parameter does not exist, is blank, or is not an integer value.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
bigDecimalParam(String paramName)
Returns: BigDecimal
Safely attempts to parse the named parameter's value as a BigDecimal. Returns null if the parameter does not exist, is blank, or is not a valid decimal value.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
doubleParam(String paramName)
Returns: Double
Safely attempts to parse the named parameter's value as a Double. Returns null if the parameter does not exist, is blank, or is not a valid decimal value.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
booleanParam(String paramName)
Returns: Boolean
Parses the named parameter's value as a Boolean.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
booleanParam(String paramName, boolean defaultVal)
Returns: Boolean
Parses the named parameter's value as a Boolean, falling back to the given default when the parameter is not present or not a recognised boolean value.
| Parameter | Description |
|---|---|
paramName | the parameter name to look up |
defaultVal | the value to return if the parameter is missing or unparsable |
getCurrentUser()
Returns: Profile
The profile of the currently authenticated user for the request this form was submitted in.
parseList(String indicatorParamPrefix)
Returns: List<Map<String,String>>
Builds a list of field maps from repeating groups of parameters that share a common numeric suffix, for example "target.1", "target.2" and "rules.1", "rules.2" submitted together as row 1 and row 2 of a repeating form section. For each parameter name starting with indicatorParamPrefix, its trailing suffix (the part after the prefix) is used to collect all other parameters sharing that same suffix into one map, via findMapFromSuffix.
| Parameter | Description |
|---|---|
indicatorParamPrefix | the prefix identifying which parameter names mark a row, e.g. "target." |
findMapFromSuffix(String suffix)
Returns: Map<String,String>
Builds a map from every parameter whose name ends with the given suffix, keyed by the part of the name before the suffix, with the value converted to a string.
| Parameter | Description |
|---|---|
suffix | the suffix identifying which parameters to include |
findMapFromPrefix(String prefix)
Returns: Map<String,String>
Builds a map from every parameter whose name starts with the given prefix, keyed by the part of the name after the prefix, with the value converted to a string.
| Parameter | Description |
|---|---|
prefix | the prefix identifying which parameters to include |
databind(Object ob, DataBinderField fields)
Returns: void
Populates the given object's properties from this FormContext's parameters, using the normal trust type, optionally restricted to the given fields.
| Parameter | Description |
|---|---|
ob | the object whose properties are to be populated from the form parameters |
fields | the specific fields to bind, or none to bind all matching properties |
databind(Object ob, boolean isTrusted, DataBinderField fields)
Returns: void
Populates the given object's properties from this FormContext's parameters, optionally restricted to the given fields. When isTrusted is true, binding uses the more permissive LAX trust type; otherwise the NORMAL trust type is used.
| Parameter | Description |
|---|---|
ob | the object whose properties are to be populated from the form parameters |
isTrusted | true to bind using the LAX trust type, false to use the NORMAL trust type |
fields | the specific fields to bind, or none to bind all matching properties |
databind(Object ob, TrustType trustType, DataBinderField fields)
Returns: void
Populates the given object's properties from this FormContext's parameters using the given trust type, optionally restricted to the given fields.
| Parameter | Description |
|---|---|
ob | the object whose properties are to be populated from the form parameters |
trustType | the DataBinder trust type controlling how strictly values are validated while binding |
fields | the specific fields to bind, or none to bind all matching properties |
databind(Object ob, String prefix)
Returns: void
Populates the given object's properties from the subset of this FormContext's parameters whose name starts with prefix followed by a dot, using the part of each name after "prefix." as the property name.
| Parameter | Description |
|---|---|
ob | the object whose properties are to be populated from the matching form parameters |
prefix | the prefix (without the trailing dot) identifying which parameters to bind |
hasParamsWithPrefix(String prefix)
Returns: boolean
Returns true if any parameter of this FormContext has a name starting with the given prefix.
| Parameter | Description |
|---|---|
prefix | the prefix to check parameter names against |
paramsWithPreffix(String prefix)
Returns: Map<String,String>
Returns the cleaned values of every parameter whose name starts with the given prefix, keyed by the full parameter name.
| Parameter | Description |
|---|---|
prefix | the prefix identifying which parameters to include |
paramsWithPreffix(String prefix, boolean removePrefix)
Returns: Map<String,String>
Returns the cleaned values of every parameter whose name starts with the given prefix, optionally with the prefix stripped from the returned keys.
| Parameter | Description |
|---|---|
prefix | the prefix identifying which parameters to include |
removePrefix | true to key the result by the parameter name with the prefix stripped, false to key it by the full parameter name |
containsParam(String name)
Returns: boolean
Returns true if the parameter name is present in the request, regardless of whether it has a value or not. Also matches the checkbox indicator parameter form, e.g. "myinput_checkbox" for a field named "myinput".
| Parameter | Description |
|---|---|
name | the parameter name to check for |
hasValue(String paramName)
Returns: boolean
Returns true if the specified parameter is present and has a non-blank value.
| Parameter | Description |
|---|---|
paramName | the parameter name to check |
parseTerms()
Returns: Map<String,List<String>>
Parses this FormContext's parameters as search terms, grouping recognised term values by their search field name. See SearchUtils.parseTerms for the term syntax.
toQueryParams()
Returns: String
Renders this FormContext's parameters back out as a URL query string, with each value cleaned and percent-encoded.
toCleanedMap()
Returns: Map<String,String>
Returns a copy of this FormContext's parameters as a map of cleaned string values, with each parameter name also passed through the same cleaning as its value.
© 2025 Kademi Ltd