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 The Bootstrap tutorial walks through installing the framework and creating a simple application.However,
Note |
---|
While the framework is |
...
simple to use, creating non-trivial applications |
...
assumes a working knowledge of |
...
many JEE technologies, including:
| ||
Panel | ||
---|---|---|
| ||
|
For more about any of the supporting technologies, visit see the Key Technologies page on the Apache Struts websitePrimer.
In this the Ready, Set, Go! lesson, we download the framework , launch the example applications, and then get started on an application of our own.
Download the Distribution
...
A
...
The full distribution can be downloaded form from the Apache Struts website. The full distribution contains the strutsstruts2-action2core.jar
file, a copy of all the documentation, sources, all required and optional related 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:
No Format |
---|
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:
No Format |
---|
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:
Code Block |
---|
> 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:
Code Block |
---|
> 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.
blank | Not really an example application, but a blank web application template to use as the base for your own applications |
---|---|
cookbook | A "how to" application that displays the full source code for each "recipe". |
mailreader | The infamous Struts MailReader application. |
portlet | Demonstration of our porlet integration (to be deployed in a Portal Server) – see the Portlet Tutorial to read more about portlets |
shopping-cart | Simple example application demonstrating various aspects of the framework |
showcase | Extensive demonstration of all tag and AJAX features, along with other examples and some best practices |
starter | Basic web application that you can use as a starting point for experimenting with framework features - one could almost call it a "playground" application |
You can review the QuickStart documentation to learn more about how it works and how you can utilize QuickStart with your own applications.
Note | ||
---|---|---|
| ||
Quickstart is a handy tool for development of your applications. We recommend that you give QuickStart a try, to see if it meets your development needs. However, QuickStart is not meant to be your sole environment for web application development. QuickStart is meant to help you rapidily create proof-of-concepts and so that you can see the result. We recommend you always at least test your work under other applications servers, such as Tomcat, Resin, or even the standard, standalone version of Jetty. |
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:
Code Block |
---|
> 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.
Code Block |
---|
> 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
Code Block |
---|
> 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"
Info | ||
---|---|---|
| ||
The framework build copies the sources of each bundled web application to |
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.
, a copy of the documentation in HTML format, and the complete source code.
Tip |
---|
To compile it yourself, refer to Building the Framework from Source. |
Our First Application
To get started with a new application, we can use the blank template, run the Maven archetype, or set up a web infrastructure from scratch.
Using the Blank Application
...
The blank web application in the distribution's webapp
apps
directory is meant as a template. Make We can make a copy of the "blank.war", deploy it to our container, and use the exploded copy as the basis for your applicationour application. There is even a simple batch file in the source code directory that we can use to recompile the application in place.
Run the
...
Maven Archetype
For those of us using Maven as a build system, we can use the Maven Archetype to create a new application.
For directions on using the Struts 2 archetypes see the Struts 2 Maven Archetypes page
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!
Code Block |
---|
> cd /projects/Apache/struts-current/action2/webapps
> ant new
|
The Ant buildfile will prompt you for a the name of your new application.
Setting up from scratch
If for some reason the blank template or archetype doesn't work for youout, it's not so hard to setup a SAF-based Struts 2 application from scratch.
Structure of your web application
- Setup a file structure for your application.
Code Block |
---|
/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/
.
- the
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.
Filename | Description |
---|---|
| Framework library itself, found in distribution root directory |
| XWork library on which SAF 2 is built |
| OSCore, a general-utility library from OpenSymphony |
| Object Graph Navigation Language (OGNL), the expression language used throughout the framework |
| Commons logging, which the framework uses to support transparently logging to either Log4J or JDK 1.4+ |
| All UI tag templates are written in Freemarker, which is also a good option for your views |
| The default dependency injection container for the framework. |
| J2EE web application configuration file that defines the servlets, JSP tag |
| Framework configuration file that defines the actions, results, and interceptors 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
Wiki Markup |
---|
Create an {{web.xml}} file in {{\[webapp\]/WEB-INF}} (or merge into it the framework resources). |
Code Block | ||
---|---|---|
| ||
<?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
.
Code Block | ||
---|---|---|
| ||
<!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 thestruts-action.jar
, so it is sure to be found.)
- It defines a default package (with the <package> section) where framework elements like
actions
,results
andinterceptors
are registered.
See also: action.xml
For details, see Simple Setup.
Next | Onward to Hello World |
---|---|
Prev | Return to Bootstrap |
Next | Onward to the First lesson |
Prev |