org.apache.commons.validator

Class Field

public class Field extends Object implements Cloneable, Serializable

This contains the list of pluggable validators to run on a field and any message information and variables to perform the validations and generate error messages. Instances of this class are configured with a <field> xml element.

The use of FastHashMap is deprecated and will be replaced in a future release.

Version: $Revision: 478334 $ $Date: 2006-11-22 21:31:54 +0000 (Wed, 22 Nov 2006) $

See Also: Form

Field Summary
protected Map[]	args Holds Maps of arguments. args[0] returns the Map for the first replacement argument.
List	dependencyList Internal representation of this.depends String as a List.
protected String	depends A comma separated list of validator's this field depends on.
static String	DEFAULT_ARG This is the value that will be used as a key if the `Arg` name field has no value.
protected int	fieldOrder The order of the Field in the Form.
protected FastHashMap	hMsgs
protected FastHashMap	hVars
protected String	indexedListProperty The Field's indexed list property name.
protected String	indexedProperty The Field's indexed property name.
protected String	key The Field's unique key.
protected int	page The Page Number
protected String	property The Field's property name.
protected static String	TOKEN_END The end of a token.
static String	TOKEN_INDEXED This indicates an indexed property is being referenced.
protected static String	TOKEN_START The start of a token.
protected static String	TOKEN_VAR A Vriable token.

Method Summary
void	addArg(Arg arg) Add an `Arg` to the replacement argument list.
void	addMsg(Msg msg) Add a `Msg` to the `Field`.
void	addVar(Var v) Add a `Var` to the `Field`.
void	addVar(String name, String value, String jsType) Add a `Var`, based on the values passed in, to the `Field`.
Object	clone() Creates and returns a copy of this object.
void	determineArgPosition(Arg arg) Calculate the position of the Arg
void	ensureArgsCapacity(Arg arg) Ensures that the args array can hold the given arg.
void	generateKey() Generate correct `key` value.
Arg	getArg(int position) Gets the default `Arg` object at the given position.
Arg	getArg(String key, int position) Gets the `Arg` object at the given position.
Arg[]	getArgs(String key) Retrieves the Args for the given validator name.
List	getDependencyList() Gets an unmodifiable `List` of the dependencies in the same order they were defined in parameter passed to the setDepends() method.
String	getDepends() Gets the validation rules for this field as a comma separated list.
int	getFieldOrder() Gets the position of the `Field` in the validation list.
String	getIndexedListProperty() Gets the indexed property name of the field.
String	getIndexedProperty() Gets the indexed property name of the field.
Object[]	getIndexedProperty(Object bean) Returns an indexed property from the object we're validating.
int	getIndexedPropertySize(Object bean) Returns the size of an indexed property from the object we're validating.
String	getKey() Gets a unique key based on the property and indexedProperty fields.
Msg	getMessage(String key) Retrieve a message object.
Map	getMessages() The `Field`'s messages are returned as an unmodifiable `Map`.
String	getMsg(String key) Retrieve a message value.
protected Map	getMsgMap() Returns a Map of String Msg names to Msg objects.
int	getPage() Gets the page value that the Field is associated with for validation.
String	getProperty() Gets the property name of the field.
Var	getVar(String mainKey) Retrieve a variable.
protected Map	getVarMap() Returns a Map of String Var names to Var objects.
Map	getVars() The `Field`'s variables are returned as an unmodifiable `Map`.
String	getVarValue(String mainKey) Retrieve a variable's value.
void	handleMissingAction(String name) Called when a validator name is used in a depends clause but there is no know ValidatorAction configured for that name.
boolean	isDependency(String validatorName) Checks if the validator is listed as a dependency.
boolean	isIndexed() If there is a value specified for the indexedProperty field then `true` will be returned.
void	process(Map globalConstants, Map constants) Replace constants with values in fields and process the depends field to create the dependency `Map`.
void	processArg(String key, String replaceValue) Replace the arg `Collection` key value with the key/value pairs passed in.
void	processMessageComponents(String key, String replaceValue) Replace the args key value with the key/value pairs passed in.
void	processVars(String key, String replaceValue) Replace the vars value with the key/value pairs passed in.
boolean	runDependentValidators(ValidatorAction va, ValidatorResults results, Map actions, Map params, int pos) Calls all of the validators that this validator depends on.
void	setDepends(String depends) Sets the validation rules for this field as a comma separated list.
void	setFieldOrder(int fieldOrder) Sets the position of the `Field` in the validation list.
void	setIndexedListProperty(String indexedListProperty) Sets the indexed property name of the field.
void	setIndexedProperty(String indexedProperty) Sets the indexed property name of the field.
void	setKey(String key) Sets a unique key for the field.
void	setPage(int page) Sets the page value that the Field is associated with for validation.
void	setProperty(String property) Sets the property name of the field.
String	toString() Returns a string representation of the object.
ValidatorResults	validate(Map params, Map actions) Run the configured validations on this field.
boolean	validateForRule(ValidatorAction va, ValidatorResults results, Map actions, Map params, int pos) Executes the given ValidatorAction and all ValidatorActions that it depends on.

