...

The Convention plugin uses a number of different annotations to override the default conventions that are used to map actions to URLs and locate results. In addition, you can modify the parent XWork package that actions are configured with.

Action annotation

The Convention plugin allows action classes to change the URL that they are mapped to using the Action annotation. This annotation can also be used inside the Actions annotation to allow multiple URLs to map to a single action class. This annotation must be defined on action methods like this:

...

package com.example.actions;

import com.opensymphony.xwork2.ActionSupport; 
import org.apache.struts2.convention.annotation.Action;
import org.apache.struts2.convention.annotation.Actions;

public class HelloWorld extends ActionSupport {
  @Action("/different/url")
  public String execute() {
    return SUCCESS;

  }

  @Action("url")
  public String doSomething() {
    return SUCCESS;
  }
}

...

If interceptors are not specified, the default stack is applied.

InterceptorRef annotation

Interceptors can be specified at the method level, using the Action annotation or at the class level using the InterceptorRefs annotation. Interceptors specified at the class level will be applied to all actions defined on that class. In the following example:

...

The following interceptors will be applied to "action1": "interceptor-1", all interceptors from "defaultStack", "validation".
All interceptors from "defaultStack" will be applied to "action2".

Result annotation

The Convention plugin allows action classes to define different results for an action. Results fall into two categories, global and local. Global results are shared across all actions defined within the action class. These results are defined as annotations on the action class. Local results apply only to the action method they are defined on. Here is an example of the different types of result annotations:

...

package com.example.actions;

import com.opensymphony.xwork2.ActionSupport; 
import org.apache.struts2.convention.annotation.Action;
import org.apache.struts2.convention.annotation.Actions;
import org.apache.struts2.convention.annotation.Result;
import org.apache.struts2.convention.annotation.Results;

public class HelloWorld extends ActionSupport {
  @Action(value="/different/url", 
    results={@Result(name="success", type="httpheader", params={"status", "500", "errorMessage", "Internal Error"})}
  )
  public String execute() {
    return SUCCESS;
  }

  @Action("/another/url")
  public String doSomething() {
    return SUCCESS;
  }
}

Namespace annotation

The namespace annotation allows the namespace for action classes to be changed instead of using the convention of the Java package name. This annotation can be placed on an action class or within the package-info.java class that allows annotations to be placed on Java packages. When this annotation is put on an action class, it applies to all actions defined in the class, that are not fully qualified action URLs. When this annotation is place in the package-info.java file, it changes the default namespace for all actions defined in the Java package. Here is an example of the annotation on an action class:

...

This changes the default namespace for all actions defined in the package com.example.actions. This annotation however doesn't apply to sub-packages.

ResultPath annotation

The ResultPath annotation allows applications to change the location where results are stored. This annotation can be placed on an action class and also in the package-info.java file. Here is an example of using this annotation:

...

The result for this class will be located in WEB-INF/jsps rather than the default of WEB-INF/content.

ParentPackage annotation

The ParentPackage annotation allows applications to define different parent XWork packages for specific action classes or Java packages. Here is an example of using the annotation on an action class:

package com.example.actions;

import com.opensymphony.xwork2.ActionSupport; 
import org.apache.struts2.convention.annotation.Action;
import org.apache.struts2.convention.annotation.ParentPackage;

@ParentPackage("customXWorkPackage")
public class HelloWorld extends ActionSupport {
  public String execute() {
    return SUCCESS;
  }
}

ExceptionMapping Annotation

This annotation can be used to define exception mappings to actions. See the exception mapping documentation for more details. These mappings can be applied to the class level, in which case they will be applied to all actions defined on that class:

...

This feature is experimental and has not been tested on all container, and it is strongly advised not to use it in production environments.

Troubleshooting

Tips

...

Common Errors

1. I get an error like "There is no Action mapped for namespace /orders and action name view.". This means that the URL /orders/view.action is not mapping to any action class. Check the namespace and the name of the action.
2. I get an error like "No result defined for action "my.example.actions.orders.ViewAction and result success". This means that the action was mapped to the right URL, but the Convention plugin was unable to find a success result for it. Check that the result file exists, like /WEB-INF/content/orders/view-success.jsp.

...