THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
Preface
Struts Action Framework 2 is a popular,
...
easy-to-use
...
MVC
...
framework.
...
For
...
more
...
information
...
on
...
the
...
SAF
...
project,
...
please
...
visit
...
the
...
...
...
...
.
...
This
...
document
...
will
...
help
...
you
...
to
...
get
...
started
...
with
...
the
...
framework,
...
enabling
...
you
...
to
...
run
...
the
...
examples
...
and
...
demonstrations
...
provided
...
even
...
if
...
you
...
are
...
not
...
an
...
experienced
...
Java
...
web
...
application
...
developer.
...
Nevertheless,
...
the
...
framework
...
is
...
geared
...
towards
...
developers
...
that
...
have
...
an
...
understanding
...
towards
...
certain
...
technologies.
...
Before
...
diving
...
deeper
...
into
...
how
...
the
...
SAF
...
works,
...
it
...
is
...
recommended
...
that
...
you
...
have
...
some
...
knowledge
...
of
...
the
...
supporting
...
technologies.
| Panel | ||||||
|---|---|---|---|---|---|---|
| =
|
| ||||
}
- Java
-
|
For more about any of the supporting technologies, visit the Key Technologies page on the Apache Struts website.
Downloads and Resources
| Anchor | ||||
|---|---|---|---|---|
|
To get started with the framework, download the distribution and browse some of the online resources.
Download the Distribution
| Note |
|---|
A release of SAF 2 may not yet be available. |
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
Overview
The distribution contains the following directory layout:
| No Format |
|---|
- JavaBeans - HTML and HTTP - Web Containers (such as Tomcat) - XML {panel} For more about any of the supporting technologies, visit the [Key Technologies page|http://struts.apache.org/struts-action/userGuide/preface.html] on the Apache Struts website. h2. Downloads and Resources {anchor:Website&downloads} To get started with the framework, download the distribution and browse some of the online resources. h3. Download the Distribution {note}A release of SAF 2 may not yet be available.{note} The full distribution can be downloaded form the [Apache Struts website|http://struts.apache.org/downloads.html]. The distribution contains the {{struts-action2.jar}} file, a copy of all the documentation, sources, all [required and optional dependencies|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]. h2. Browse the Resources There are many online resources available. Here are links to help you find your way: - [Download SAF2|http://struts.apache.org/downloads.html] \- download the framework distribution - [Join the Forums|http://forums.opensymphony.com/category.jspa?categoryID=5] \- 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|http://struts.apache.org/mail.html]. (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|http://svn.apache.org/viewcvs.cgi/struts/action2/] \- Browse the source. - [Confluence Wiki|http://confluence.twdata.org/] \- Read it here first! The project documentation is created on the wiki and then posted as HTML to the website. - [JIRA Issue Tracker|http://issues.apache.org/struts/] \- Browse or file enhancements requests and defect reports. - [Apache Struts Home|http://struts.apache.org/] h2. Distribution Quickstart h3. Overview The distribution contains the following directory layout: {noformat} 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 {noformat} 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: - |
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 {noformat} |
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
...
demos
...
with
...
QuickStart
| Anchor | ||||
|---|---|---|---|---|
|
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 |
|---|
{anchor:Running demos} 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|http://jetty.mortbay.org/jetty/] container. With QuickStart, running the demos is as easy as can be. You just need to run: {code} > java -jar webwork.jar quickstart:<application-name> {code} |
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 {code} |
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 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.
Running Demos with Your Favorite Web Container
| Anchor | ||||
|---|---|---|---|---|
|
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.
| 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. |
To build a web application archive (WAR), simply run:
| Code Block |
|---|
|| 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 [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|QuickStart] to learn more about how it works and how you can utilize QuickStart with your own applications. See below for a more detailed description of how the blank application helps you to easily create your own WebWork-based applications. h2. Running Demos with Your Favorite Web Container {anchor:Running demos} In order to deploy applications and demos to your favorite servlet container (also called web container) such as [Apache Tomcat|http://jakarta.apache.org/tomcat/] or [Caucho Resin|http://www.caucho.com/], 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. {note:title=To Quickstart or not to Quickstart?} 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. {note} To build a web application archive (WAR), simply run: {code} > ant build -Dwebapp=$APP {code} 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 |
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 {code} |
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 |
|---|
{code} > http://localhost/showcase {code} |
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 {{
. The build also compiles the sources for each appolication and creates a WAR at {{
. However, these WAR files are NOT ready to be deployed. These WARs do not include any of the JAR files. (Omitting the JARS reduces the size of the download by almost 200mb.) To include the dependant JARs, run Ant in the {{
directory, and new WARs, with all the JARs, are placed in {{ |
Your First SAF2 Application
| Anchor | ||||
|---|---|---|---|---|
|
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!
| Code Block |
|---|
}}. {info} h2. Your First SAF2 Application {anchor:Installing} To get started on your own application, you can utilize the blank template, run the Ant task, or just setup your own from scratch. h3. 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. h3. 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! {code} > cd /projects/Apache/struts-current/action2/webapps > ant new {code} |
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
...
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.
| Code Block |
|---|
{code} /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 {code} * Copy to your {{ |
- Copy to your
webapp/lib
...
- directory
- the
struts-action-(VERSION).jar
- the
...
- ,
- all the
*.jar
...
- files
...
- in
...
/lib/default
...
- ,
- and any necessary optional {{*.jar}
...
- files
...
- in
...
- {{/lib/
...
- (optional
...
- configuration)
...
- }}.
...
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 Config Files
The following files are a minium requirement for your application.
Filename | Description |
|---|---|
struts-action.jar |
...
Framework |
...
library |
...
itself, |
...
found |
...
in |
...
distribution |
...
root |
...
directory |
xwork.jar |
|---|
...
XWork |
...
library |
...
on |
...
which |
...
WebWork |
...
is |
...
built |
oscore.jar |
|---|
...
OSCore, |
...
a |
...
general-utility |
...
library |
...
from |
...
OpenSymphony |
ognl.jar |
|---|
...
Object |
...
Graph |
...
Navigation |
...
Language |
...
(OGNL), |
...
the |
...
expression |
...
language |
...
used |
...
throughout |
...
the framework |
commons-logging.jar |
|---|
...
Commons |
...
logging, |
...
which |
...
WebWork |
...
uses |
...
to |
...
support |
...
transparently |
...
logging |
...
to |
...
either |
...
Log4J |
...
or |
...
JDK |
...
1.4 |
...
+ |
freemarker.jar |
|---|
...
All |
...
UI |
...
tag |
...
templates |
...
are |
...
written |
...
in |
...
Freemarker, |
...
which |
...
is |
...
also |
...
a |
...
good |
...
option |
...
for |
...
your |
...
views |
spring*.jar |
|---|
...
The |
...
default |
...
dependency |
...
injection |
...
container |
...
for |
...
the |
...
framework. |
...
web.xml |
|---|
...
J2EE |
...
web |
...
application |
...
configuration |
...
file |
...
that |
...
defines |
...
the |
...
servlets, |
...
JSP |
...
tag |
...
|
...
and |
...
so |
...
on |
...
for |
...
your |
...
web |
...
application |
action.xml |
|---|
...
WebWork |
...
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> {code} |
The
...
standard{{web.xml}
...
registers
...
FilterDispatcher
...
to
...
enable
...
framework
...
functionality
...
for
...
your
...
requests.
...
The
...
ContextLoaderListener
...
set
...
ups
...
...
as
...
our
...
dependency
...
injection
...
conitainer.
...
The
...
framework
...
uses
...
Spring
...
internally,
...
and
...
you
...
may
...
wish
...
to
...
use
...
it
...
to
...
deploy
...
your
...
own
...
objects.
...
See also:
...
...
Setup action.xml
...
| Wiki Markup |
|---|
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> {code} |
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:
...
...
Next | Onward to the First lesson |
|---|---|
Prev |