In many places, applications can use Java 5 annotations as an alternative to XML and Java properties configuration. This page serves as a reference for all annotations across the framework.

Action Annotations

Note
Since 2.1, these annotations are provided by the Convention Plugin. Codebehind and Zero Config plugins are deprecated from 2.1 on.

Action annotations are available when the framework scans the classpath for Action classes, rather than specifying individual mappings through XML configuration. See the Convention Plugin page for information on how to set up classpath scanning to allow the use of Action annotations.

Annotation	Description
Actions Annotation	Group of @Action annotations, maps multiple URLs to the same action
Action Annotation	Defines the URL of an action
InterceptorRefs Annotation	Gropup of @InterceptorRef annotations
InterceptorRef Annotation	Interceptor, or interceptor stack to be applied to at action
Results Annotation	Group of @Result annotations
Result Annotation	Defines a result for an action
Namespace Annotation	Set the path of the action URL (used to overwrite the default)
ResultPath Annotation	Set where the results are located (used to overwrite the default)
ParentPackage Annotation	Set the parent package of the actions (used to overwrite the default)
ExceptionMappings	Group of @ExceptionMapping annotations
ExceptionMapping	Defines an exception mapping

Workflow Annotations

Annotation	Description
InputConfig Annotation	Defines what method to execute, or result to be returned if there are validation errors

Interceptor Annotations

To use these annotations, you have to specify the AnnotationWorkflowInterceptor to your interceptor stack.

Annotation	Description
After Annotation	Marks a action method that needs to be executed after the result.
Before Annotation	Marks a action method that needs to be executed before the main action method.
BeforeResult Annotation	Marks a action method that needs to be executed before the result.

Validation Annotations

To use annotation-based validation,

Currently only in beta-status, an xwork-tiger project exists that is starting to add some basic J2SE 5 ("Tiger") support to WebWork. Currently, the only Java 5 implementation in xwork-tiger.jar is a Map and Collection support using generics.

In short, instead of specifying the types found in collections and maps as documented in Type Conversion, the collection's generic type is used. This means you most likely don't need any ClassName-conversion.properties files.

Info

title	Work in progress

This is a work in progress and not yet finished! More complex examples will follow. For now, have a look at the unit tests within the xwork-tiger project path.

Create XXX-conversion.properties via "ant apt" target

This is an example for the apt ant target:

...


    <target name="apt">
        <mkdir dir="${build}/generated"/>

        <path id="classpath">
            <pathelement path="${basedir}/build/java"/>
            <pathelement path="${basedir}/build/test"/>
            <!-- xwork.jar and xwork-tiger.jar must be in one of the following lib dirs -->
            <fileset dir="${basedir}/lib/build" includes="*.jar"/>
            <fileset dir="${basedir}/lib/default" includes="*.jar"/>
            <fileset dir="${basedir}/lib/spring" includes="*.jar"/>
        </path>

        <property name="pclasspath" refid="classpath"/>

        <!-- Change the includes attribute value to match your annotated java files -->
        <fileset id="sources" dir="." includes="src/test/**/*.java" />

        <pathconvert pathsep=" " property="sourcefiles" refid="sources"/>

        <echo>

            CLASSPATH ${pclasspath}

            SOURCES: ${sourcefiles}

        </echo>

        <exec executable="apt" >
            <arg value="-s"/>
            <arg value="${build}/generated"/>
            <arg value="-classpath"/>
            <arg pathref="classpath"/>
            <arg value="-nocompile"/>
            <arg value="-factory"/>
            <arg value="com.opensymphony.xwork.apt.XWorkProcessorFactory"/>
            <arg line="${sourcefiles}"/>
        </exec>
    </target>

Type Conversion Annotations

If you want to use annotation based type conversion, you have to annotate the class or interface with the Conversion Annotation.
Currently runtime evaluation for these annotations is not supported. This feature will be added in the near future.