Field Detail

args

protected Map[] args

Holds Maps of arguments. args[0] returns the Map for the first replacement argument. Start with a 0 length array so that it will only grow to the size of the highest argument position.

Since: Validator 1.1

dependencyList

private List dependencyList

Internal representation of this.depends String as a List. This List gets updated whenever setDepends() gets called. This List is synchronized so a call to setDepends() (which clears the List) won't interfere with a call to isDependency().

depends

protected String depends

A comma separated list of validator's this field depends on.

DEFAULT_ARG

private static final String DEFAULT_ARG

This is the value that will be used as a key if the Arg name field has no value.

fieldOrder

protected int fieldOrder

The order of the Field in the Form.

hMsgs

protected FastHashMap hMsgs

Deprecated: Subclasses should use getMsgMap() instead.

hVars

protected FastHashMap hVars

Deprecated: Subclasses should use getVarMap() instead.

indexedListProperty

protected String indexedListProperty

The Field's indexed list property name.

indexedProperty

protected String indexedProperty

The Field's indexed property name.

key

protected String key

The Field's unique key.

page

protected int page

The Page Number

property

protected String property

The Field's property name.

TOKEN_END

protected static final String TOKEN_END

The end of a token.

TOKEN_INDEXED

public static final String TOKEN_INDEXED

This indicates an indexed property is being referenced.

TOKEN_START

protected static final String TOKEN_START

The start of a token.

TOKEN_VAR

protected static final String TOKEN_VAR

A Vriable token.

Method Detail

addArg

public void addArg(Arg arg)

Add an Arg to the replacement argument list.

Parameters: arg Validation message's argument.

Since: Validator 1.1

addMsg

public void addMsg(Msg msg)

Add a Msg to the Field.

Parameters: msg A validation message.

addVar

public void addVar(Var v)

Add a Var to the Field.

Parameters: v The Validator Argument.

addVar

public void addVar(String name, String value, String jsType)

Add a Var, based on the values passed in, to the Field.

Parameters: name Name of the validation. value The Argument's value. jsType The Javascript type.

clone

public Object clone()

Creates and returns a copy of this object.

Returns: A copy of the Field.

determineArgPosition

private void determineArgPosition(Arg arg)

Calculate the position of the Arg

ensureArgsCapacity

private void ensureArgsCapacity(Arg arg)

Ensures that the args array can hold the given arg. Resizes the array as necessary.

Parameters: arg Determine if the args array is long enough to store this arg's position.

generateKey

public void generateKey()

Generate correct key value.

getArg

public Arg getArg(int position)

Gets the default Arg object at the given position.

Parameters: position Validation message argument's position.

Returns: The default Arg or null if not found.

Since: Validator 1.1

getArg

public Arg getArg(String key, int position)

Gets the Arg object at the given position. If the key finds a null value then the default value will be retrieved.

Parameters: key The name the Arg is stored under. If not found, the default Arg for the given position (if any) will be retrieved. position The Arg number to find.

Returns: The Arg with the given name and position or null if not found.

Since: Validator 1.1

getArgs

public Arg[] getArgs(String key)

Retrieves the Args for the given validator name.

Parameters: key The validator's args to retrieve.

Returns: An Arg[] sorted by the Args' positions (i.e. the Arg at index 0 has a position of 0).

Since: Validator 1.1.1

getDependencyList

public List getDependencyList()

Gets an unmodifiable List of the dependencies in the same order they were defined in parameter passed to the setDepends() method.

Returns: A list of the Field's dependancies.

getDepends

public String getDepends()

Gets the validation rules for this field as a comma separated list.

Returns: A comma separated list of validator names.

getFieldOrder

public int getFieldOrder()

Gets the position of the Field in the validation list.

Returns: The field position.

getIndexedListProperty

public String getIndexedListProperty()

Gets the indexed property name of the field. This is the method name that will return an array or a Collection used to retrieve the list and then loop through the list performing the specified validations.

Returns: The field's indexed List property name.

getIndexedProperty

public String getIndexedProperty()

Gets the indexed property name of the field. This is the method name that can take an int as a parameter for indexed property value retrieval.

Returns: The field's indexed property name.

getIndexedProperty

Object[] getIndexedProperty(Object bean)

Returns an indexed property from the object we're validating.

Parameters: bean The bean to extract the indexed values from.

Throws: ValidatorException If there's an error looking up the property or, the property found is not indexed.

getIndexedPropertySize

private int getIndexedPropertySize(Object bean)

