org.apache.turbine.services.intake.model
Class Field

java.lang.Object
  org.apache.turbine.services.intake.model.Field

Direct Known Subclasses:

BigDecimalField, BooleanField, ComboKeyField, DateStringField, DoubleField, FileItemField, FloatField, IntegerField, LongField, NumberKeyField, ShortField, StringField, StringKeyField

public abstract class Field

extends java.lang.Object

Base class for Intake generated input processing classes.

Version:

$Id: Field.java 645969 2008-04-08 15:12:38Z tv $

Author:

John McNally, Henning P. Schmiedehausen, Quinton McCombs, Jürgen Hoffmann, Thomas Vandahl

Field Summary

protected boolean	alwaysRequired Is this field always required?
static java.lang.String	defaultFieldPackage Default Field Package
static java.lang.String	defaultValidatorPackage Default Validator Package
protected java.lang.Object	defaultValue Default value of the field
protected java.lang.String	displayName Display name of the field to be used on data entry forms...
protected java.lang.Object	emptyValue Value of the field to use if the mapped parameter is empty or non-existant
protected java.lang.reflect.Method	getter Getter method in the mapped object used to populate the field
protected Group	group Group to which the field belongs
protected java.lang.String	ifRequiredMessage Error message set on the field if required and not set by parser
protected boolean	initialized Has the field has been set from the parser?
protected boolean	isDebugEnabled
protected boolean	isMultiValued Does this field accept multiple values?
protected java.lang.String	key Key used to identify the field in the parser
protected org.apache.commons.logging.Log	log Logging
protected java.lang.String	mapToObject Class name of the object to which the field is mapped
protected java.lang.String	message Error message, is any, resulting from validation
protected java.lang.String	name Name of the field.
protected java.lang.Object	onError Value of the field if an error occurs while getting the value from the mapped object
protected ValueParser	parser The object containing the field data.
protected boolean	required Does the field require a value?
protected Retrievable	retrievable Mapped object used to set the initial field value
protected boolean	setFlag Has the field has been set from the parser?
protected java.lang.reflect.Method	setter Setter method in the mapped object used to store the value of field
protected boolean	validated Has the field been validated?
protected Validator	validator Used to validate the contents of the field
protected boolean	validFlag Has the field passed the validation test?

Constructor Summary

Field(XmlField field, Group group)
Constructs a field based on data in the xml specification and assigns it to a Group.

Method Summary