For now you have to run the apt target via ant (TODO: not yet in CVS).

...

@Conversion

The Conversion annotation must be applied at Type level.

Parameter	Required	Default	Notes
conversion	no		Used for Type Conversions being applied at Type level.

...

@TypeConversion

Parameter	Required	Default	Notes
key	no	The annotated property/key name	The optional property name mostly used within TYPE level annotations.
type	no	ConversionType.CLASS	Enum value of ConversionType. Determines whether the conversion should be applied at application or class level.
rule	no	ConversionRule.PROPERTY	Enum value of ConversionRule. The ConversionRule can be a property, a Collection or a Map.
converter	either this or value		The class name of the TypeConverter to be used as converter.
value	either converter or this		The value to set for ConversionRule.KEY_PROPERTY.

The TypeConversion annotation can be applied at property and method level.

Example:

...


@Conversion()
public class ConversionAction implements Action {

    private String convertInt;

    private String convertDouble;

    private List users = null;

    private HashMap keyValues = null;

    @TypeConversion(type = ConversionType.APPLICATION, converter = "com.opensymphony.xwork.util.XWorkBasicConverter")
    public void setConvertInt( String convertInt ) {
        this.convertInt = convertInt;
    }

    @TypeConversion(converter = "com.opensymphony.xwork.util.XWorkBasicConverter")
    public void setConvertDouble( String convertDouble ) {
        this.convertDouble = convertDouble;
    }

    @TypeConversion(rule = ConversionRule.COLLECTION, converter = "java.util.String")
    public void setUsers( List users ) {
        this.users = users;
    }

    @TypeConversion(rule = ConversionRule.MAP, converter = "java.math.BigInteger")
    public void setKeyValues( HashMap keyValues ) {
        this.keyValues = keyValues;
    }

    @TypeConversion(type = ConversionType.APPLICATION, property = "java.util.Date", converter = "com.opensymphony.xwork.util.XWorkBasicConverter")
    public String execute() throws Exception {
        return SUCCESS;
    }
}

Validation Annotations

If you want to use annotation based validation, you have to annotate the class or interface with Validation Annotation.

These are the standard validator annotations that come with XWork-tiger:

...

@Validations

If you want to use several annotations of the same type, these annotation must be nested within the @Validations() annotation.

The possible parameters for @Validations() are as followed:

Parameter	Required	Notes
requiredFields	no	Add list of RequiredFieldValidators
customValidators	no	Add list of CustomValidators
conversionErrorFields	no	Add list of ConversionErrorFieldValidators
dateRangeFields	no	Add list of DateRangeFieldValidators
emails	no	Add list of EmailValidators
fieldExpressions	no	Add list of FieldExpressionValidators
intRangeFields	no	Add list of IntRangeFieldValidators
requiredFields	no	Add list of RequiredFieldValidators
requiredStrings	no	Add list of RequiredStringValidators
stringLengthFields	no	Add list of StringLengthFieldValidators
urls	no	Add list of UrlValidators
visitorFields	no	Add list of VisitorFieldValidators
stringRegexs	no	Add list of StringRegexValidator
regexFields	no	Add list of RegexFieldValidator
expressions	no	Add list of ExpressionValidator

