<< back to Maven Archetypes Edit on GitHub

# Struts 2 Blank Archetype

The Struts 2 Blank Archetype (“blank-archetype”) provides a minimal, but complete, Struts 2 application. It demonstrates some of the most basic Struts 2 concepts.

Features

- XML-based configuration, demonstrates including additional config file

- Example actions

- Package-level resource bundle

- XML-based validation

- Unit-testing

## Creating Our blank-archetype Project

We’ll run the following command from our project’s parent directory (this is shown using Unix-style commands).

    $ mvn archetype:generate -B \
                             -DgroupId=tutorial \
                             -DartifactId=tutorial \
                             -DarchetypeGroupId=org.apache.struts \
                             -DarchetypeArtifactId=struts2-archetype-blank \
                             -DarchetypeVersion=<version>
    $ ls
    tutorial/
    $ cd tutorial
    $ ls
    pom.xml         src/

Depending on the state of your local system you may see Maven downloading various libraries (known as “downloading the internet”, which is what it seems Maven does sometimes). Be patient – Maven is basically setting up your required libraries automatically. <version> - is the version of Struts 2 you want to use and archetype was released for, e.g. 2.1.8.1 .

### Staging repository

If the above command will fail because of missing archetypes in central repository, you can try to use staging repository like below

    mvn archetype:generate -B \
                           -DgroupId=tutorial \
                           -DartifactId=tutorial \
                           -DarchetypeGroupId=org.apache.struts \
                           -DarchetypeArtifactId=struts2-archetype-blank \
                           -DarchetypeVersion=<version>
                           -DarchetypeCatalog=http://people.apache.org/builds/struts/<version>/m2-staging-repository/

## Project Structure

The source code structure follows the normal Maven directory structure. The blank-archetype does not include all of the directories listed in the Maven structure reference page.

Our project’s structure looks like this:

Directory | Description
--- | ---
src | All project source
src/main | Primary source directory
src/main/java | Java source code
src/main/java/tutorial | Package defined by groupId parameter
src/main/java/tutorial/example | The example actions from the archetype
src/main/resources | Resources (config, property, and validation files, and so on
src/main/resources/tutorial | Package defined by groupId parameter
src/main/resources/tutorial/example | Example property and validation files from archetype
src/main/webapp | Web application files (HTML, JSP, etc.)
src/main/webapp/WEB-INF | Typical WEB-INF folder
src/main/webapp/WEB-INF/example | Files from archetype
src/test | Test code (unit tests etc.)
src/test/java | Java-based test code
src/test/java/tutorial | Package defined by groupId parameter
src/test/java/tutorial/example | Test code from archetype

### Structure Difference From Non-Maven Projects

One big change for folks not used to the Maven structure is the separation of Java source code and resource files. For example, in a non-Maven project our directory structure might look like this:

Directory | Description
--- | ---
src | All project source
src/tutorial | Tutorial package
src/tutorial/example | Example package
src/tutorial/example/Login.java | Login action source
src/tutorial/example/package.properties | Resource file
src/tutorial/example/Login-validation.xml | Validation file
src/struts.xml | Struts 2 config file
web | Web app files
web/WEB-INF | Typical WEB-INF folder
web/index.html | An HTML file

It can take a little while to get used to, but ultimately it provides good separation of “types” of things, and becomes second-nature pretty quickly. Note that it’s possible to use a non-Maven directory layout with Maven projects, but this can be challenging at some points.

## Building The Project

There are several different ways we can go about building our project, from simple compilation up to actually running the web application – all from within Maven.

### Compilation

    $ mvn compile

will create a `target` directory containing the compiled classes. By itself this isn’t terribly useful.

### Testing

Running

    $ mvn test

will compile the application and run the included unit tests. Blank-archetype’s unit tests are not extensive, but provide a simple starting point for writing more complex, application-specific tests.

Once we’ve run the Maven test command we’ll notice there’s a `target/surefire-reports` directory. The Maven Surefire Plugin is how Maven runs our unit tests. By default it will create test results in XML and text formats in the `target/surefire-reports` directory. These files can be examined to get further information regarding the failed tests.

### Assembling (Creating a WAR)

### Running

We can run blank-archetype using the Jetty server via the Maven Jetty Plugin by executing the Jetty plugin’s `run` command:

    $ mvn jetty:run

Once we’ve run the application we can see that it works by visiting `localhost:8080/tutorial/example/Welcome.action` as a sanity check.

## Application Documentation

The application consists of a few test actions demonstrating simple validation and package-level property (resource) files. The most interesting URLs are as follows (assuming we used `groupId=tutorial`):

URL | Description
--- | ---
/tutorial/example/Welcome.action | Handled by wildcard mapping
/tutorial/example/HelloWorld.action | Handled by explicit mapping, demonstrates package-level properties
/tutorial/example/Login.action | Handled by explicit mapping with method wilcard (see the Login.action documentation for information regarding how to access this URL)

### Application Configuration

The default Struts 2 configuration file is contained in `src/main/resources/struts.xml`. It includes an additional configuration file, `src/main/resources/example.xml`. The application’s mappings are contained in the `example.xml` file. The `struts.xml` file sets some constants.

See the struts.xml page for more information about the `struts.xml` file. For more information regarding what’s contained in typical `struts.xml` files start at the Configuration Elements page, which contains links to a bunch of information. See the Configuration Files page for more information regarding additional Struts 2 configuration files, including links to the files that set all the Struts 2 default configurations.

### Welcome.action

The mapping for this action is handled by a “catch-all” mapping in `example.xml`:

    <action name="*" class="tutorial2.example.ExampleSupport">
      <result>/example/{1}.jsp</result>
    </action>

This mapping is the last mapping contained in `example.xml` – anything not handled by mappings appearing before it in `example.xml` will be caught by this mapping. This mapping will look for JSP files in `src/main/webapp/example/*.jsp`. Since there’s a `Welcome.jsp` in that directory, we’re all set. See the Wildcard Mappings page for more information on how Struts 2 can use wildcard mappings.

### HelloWorld.action

The mapping executes the HelloWorld action, contained in `src/main/java/tutorial/example/HelloWorld.action`. This action retrieves a message from a package-level properties file, contained in `src/main/resources/tutorial/package.properties`. See the Localization page for more information about how Struts 2 handles message resources (it’s pretty cool).

### Login.action

This is another wildcard mapping:

    <action name="Login_*" method="{1}" class="tutorial2.example.Login">
      <result name="input">/example/Login.jsp</result>
      <result type="redirectAction">Menu</result>
    </action>

In the application the Login action is reached via a link, but not directly to `/tutorial/example/Login.action`. The link is actually `/tutorial/example/Login_input.action`. Reaching the Login action this way bypasses validation: if we hit the Login action directly we’ll get a validation error.

The validation configuration is contained in `/src/main/resources/tutorial/example/Login-validation.xml`. It checks for the presence of the `username` and `password` properties (form values). It uses messages stored in the `package.properties` file (in the same directory). See the Validation page for more information regarding Struts 2 validation.