The Convention is a code by convention and component plugin similar to the Codebehind and Zero-config plugins.

Introduction

The Convention Plugin provides the following features:

• Action location by package naming conventions
• Result (JSP, FreeMarker, etc) location by naming conventions
• Class name to URL naming convention
• Package name to namespace convention
• SEO compliant URLs (i.e. my-action rather than MyAction)
• Action name overrides using annotations
• Namespace overrides using annotations
• XWork package overrides using annotations
• Default action and result handling (i.e. /products will try com.example.actions.Products as well as com.example.actions.products.Index)

The Convention Plugin should require no configuration to use. Many of the conventions can be controlled using configuration properties and many of the classes can be extended or overridden.

Setup

In order to use the Convention plugin, you first need to add the JAR file to the WEB-INF/lib directory of your application.

Hello world

Now that the Convention plugin has been added to your application, let's start with a very simple example. This example will use an actionless result that is identified by the URL. By default, the Convention plugin assumes that all of the results are stored in WEB-INF/content. This can be changed by setting the property struts.convention.result.path in the Struts properties file to the new location. Don't worry about trailing slashes, the Convention plugin handles this for you. Here is our hello world JSP:

Hello world!

If you start Tomcat (or whichever J2EE container you are using) and type in http://localhost:8080/hello-world into your browser you should see our JSP. This illustrates that the Convention plugin will find results even when no action exists and it is all based on the URL passed to Struts.

Code behind hello world

Let's expand on this example and add a code behind class. In order to do this we need to ensure that the Convention plugin is able to find our action classes. By default, the Convention plugin will find all action classes that implement com.opensymphony.xwork2.Action or whose name ends with the word Action in specific packages.

These packages are located by the Convention plugin using a search methodology. First the Convention plugin first have to tell the Convention plugin where the classes live. This is controlled via the property smarturls.action.packages setting in the struts.properties file. If you don't have a struts.properties file, simply create one and place it into the classpath of the application. This can be done by putting the file in WEB-INF/classes or into a JAR file in the root directory of that JAR file. Here's how it should look:

smarturls.action.packages=com.example.actions

This configuration tells SmartURLs to go find all the actions in the com.example.actions package and configure them for use. This will also find all actions in sub-packages as well. We'll get to sub-packages and namespaces next. Here's our code behind:

package com.example.actions;

import 

public class HelloWorld extends ActionSupport {
  private String message;

  public String getMessage() {
    return message;
  }

  public String execute() {
    message = "Hello World!"
    return SUCCESS;
  }
}

Sub-packages and namespaces

Results and locations

Components

Extensionless URLs

Configuration reference

Annotation reference