...


   @Validations(
            requiredFields =
                    {@RequiredFieldValidator(type = ValidatorType.SIMPLE, fieldName = "customfield", message = "You must enter a value for field.")},
            requiredStrings =
                    {@RequiredStringValidator(type = ValidatorType.SIMPLE, fieldName = "stringisrequired", message = "You must enter a value for string.")},
            emails =
                    { @EmailValidator(type = ValidatorType.SIMPLE, fieldName = "emailaddress", message = "You must enter a value for email.")},
            urls =
                    { @UrlValidator(type = ValidatorType.SIMPLE, fieldName = "hreflocation", message = "You must enter a value for email.")},
            stringLengthFields =
                    {@StringLengthFieldValidator(type = ValidatorType.SIMPLE, trim = true, minLength="10" , maxLength = "12", fieldName = "needstringlength", message = "You must enter a stringlength.")},
            intRangeFields =
                    { @IntRangeFieldValidator(type = ValidatorType.SIMPLE, fieldName = "intfield", min = "6", max = "10", message = "bar must be between ${min} and ${max}, current value is ${bar}.")},
            dateRangeFields =
                    {@DateRangeFieldValidator(type = ValidatorType.SIMPLE, fieldName = "datefield", min = "-1", max = "99", message = "bar must be between ${min} and ${max}, current value is ${bar}.")},
            expressions = {
                @ExpressionValidator(expression = "foo &gt; 1", message = "Foo must be greater than Bar 1. Foo = ${foo}, Bar = ${bar}."),
                @ExpressionValidator(expression = "foo &gt; 2", message = "Foo must be greater than Bar 2. Foo = ${foo}, Bar = ${bar}."),
                @ExpressionValidator(expression = "foo &gt; 3", message = "Foo must be greater than Bar 3. Foo = ${foo}, Bar = ${bar}."),
                @ExpressionValidator(expression = "foo &gt; 4", message = "Foo must be greater than Bar 4. Foo = ${foo}, Bar = ${bar}."),
                @ExpressionValidator(expression = "foo &gt; 5", message = "Foo must be greater than Bar 5. Foo = ${foo}, Bar = ${bar}.")
    }
    )
    public String execute() throws Exception {
        return SUCCESS;
    }

...

@RequiredFieldValidator

This validator checks that a field is non-null.

Example:

...


@RequiredFieldValidator(message = "Default message", key = "i18n.key", shortCircuit = true)

...

@RequiredStringValidator

This validator checks that a String field is not empty (i.e. non-null with a length > 0).

Parameter	Required	Default	Notes
trim	no	true	Boolean property. Determines whether the String is trimmed before performing the length check.

Example:

...


@RequiredStringValidator(message = "Default message", key = "i18n.key", shortCircuit = true, trim = true)

...

@StringLengthFieldValidator

This validator checks that a String field is of the right length. It assumes that the field is a String.

Parameter	Required	Default	Notes
trim	no	true	Boolean property. Determines whether the String is trimmed before performing the length check.
minLength	no		Integer property. The minimum length the String must be.
maxLength	no		Integer property. The maximum length the String can be.

If neither minLength nor maxLength is set, nothing will be done.

Example:

...


@StringLengthFieldValidator(message = "Default message", key = "i18n.key", shortCircuit = true, trim = true, minLength = "5",  maxLength = "12")

...

@StringRegexValidator

This validator checks that a String field matches a configure Regular Expression, if it is not an empty String.

Parameter	Required	Default	Notes
regex	yes	"."	String property. The Regular Expression for which to check a match.
caseSensitive	no	true	Whether the matching of alpha characters in the expression should be done case-sensitively.

Example:

...


@StringRegexValidator(message = "Default message", key = "i18n.key", shortCircuit = true, regex = "a regular expression", caseSensitive = true)

Annotation	Description
ConversionErrorFieldValidator Annotation	Checks if there are any conversion errors for a field.
DateRangeFieldValidator Annotation	Checks that a date field has a value within a specified range.
DoubleRangeFieldValidator Annotation	Checks that a double field has a value within a specified range.
EmailValidator Annotation	Checks

...

@EmailValidator

...

that a field is a valid e-mail address

...

.

Example:

...


@EmailValidator(message = "Default message", key = "i18n.key", shortCircuit = true)

ExpressionValidator Annotation	Validates an expression.
FieldExpressionValidator Annotation	Uses an OGNL expression to perform its validator.
IntRangeFieldValidator Annotation	Checks

...

@UrlValidator

This validator checks that a field is a valid URL.

Example:

...


