Home > Guides > Core Developers Guide > Struts 2 Maven Archetypes > Struts 2 Blank Archetype |

Apache Struts 2 Documentation
Struts 2 Blank Archetype
Edit Page Browse Space Add Page Add News

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

Contents

## 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, eg. 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
`¦- main` | Primary source directory
`¦ ¦- java` | Java source code
`¦ ¦ `- tutorial` | Package defined by `groupId` parameter
`¦ ¦ `- example` | The example actions from the archetype
`¦ ¦- resources` | Resources (config, property, and validation files, and so on
`¦ ¦ `-tutorial` | Package defined by `groupId` parameter
`¦ ¦ `- example` | Example property and validation files from archetype
`¦ `- webapp` | Web application files (HTML, JSP, etc.)
`¦ `- WEB-INF` | Typical WEB-INF folder
`¦ `- example` | Files from archetype
``- test` | Test code (unit tests etc.)
``- java` | Java-based test code
``- tutorial` | Package defined by `groupId` parameter
``- 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:

`src` | All project source
`¦- tutorial` | Tutorial package
`¦ `- example` | Example package
`¦ ¦- Login.java` | Login action source
`¦ ¦- package.properties` | Resource file
`¦ `- Login-validation.xml` | Validation file
``- struts.xml` | Struts 2 config file
`web` | Web app files
`¦- WEB-INF` | Typical WEB-INF folder
``- 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.

One 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.