Returns the size of an indexed property from the object we're validating.

Parameters: bean The bean to extract the indexed values from.

Throws: ValidatorException If there's an error looking up the property or, the property found is not indexed.

getKey

public String getKey()

Gets a unique key based on the property and indexedProperty fields.

Returns: a unique key for the field.

getMessage

public Msg getMessage(String key)

Retrieve a message object.

Parameters: key Validation key.

Returns: A validation message for a specified validator.

Since: Validator 1.1.4

getMessages

public Map getMessages()

The Field's messages are returned as an unmodifiable Map.

Returns: Map of validation messages for the field.

Since: Validator 1.1.4

getMsg

public String getMsg(String key)

Retrieve a message value.

Parameters: key Validation key.

Returns: A validation message for a specified validator.

getMsgMap

protected Map getMsgMap()

Returns a Map of String Msg names to Msg objects.

Returns: A Map of the Field's messages.

Since: Validator 1.2.0

getPage

public int getPage()

Gets the page value that the Field is associated with for validation.

Returns: The page number.

getProperty

public String getProperty()

Gets the property name of the field.

Returns: The field's property name.

getVar

public Var getVar(String mainKey)

Retrieve a variable.

Parameters: mainKey The Variable's key

Returns: the Variable

getVarMap

protected Map getVarMap()

Returns a Map of String Var names to Var objects.

Returns: A Map of the Field's variables.

Since: Validator 1.2.0

getVars

public Map getVars()

The Field's variables are returned as an unmodifiable Map.

Returns: the Map of Variable's for a Field.

getVarValue

public String getVarValue(String mainKey)

Retrieve a variable's value.

Parameters: mainKey The Variable's key

Returns: the Variable's value

handleMissingAction

private void handleMissingAction(String name)

Called when a validator name is used in a depends clause but there is no know ValidatorAction configured for that name.

Parameters: name The name of the validator in the depends list.

Throws: ValidatorException

isDependency

public boolean isDependency(String validatorName)

Checks if the validator is listed as a dependency.

Parameters: validatorName Name of the validator to check.

Returns: Whether the field is dependant on a validator.

isIndexed

public boolean isIndexed()

If there is a value specified for the indexedProperty field then true will be returned. Otherwise it will be false.

Returns: Whether the Field is indexed.

process

void process(Map globalConstants, Map constants)

Replace constants with values in fields and process the depends field to create the dependency Map.

processArg

private void processArg(String key, String replaceValue)

Replace the arg Collection key value with the key/value pairs passed in.

processMessageComponents

private void processMessageComponents(String key, String replaceValue)

Replace the args key value with the key/value pairs passed in.

processVars

private void processVars(String key, String replaceValue)

Replace the vars value with the key/value pairs passed in.

runDependentValidators

private boolean runDependentValidators(ValidatorAction va, ValidatorResults results, Map actions, Map params, int pos)

Calls all of the validators that this validator depends on. TODO ValidatorAction should know how to run its own dependencies.

Parameters: va Run dependent validators for this action. results actions pos

Returns: true if all of the dependent validations passed.

Throws: ValidatorException If there's an error running a validator

setDepends

public void setDepends(String depends)

Sets the validation rules for this field as a comma separated list.

Parameters: depends A comma separated list of validator names.

setFieldOrder

public void setFieldOrder(int fieldOrder)

Sets the position of the Field in the validation list.

Parameters: fieldOrder The field position.

setIndexedListProperty

public void setIndexedListProperty(String indexedListProperty)

Sets the indexed property name of the field.

Parameters: indexedListProperty The field's indexed List property name.

setIndexedProperty

public void setIndexedProperty(String indexedProperty)

Sets the indexed property name of the field.

Parameters: indexedProperty The field's indexed property name.

setKey

public void setKey(String key)

Sets a unique key for the field. This can be used to change the key temporarily to have a unique key for an indexed field.

Parameters: key a unique key for the field

setPage

public void setPage(int page)

Sets the page value that the Field is associated with for validation.

Parameters: page The page number.

setProperty

public void setProperty(String property)

Sets the property name of the field.

Parameters: property The field's property name.

toString

public String toString()

Returns a string representation of the object.

Returns: A string representation of the object.

validate

public ValidatorResults validate(Map params, Map actions)

Run the configured validations on this field. Run all validations in the depends clause over each item in turn, returning when the first one fails.

Parameters: params A Map of parameter class names to parameter values to pass into validation methods. actions A Map of validator names to ValidatorAction objects.

Returns: A ValidatorResults object containing validation messages for this field.

Throws: ValidatorException If an error occurs during validation.

validateForRule

private boolean validateForRule(ValidatorAction va, ValidatorResults results, Map actions, Map params, int pos)

Executes the given ValidatorAction and all ValidatorActions that it depends on.

Returns: true if the validation succeeded.