@UrlValidator(message = "Default message", key = "i18n.key", shortCircuit = true)

...

@IntRangeFieldValidator

...

that a numeric field has a value within a specified range.

Parameter	Required	Default	Notes
min	no		Integer property. The minimum the number must be.
max	no		Integer property. The maximum number can be.

If neither min nor max is set, nothing will be done.

The values for min and max must be inserted as String values so that "0" can be handled as a possible value.

Example:

...


@IntRangeFieldValidator(message = "Default message", key = "i18n.key", shortCircuit = true, min = "0", max = "42")

...

@DateRangeFieldValidator

This validator checks that a date field has a value within a specified range.

Parameter	Required	Default	Notes
min	no		Date property. The minimum the date must be.
max	no		Date property. The maximum date can be.

If neither min nor max is set, nothing will be done.

Example:

...


@DateRangeFieldValidator(message = "Default message", key = "i18n.key", shortCircuit = true, min = "2005/01/01", max = "2005/12/31")

...

@ConversionErrorFieldValidator

This validator checks if there are any conversion errors for a field and applies them if they exist. See Type Conversion Error Handling for details.

Example:

...


@ConversionErrorFieldValidator(message = "Default message", key = "i18n.key", shortCircuit = true)

...

@ExpressionValidator

This validator uses an OGNL expression to perform its validation. The error message will be added to the action if the expression returns false when it is evaluated against the value stack.

Parameter	Required	Default	Notes
expression	yes		An OGNL expression that returns a boolean value.

Example:

...


@ExpressionValidator(message = "Default message", key = "i18n.key", shortCircuit = true, expression = "an OGNL expression" )

...

@FieldExpressionValidator

This validator uses an OGNL expression to perform its validation. The error message will be added to the field if the expression returns false when it is evaluated against the value stack.

Parameter	Required	Default	Notes
expression	yes		An OGNL expression that returns a boolean value.

Example:

...


@FieldExpressionValidator(message = "Default message", key = "i18n.key", shortCircuit = true, expression = "an OGNL expression")

...

@VisitorFieldValidator

The validator allows you to forward validation to object properties of your action using the objects own validation files. This allows you to use the ModelDriven development pattern and manage your validations for your models in one place, where they belong, next to your model classes. The VisitorFieldValidator can handle either simple Object properties, Collections of Objects, or Arrays.

The error message for the VisitorFieldValidator will be appended in front of validation messages added by the validations for the Object message.

Parameter	Required	Default	Notes
context	no	action alias	Determines the context to use for validating the Object property. If not defined, the context of the Action validation is propogated to the Object property validation. In the case of Action validation, this context is the Action alias.
appendPrefix	no	true	Determines whether the field name of this field validator should be prepended to the field name of the visited field to determine the full field name when an error occurs. For example, suppose that the bean being validated has a "name" property. If appendPrefix is true, then the field error will be stored under the field "bean.name". If appendPrefix is false, then the field error will be stored under the field "name". If you are using the VisitorFieldValidator to validate the model from a ModelDriven Action, you should set appendPrefix to false unless you are using "model.name" to reference the properties on your model.

Example:

...


@VisitorFieldValidator(message = "Default message", key = "i18n.key", shortCircuit = true, context = "action alias", appendPrefix = true)

Here we see the context being overridden in the validator mapping, so the action alias context will not be propogated.

ModelDriven example:

...


@VisitorFieldValidator(message = "Default message", key = "i18n.key", shortCircuit = true, context = "action alias", appendPrefix = true)

This will use the model's validation rules and any errors messages will be applied directly (nothing is prefixed because of the empty message).

More Complex Examples

An Annotated Interface

Mark the interface with @Validation()
Apply standard or custom annoations at method level

...


@Validation()
public interface AnnotationDataAware {

    void setBarObj(Bar b);

    Bar getBarObj();

    @RequiredFieldValidator(message = "You must enter a value for data.")
    @RequiredStringValidator(message = "You must enter a value for data.")
    void setData(String data);

