org.omnifaces.cdi
Annotation Type Param

@Qualifier
@Retention(value=RUNTIME)
@Target(value={TYPE,METHOD,FIELD,PARAMETER})
public @interface Param

Specifies a request parameter that is to be injected into a managed bean within a JSF context, with full support for a converter and one or more validators. Converters and validators can optionally have attributes.

By default the name of the request parameter is taken from the name of the variable into which injection takes place. It can be optionally specified.

String values can be injected without a converter, other types need a converter.

Injection should be into a field of type ParamValue, with V the actual type of the (converted) request parameter.

The following is an example of the injection of a request parameter user following a request such as http://example.com/mypage?user=100:

 @Inject @Param(
        converter="#{userconverter}"
        validator="#{priviledgedUser}"*
 )
 private ParamValue<User> user;
 

If conversion or validation fails, a ParamValue is injected, but it will contain a null value. The conversion and validation messages (if any) will be set in the JSF context then, and FacesContext.isValidationFailed() will return true;

Since:

1.6

Author:

Arjan Tijms

Optional Element Summary

java.lang.String	converter (Optional/Required) The converter to be used for converting the request parameter to the type that is to be injected.
Attribute[]	converterAttributes (Optional) Attributes that will be set on the converter instance obtained from converter() or converterClass().
java.lang.Class<? extends javax.faces.convert.Converter>	converterClass (Optional) Class of the converter to be used for converting the request parameter to the type that is to be injected.
java.lang.String	converterMessage (Optional) A message that will be used if conversion fails instead of the message set by the converter.
boolean	disableBeanValidation (Optional) Flag that disables bean validation for this instance.
java.lang.String	label (Optional) the label used to refer to the request parameter.
java.lang.String	name (Optional) The name of the request parameter.
boolean	overrideGlobalBeanValidationDisabled (Optional) Flag that overrides the global BeanValidator.DISABLE_DEFAULT_BEAN_VALIDATOR_PARAM_NAME setting.
boolean	required (Optional) Flag indicating if this request parameter is required (must be present) or not.
java.lang.String	requiredMessage (Optional) A message that will be used if a non-empty value is submitted instead of the default message associated with the RequiredValidator.
Attribute[]	validatorAttributes (Optional) Attributes that will be set on each of the validator instances obtained from validators()() and validatorClasses()().
java.lang.Class<? extends javax.faces.validator.Validator>[]	validatorClasses (Optional) Class of one ore more validators to be used for validating the (converted) request parameter.
java.lang.String	validatorMessage (Optional) A message that will be used if validation fails instead of the message set by the validator(s).
java.lang.String[]	validators (Optional) The validators to be used for validating the (converted) request parameter.

name

public abstract java.lang.String name

(Optional) The name of the request parameter. If not specified the name of the injection target field will be used.

Default:

""

label

public abstract java.lang.String label

(Optional) the label used to refer to the request parameter. If not specified the name of the request parameter.

Default:

""

converter

public abstract java.lang.String converter

(Optional/Required) The converter to be used for converting the request parameter to the type that is to be injected. Optional if the target type is String, otherwise required.

A converter can be specified in 3 ways:

1. A string value representing the converter-id as used by Application.createConverter(String)
2. An EL expression that resolves to a String representing the converter-id
3. An EL expression that resolves to a Converter instance.

If this attribute is specified in addition to converterClass(), this attribute takes precedence.

Default:

""

required

public abstract boolean required

(Optional) Flag indicating if this request parameter is required (must be present) or not. The required check is done after conversion and before validation. A value is said to be not present if it turns out to be empty according to the semantics of Utils.isEmpty(Object).

Default:

false

validators

public abstract java.lang.String[] validators

(Optional) The validators to be used for validating the (converted) request parameter.

A validator can be specified in 3 ways:

1. A string value representing the validator-id as used by Application.createValidator(String)
2. An EL expression that resolves to a String representing the validator-id
3. An EL expression that resolves to a Validator instance.

If this attribute is specified in addition to validatorClasses() then the validators from both attributes will be added to the final collection of validators. The validators from this attribute will however be called first.

Default:

{}

converterClass

public abstract java.lang.Class<? extends javax.faces.convert.Converter> converterClass

(Optional) Class of the converter to be used for converting the request parameter to the type that is to be injected.

Default:

javax.faces.convert.Converter.class

validatorClasses

public abstract java.lang.Class<? extends javax.faces.validator.Validator>[] validatorClasses

(Optional) Class of one ore more validators to be used for validating the (converted) request parameter.

Default:

{}

converterAttributes

public abstract Attribute[] converterAttributes

(Optional) Attributes that will be set on the converter instance obtained from converter() or converterClass().

For each attribute the converter instance should have a writable JavaBeans property with the same name. The value can be a string literal or an EL expression. String literals are coerced if necessary if there's a PropertyEditor available (the JDK provides these for the primitive types and their corresponding boxed types).

Attributes for which the converter doesn't have a property (setter) are silently ignored.

Default:

{}

validatorAttributes

public abstract Attribute[] validatorAttributes

(Optional) Attributes that will be set on each of the validator instances obtained from validators()() and validatorClasses()().

For each attribute the validator instances should have a writable JavaBeans property with the same name. The value can be a string literal or an EL expression. String literals are coerced if necessary if there's a PropertyEditor available (the JDK provides these for the primitive types and their corresponding boxed types).

Attributes for which any given validator doesn't have a property (setter) are silently ignored.

Default:

{}

converterMessage

public abstract java.lang.String converterMessage

(Optional) A message that will be used if conversion fails instead of the message set by the converter.

The value for which conversion failed is available as {0}. The label associated with this parameter value (see the label() attribute) is available as {1}.

Default:

""

validatorMessage

public abstract java.lang.String validatorMessage

(Optional) A message that will be used if validation fails instead of the message set by the validator(s).

The value for which validation failed is available as {0}. The label associated with this parameter value (see the label() attribute) is available as {1}.

Default:

""

requiredMessage

public abstract java.lang.String requiredMessage

(Optional) A message that will be used if a non-empty value is submitted instead of the default message associated with the RequiredValidator.

The (empty) value for which the required check failed is available as {0}. (this will be either null or the empty string) The label associated with this parameter value (see the label() attribute) is available as {1}.

Default:

""

disableBeanValidation

public abstract boolean disableBeanValidation

(Optional) Flag that disables bean validation for this instance.

NOTE: bean validation at the moment (OmniFaces 1.6) is done against the ParamValue that is injected. In many cases this will be of limited use. We hope to directly inject the converted type in OmniFaces 1.7 and then bean validation will make more sense.

If true no bean validation will be attempted. If false (the default) no specific action is taken, and it will depend on the availability of bean validation and the global BeanValidator.DISABLE_DEFAULT_BEAN_VALIDATOR_PARAM_NAME setting whether bean validation is attempted or not.

Default:

false

overrideGlobalBeanValidationDisabled

public abstract boolean overrideGlobalBeanValidationDisabled

(Optional) Flag that overrides the global BeanValidator.DISABLE_DEFAULT_BEAN_VALIDATOR_PARAM_NAME setting.

If true bean validation will be performed for this instance (given that bean validation is available) despite it globally being disabled. If false (the default) no specific action is taken.

Default:

false