Getting Started

Preface

Struts Action Framework 2 is a popular, easy-to-use MVC framework. This tutorial will help you get started with the framework, even if you are not an experienced Java web application developer. The tutorial will walk you through installing the framework and creating a simple application.

However, the framework is geared toward professional developers. To create non-trivial applications, a working knowledge of several key technologies is required.

For more about any of the supporting technologies, visit the Key Technologies page on the Apache Struts website.

In this lesson, we download the framework, launch the example applications, and then get started on an application of our own.

Download the Distribution

The full distribution can be downloaded form the Apache Struts website. The distribution contains the struts-action2.jar file, a copy of all the documentation, sources, all required and optional dependencies,and example applications. For more information on how to build the framework from source or even from a clean checkout, please refer to Building the Framework from Source.

Browse the Resources

There are many online resources available. Here are links to help you find your way:

• Download SAF2 - download the framework distribution
• Join the Forums - The forums are full of active developers, contributors, and power users - often even available for chat. This is the best and quickest way to get a question answered.
• Subscribe to Mailing List and post a question, or browse Mail Archive. (You probably want to browse the archive or forum first. All posts from the forum are posted to the mailing lists, and vice versa.
• Subversion Repository - Browse the source.
• Confluence Wiki - Read it here first! The project documentation is created on the wiki and then posted as HTML to the website.
• JIRA Issue Tracker - Browse or file enhancements requests and defect reports.
• Apache Struts Home

Distribution Quickstart

The distribution contains the following directory layout:

dist/
docs/
lib/
src/
src/java/template/
webapps/
README.txt
build.properties
build.xml
ivy.xml
osbuild.xml
pom.xml
struts-action-(VERSION).jar
struts-action-(VERSION).zip
struts-action-(VERSION)-src.jar

The docs directory contains the current Javadocs, the full user documentation including the document you are reading, and taglib documentation, as well as Clover, JUnit and dependency reports for the build.

The dist directory contains framework files with different packaging:

• struts-action-nostatic-<version>.jar: containing only the framework without the static content
• struts-action-static-<version>.zip: containing the required framework static dependencies

The lib directory contains the required as well as optional Dependencies for the framework, organized in subdirectories to represent different optional configurations:

lib/
      ajax
      bootstrap
      build
      cewolf
      default
      fileupload
      fileupload-cos
      fileupload-pell
      hibernate
      jasperreports
      jfree
      pico
      plexus
      portlet
      quickstart
      sitemesh
      source
      spring
      tiger
      tiles
      velocity
      xslt

Note that none of the optional packages are required to use the framework. If you wish to use certain features such as JasperReports or Java 5 (Tiger) generics and annotation support, then you must include the optional packages.

The framework also comes packaged with all the source files and templates for the JSP tags.

Running the Examples

Several example applications come bundled with the distribution. You can run these using the QuickStart feature or in your own web container.

Running with QuickStart

The framework provides a slick way to jump into web development called QuickStart. Essentally, QuickStart is combination of technologies and conventions. The key technology is the ability to run web applications "out of the box" with a stripped-down Jetty container.

With QuickStart, running the demos is as easy as can be. You just need to run:

> java -jar webwork.jar quickstart:<application-name>

from the distribution's top directory, where <application-name> is one of the subdirectory names under webapps/. Each subdirectoy hosts a demo application.

If you want to start the shopping-cart webapp, the startup command would be:

> java -jar webwork.jar quickstart:shopping-cart

One the application starts up, point your browser to http://localhost:8080/shopping-cart/, and you should be ready to go.

Several example appliations are included in the distribution.

You can review the QuickStart documentation to learn more about how it works and how you can utilize QuickStart with your own applications.

Running with your web container

In order to deploy applications and demos to your favorite servlet container (also called web container) such as Apache Tomcat or Caucho Resin, you will need to build WAR files from the webapps directory. You will find an Antbuild file there which will provide you with an easy way to build your own WARs.
To build a web application archive (WAR), simply run:

> ant build -Dwebapp=$APP

where $APP is the name of the web application you want to build. After the build is finished, the fully-built WAR file can be found in the dist directory. You may deploy this file to any servlet container.

To build the {{showcase}] aplication, substite "showcase" for $ID.

> ant build -Dwebapp=showcase

To deploy the built showcase.war to Tomcat, move or copy the WAR to $TOMCAT_HOME/webapps/ or use the Tomcat Manager Application to upload and deploy the WAR. After the WAR is deployed (and your server is started), point your browser to

> http://localhost/showcase

Of course, if the server is not local, substitute the IP or hostname for "localhost", including a port designation if needed. If you are not deploying the Showcase application, then substitute the appropriate application name for "showcase"

Your First SAF2 Application

To get started on your own application, you can utilize the blank template, run the Ant task, or just setup your own from scratch.

Using the Blank template

The blank web application in the distribution's webapp directory is meant as a template. Make a copy of "blank" and use the copy as the basis for your application.

Run the Ant task

While it's simple enough to copy a directory tree, there is an even easier way to get started. In the webapps directory, there is a build.xml file. The new task of this Ant build file can create fresh, empty web application for you. Just add content!

> cd /projects/Apache/struts-current/action2/webapps
> ant new

The Ant buildfile will prompt you for a the name of your new application.

new:
     [echo]
     [echo]             +=============================================================+
     [echo]             |              -- Create a new web application  --            |
     [echo]             +=============================================================+
     [echo]

    [input] Enter the name of your new application [myapp]? saf-sample
     [echo] Creating 'saf-sample' web application...
     [copy] Copying 7 files to /Users/rainerh/projects/action2/webapps/saf-sample
     [copy] Copying 1 file to /Users/rainerh/projects/action2/webapps/saf-sample
     [echo]
     [echo]             +=============================================================+
     [echo]             |    -- Your Web Application was created successfully! --     |
     [echo]             |                                                             |
     [echo]             | Now you should be able to cd to your application and run:   |
     [echo]             | > ant build -Dwebapp=saf-sample                              |
     [echo]             +=============================================================+

BUILD SUCCESSFUL

This task creates a new directory within the webapps dir.

For example, this is the setup for a new webapp project created with 'ant new' webapp name 'saf-sample':

webapps/
  saf-sample/
    src/
      java/
         org/apache/struts/action2/example/HomeAction.java -- A simple action example implementation
      webapp/
        index.jsp -- redirects to home.action
        WEB-INF/
          classes/
            action.properties -- Simple properties to use Spring and run SAF in devMode
            action.xml -- Basic action mapping sample with one action mapping
          pages/
            home.jsp -- The home.jsp referenced via the HomeAction
          applicationContext.xml -- blank Spring definition file. Add your Spring beans here.
          web.xml -- basic web.xml for SAF

You can now use the newly created project structure to get your SAF-based project running.

Setting up from scratch

If for some reason the blank template doesn't work for you, it's not so hard to setup a SAF-based application from scratch.

Structure of your web application

• Setup a file structure for your application.

/mywebapp/
/mywebapp/template/
/mywebapp/META-INF/
/mywebapp/WEB-INF/
/mywebapp/WEB-INF/classes/
/mywebapp/WEB-INF/lib/
/mywebapp/WEB-INF/lib/CORE&OPTIONAL *.jar
/mywebapp/WEB-INF/web.xml

• Copy to your webapp/lib directory
  • the struts-action-(VERSION).jar,
  • all the *.jar files in /lib/default, and
  • any necessary optional *.jar files from /lib/.

If you need to customize your own templates (how HTML is rendered from webwork UI tags), copy into your webapp directory the /src/java/template directory.

Minimum set of libraries and configuration files

The following files are a minium requirement for your application.

The library files (*.jar) needs to be copied to your /mywebapp/WEB-INF/lib/ directory. If you need optional functionalities requiring dependencies on optional JARs, those JARs need to be copied to this directory too.

Setup web.xml

Create an web.xml file in [webapp]/WEB-INF (or merge into it the framework resources).

<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
  <display-name>My Application</display-name>
  <filter>
    <filter-name>action2</filter-name>
    <filter-class>org.apache.struts.action2.dispatcher.FilterDispatcher</filter-class>
  </filter>

  <filter-mapping>
    <filter-name>action</filter-name>
    <url-pattern>/*</url-pattern>
  </filter-mapping>
  <listener>
    <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
  </listener>
</web-app>

The standard web.xml registers a FilterDispatcher to enable framework functionality for your requests. The ContextLoaderListener configures Spring as our dependency injection conitainer. The framework uses Spring internally, and you may wish to use it to deploy your own objects.

See also: web.xml

Setup action.xml

Create a skeleton action.xml file in /$APP/WEB-INF/classes.

<!DOCTYPE xwork PUBLIC "-//OpenSymphony Group//XWork 1.1.1//EN"
"http://www.opensymphony.com/xwork/xwork-1.1.1.dtd">

<xwork>	<!-- Include framework defaults (from Struts Action JAR). -->
	<include file="action-default.xml" />

	<!-- Configuration for the default package. -->
	<package name="default" extends="action-default">
	</package>
</xwork>

For now, the action.xml does only two things:

• It tells the framework that it should import the configuration information from action-default.xml. (This file is located at the root of the struts-action.jar, so it is sure to be found.)

• It defines a default package (with the <package> section) where framework elements like actions, results and interceptors are registered.

See also: action.xml