    String getData();
}

An Annotated Class

...

RegexFieldValidator Annotation	Validates a regular expression for a field.
RequiredFieldValidator Annotation	Checks that a field is non-null.
RequiredStringValidator Annotation	Checks that a String field is not empty.
StringLengthFieldValidator Annotation	Checks that a String field is of the right length.
UrlValidator Annotation	Checks that a field is a valid URL.
Validation Annotation	Marker annotation for validation at Type level.
Validations Annotation	Used to group validation annotations.
VisitorFieldValidator Annotation	Invokes the validation for a property's object type.
CustomValidator Annotation	Use this annotation for your custom validator types.

Resources

Validation using Annotations (arsenalist)

Type Conversion Annotations

By default, type conversion for Maps and Collections using generics is directly supported.

In short, instead of specifying the types found in collections and maps as documented in Type Conversion, the collection's generic type is used. By using annotations, an application should be able to avoid using any ClassName-conversion.properties files.

To use annotation-based type conversion, annotate the class or interface with the Conversion Annotation.

Annotation	Description
Conversion Annotation	Marker annotation for type conversions at Type level.
CreateIfNull Annotation	For Collection and Map types: Create the types within the Collection or Map, if null.
Element Annotation	For Generic types: Specify the element type for Collection types and Map values.
Key Annotation	For Generic types: Specify the key type for Map keys.
KeyProperty Annotation	For Generic types: Specify the key property name value.
TypeConversion Annotation	Used for class and application wide conversion rules.

Tiles Annotations

The Tiles Plugin provides it's own set of Annotations. They can be used to keep tiles.xml short. Instead tiles definitions can be created by annotating actions.

Annotation	Description
TilesDefinition	Represents a `<definition>` element in `tiles.xml`
TilesDefinitions	A list of `TilesDefinition` Annotations
TilesPutAttribute	Represents a `<put-attribute>` element in `tiles.xml`
TilesPutListAttribute	Represents a `<put-list-attribute>` element in `tiles.xml`
TilesAddAttribute	Represents a `<add-attribute>` element in `tiles.xml`
TilesAddListAttribute	Represents a `<add-list-attribute>` element in `tiles.xml`

Next: Configuration Elements

...

Child pages

Versions Compared

Old Version 13

New Version Current

Key

Action Annotations

Workflow Annotations

Interceptor Annotations

Validation Annotations

Create XXX-conversion.properties via "ant apt" target

Type Conversion Annotations

@Conversion

@TypeConversion

Validation Annotations

@Validations

@RequiredFieldValidator

@RequiredStringValidator

@StringLengthFieldValidator

@StringRegexValidator

@EmailValidator

@UrlValidator

@IntRangeFieldValidator

@DateRangeFieldValidator

@ConversionErrorFieldValidator

@ExpressionValidator

@FieldExpressionValidator

@VisitorFieldValidator

More Complex Examples

An Annotated Interface

An Annotated Class

Resources

Type Conversion Annotations

Tiles Annotations

Next: Configuration Elements

Child pages

Page History

Versions Compared

Old Version 13

New Version Current

Key

Action Annotations

Workflow Annotations

Interceptor Annotations

Validation Annotations

Create XXX-conversion.properties via "ant apt" target

Type Conversion Annotations

@Conversion

@TypeConversion

Validation Annotations

@Validations

@RequiredFieldValidator

@RequiredStringValidator

@StringLengthFieldValidator

@StringRegexValidator

@EmailValidator

@UrlValidator

@IntRangeFieldValidator

@DateRangeFieldValidator

@ConversionErrorFieldValidator

@ExpressionValidator

@FieldExpressionValidator

@VisitorFieldValidator

More Complex Examples

An Annotated Interface

An Annotated Class

Resources

Type Conversion Annotations

Tiles Annotations

Next: Configuration Elements