void	dispose() Disposes the object after use.
protected abstract void	doSetValue() Sets the value of the field from data in the parser.
protected void	doSetValue(ValueParser pp) Deprecated. Use doSetValue() instead (with no parameters).
void	getDefault() Loads the default value from the object
protected java.lang.String	getDefaultValidator() Produces the fully qualified class name of the default validator.
java.lang.Object	getDefaultValue() Get the default Value
java.lang.String	getDisplayName() Get the display name of the field.
java.lang.String	getDisplaySize() Gets the diplay size of the field.
java.lang.Object	getEmptyValue() Get the Value to use if the field is empty
Group	getGroup() Returns the Group this field belongs to or null if unknown.
java.lang.String	getHTMLString() Calls toString() on the object returned by getValue(), unless null; and then it returns "", the empty String.
java.lang.Object	getInitialValue() Get the value used as a default.
java.lang.String	getKey() Get the key used to identify the field.
java.util.Locale	getLocale() Returns the Locale used when localizing data for this field, or null if unknown.
java.lang.String	getMaxSize() Gets the maximum size of the field.
java.lang.String	getMessage() Get any error message resulting from invalid input.
java.lang.String	getName() Gets the name of the field.
void	getProperty(java.lang.Object obj) Loads the valid value from a bean
protected java.lang.Object	getSafeEmptyValue() Provides access to emptyValue such that the value returned will be acceptable as an argument parameter to Method.invoke.
java.lang.String	getStringValue() Gets the String representation of the Value.
java.lang.Object	getTestValue() Get the value input by a user that will be validated.
Validator	getValidator() Gets the Validator object for this field.
java.lang.Object	getValue() Get the value of the field.
java.lang.String	getValueIfAbsent() Use in a hidden field assign a default value in the event the field is absent from the query parameters.
Field	init(Retrievable obj) Method called when this field or the group it belongs to is pulled from the pool.
Field	init(ValueParser pp) Method called when this field (the group it belongs to) is pulled from the pool.
boolean	isMultiValued() Flag to determine whether the field has been declared as multi-valued.
boolean	isRequired() Flag to determine whether the field has been declared as required.
boolean	isSet() Flag set to true, if the test value has been set by the parser (even to an empty value, so don't used this to determine if the field contains a non-empty value).
boolean	isValid() Flag set to true, if the test value met the constraints.
boolean	isValidated() Flag to determine whether the field has been validated.
void	removeFromRequest() Removes references to this group and its fields from the query parameters
abstract void	setDefaultValue(java.lang.String prop) Set the default Value.
void	setDisplayName(java.lang.String newDisplayName) Set the display name of the field.
abstract void	setEmptyValue(java.lang.String prop) Set the empty Value.
void	setMessage(java.lang.String message) Sets an error message.
void	setProperty(java.lang.Object obj) Calls a setter method on obj, if this field has been set.
void	setRequired(boolean v) Set whether this field is required to have a value.
void	setRequired(boolean v, java.lang.String message) Set the value of required.
java.lang.String	toString() Calls toString() on the object returned by getValue(), unless null; and then it returns "", the empty String.
boolean	validate() Compares request data with constraints and sets the valid flag.
protected boolean	validate(ValueParser pp) Deprecated. Call validate() instead (with no parameters).

Methods inherited from class java.lang.Object

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

Field Detail

defaultValidatorPackage

public static final java.lang.String defaultValidatorPackage

Default Validator Package

See Also:

Constant Field Values

defaultFieldPackage

public static final java.lang.String defaultFieldPackage

Default Field Package

See Also:

Constant Field Values

name

protected final java.lang.String name

Name of the field.

key

protected final java.lang.String key

Key used to identify the field in the parser

displayName

protected java.lang.String displayName

Display name of the field to be used on data entry forms...

mapToObject

protected final java.lang.String mapToObject

Class name of the object to which the field is mapped

validator

protected Validator validator

Used to validate the contents of the field

getter

protected final java.lang.reflect.Method getter

Getter method in the mapped object used to populate the field

setter

protected final java.lang.reflect.Method setter

Setter method in the mapped object used to store the value of field

ifRequiredMessage

protected java.lang.String ifRequiredMessage

Error message set on the field if required and not set by parser

isMultiValued

protected final boolean isMultiValued

Does this field accept multiple values?

group

protected final Group group

Group to which the field belongs

alwaysRequired

protected boolean alwaysRequired

Is this field always required? This is only set through the XML file

onError

protected java.lang.Object onError

Value of the field if an error occurs while getting the value from the mapped object

defaultValue

protected java.lang.Object defaultValue

Default value of the field

emptyValue

protected java.lang.Object emptyValue

Value of the field to use if the mapped parameter is empty or non-existant

setFlag

protected boolean setFlag

Has the field has been set from the parser?

validFlag

protected boolean validFlag

Has the field passed the validation test?

validated

protected boolean validated

Has the field been validated?

required

protected boolean required

Does the field require a value?

initialized

protected boolean initialized

Has the field has been set from the parser?

message

protected java.lang.String message

Error message, is any, resulting from validation

retrievable

protected Retrievable retrievable

Mapped object used to set the initial field value

parser

protected ValueParser parser

The object containing the field data.

log

protected org.apache.commons.logging.Log log

Logging

isDebugEnabled

protected boolean isDebugEnabled

Constructor Detail

Field

public Field(XmlField field,
             Group group)
      throws IntakeException

Constructs a field based on data in the xml specification and assigns it to a Group.

Parameters:

field - a XmlField value

group - a Group value

Throws:

IntakeException - indicates the validator was not valid or could not be loaded.

SystemError - only occurs is the Validation object does not extend InitableByConstraintMap

Method Detail

init

public Field init(ValueParser pp)
           throws IntakeException

Method called when this field (the group it belongs to) is pulled from the pool. The request data is searched to determine if a value has been supplied for this field. If so, the value is validated.

Parameters:

pp - a ValueParser value

Returns:

a Field value

Throws:

IntakeException - this exception is only thrown by subclasses overriding this implementation.

init

public Field init(Retrievable obj)

Method called when this field or the group it belongs to is pulled from the pool. The retrievable object can provide a default value for the field, or using setProperty the field's value can be transferred to the retrievable.

Parameters:

obj - a Retrievable value

Returns:

a Field value

getGroup

public Group getGroup()

Returns the Group this field belongs to or null if unknown.

Returns:

The group this field belongs to.

getLocale

public java.util.Locale getLocale()

Returns the Locale used when localizing data for this field, or null if unknown.

Returns:

Where to localize for.

getDefaultValidator

protected java.lang.String getDefaultValidator()

Produces the fully qualified class name of the default validator.

Returns:

class name of the default validator

getValidator

public Validator getValidator()

Gets the Validator object for this field.

Returns:

a Validator object

isMultiValued

public boolean isMultiValued()

Flag to determine whether the field has been declared as multi-valued.

Returns:

value of isMultiValued.

isRequired

public boolean isRequired()

Flag to determine whether the field has been declared as required.

Returns:

value of required.

setRequired

public void setRequired(boolean v)

Set whether this field is required to have a value. If the field is already required due to a setting in the XML file, this method can not set it to false.

Parameters:

v - Value to assign to required.

setRequired

public void setRequired(boolean v,
                        java.lang.String message)

Set the value of required.

Parameters:

v - a boolean value

message - override the value from intake.xml

removeFromRequest

public void removeFromRequest()

Removes references to this group and its fields from the query parameters

dispose

public void dispose()

Disposes the object after use. The method is called when the Group is returned to its pool. if overridden, super.dispose() should be called.

getKey

public java.lang.String getKey()

Get the key used to identify the field.

Returns:

the query data key.

getValueIfAbsent

public java.lang.String getValueIfAbsent()

Use in a hidden field assign a default value in the event the field is absent from the query parameters. Used to track checkboxes, since they only show up if checked.

isValid

public boolean isValid()

Flag set to true, if the test value met the constraints. Is also true, in the case the test value was not set, unless this field has been marked as required.

Returns:

a boolean value

isValidated

public boolean isValidated()

Flag to determine whether the field has been validated.

Returns:

value of validated.

isSet

public boolean isSet()

Flag set to true, if the test value has been set by the parser (even to an empty value, so don't used this to determine if the field contains a non-empty value). Validation will only be executed for fields that have been set in this manner.

Returns:

a boolean value

getDisplayName

public java.lang.String getDisplayName()

Get the display name of the field. Useful for building data entry forms. Returns name of field if no display name has been assigned to the field by xml input file.

Returns:

a String value

setDisplayName

public void setDisplayName(java.lang.String newDisplayName)

Set the display name of the field. Display names are used in building data entry forms and serve as a user friendly description of the data contained in the field.

getMessage

public java.lang.String getMessage()

Get any error message resulting from invalid input.

Returns:

a String value

setMessage

public void setMessage(java.lang.String message)

Sets an error message. The field is also marked as invalid.

validate

protected boolean validate(ValueParser pp)

Deprecated. Call validate() instead (with no parameters).

validate

public boolean validate()

Compares request data with constraints and sets the valid flag.

setDefaultValue

public abstract void setDefaultValue(java.lang.String prop)

Set the default Value. This value is used if Intake should map this field to a new object.

Parameters:

prop - The value to use if the field is mapped to a new object.

setEmptyValue

public abstract void setEmptyValue(java.lang.String prop)

Set the empty Value. This value is used if Intake maps a field to a parameter returned by the user and the corresponding field is either empty (empty string) or non-existant.

Parameters:

prop - The value to use if the field is empty.

doSetValue

protected void doSetValue(ValueParser pp)

Deprecated. Use doSetValue() instead (with no parameters).

doSetValue

protected abstract void doSetValue()

Sets the value of the field from data in the parser.

getInitialValue

public java.lang.Object getInitialValue()
                                 throws IntakeException

Get the value used as a default. If the initial value has not been set and a Retrievable object has been associated with this field, the objects property will be used as the initial value.

Returns:

an Object value

Throws:

IntakeException - indicates the value could not be returned from the mapped object

getTestValue

public java.lang.Object getTestValue()

Get the value input by a user that will be validated.

Returns:

an Object value

getValue

public java.lang.Object getValue()

Get the value of the field. if a test value has been set, it will be returned as is, unless it is so badly formed that the validation could not parse it. In most cases the test value is returned even though invalid, so that it can be returned to the user to make modifications. If the test value is not set the initial value is returned.

Returns:

an Object value

toString

public java.lang.String toString()

Calls toString() on the object returned by getValue(), unless null; and then it returns "", the empty String.

Returns:

a String value

getHTMLString

public java.lang.String getHTMLString()

Calls toString() on the object returned by getValue(), unless null; and then it returns "", the empty String. Escapes " characters to be able to display these in HTML form fields.

Returns:

a String value

getProperty

public void getProperty(java.lang.Object obj)
                 throws IntakeException

Loads the valid value from a bean

Throws:

IntakeException - indicates a problem during the execution of the object's getter method

getDefault

public void getDefault()

Loads the default value from the object

setProperty

public void setProperty(java.lang.Object obj)
                 throws IntakeException

Calls a setter method on obj, if this field has been set.

Throws:

IntakeException - indicates a problem during the execution of the object's setter method

getDefaultValue

public java.lang.Object getDefaultValue()

Get the default Value

Returns:

the default value

getEmptyValue

public java.lang.Object getEmptyValue()

Get the Value to use if the field is empty

Returns:

the value to use if the field is empty.

getSafeEmptyValue

protected java.lang.Object getSafeEmptyValue()

Provides access to emptyValue such that the value returned will be acceptable as an argument parameter to Method.invoke. Subclasses that deal with primitive types should ensure that they return an appropriate value wrapped in the object wrapper class for the primitive type.

Returns:

the value to use when the field is empty or an Object that wraps the empty value for primitive types.

getName

public java.lang.String getName()

Gets the name of the field.

Returns:

name of the field as specified in the XML file.

getDisplaySize

public java.lang.String getDisplaySize()

Gets the diplay size of the field. This is useful when building the HTML input tag. If no displaySize was set, an empty string is returned.

getMaxSize

public java.lang.String getMaxSize()

Gets the maximum size of the field. This is useful when building the HTML input tag. The maxSize is set with the maxLength rule. If this rul was not set, an enmpty string is returned.

getStringValue

public java.lang.String getStringValue()

Gets the String representation of the Value. This is basically a wrapper method for the toString method which doesn't seem to show anything on screen if accessed from Template. Name is also more in line with getValue method which returns the actual Object. This is useful for displaying correctly formatted data such as dates, such as 18/11/1968 instead of the toString dump of a Date Object.

Returns:

the String Value