Welcome to Apache Struts 2
Apache Struts 2 is a flexible control layer based on standard technologies like Java Filters, JavaBeans, ResourceBundles, Locales, and XML, as well as various OpenSymphony packages, like OGNL and XWork. The framework helps you create an extensible development environment for your application, based on industry standards and proven design patterns.
Work in progress!
Apache Struts 2 is at a pre-release, pre-Alpha stage. If you are just getting started with Struts2/WebWork2, we recommend WebWork 2.2 as an entry point. WW2 is stable and production ready. When Struts 2 is released, migration paths for WebWork 2 and Struts 1 developers will be available.
See the Struts 2 release plan for details and status.
Apache Struts 2 in a Nutshell
The framework provides its own web Controller component and integrates with other technologies to provide the Model and the View. For the Model, the framework can interact with standard data access technologies, like JDBC and EJB, as well as most any third-party packages, like Cayenne, Hibernate, or iBATIS. For the View, the framework works well with JavaServer Pages, including JSTL and JSF, as well as FreeMarker or Velocity Templates, PDF, XSLT, and other presentation systems.
The framework's Controller acts as a bridge between the application's Model and the web View. When a request is received, the Controller invokes an Action class. The Action class consults with the Model (or, preferably, a Facade representing your Model) to examine or update the application's state. To transfer data between the Model and the View, properties can be placed on the Action class, or on a plain old JavaBean.
Most often, the Model is represented as a graph of JavaBean objects. Preferably, the Model will do the "heavy lifting", and the Action will act as a "traffic cop" or adapter. The framework provides sophisticated, automatic type conversion to simplify transfering data between rich domain objects and text-only HTTP requests.
To make it easier to access dynamic data obtained by an Action, the framework includes a library of custom tags. The tags interact with the framework's validation and internationalization features, to ensure that input is correct and output is localized. The tag library can be used with JSP, FreeMarker, or Velocity.
Struts Configuration in a Nutshell
A web application uses a deployment descriptor to initialize resources like servlets and taglibs. The deployment descriptor is formatted as a XML document and named
web.xml. Likewise, the framework uses a configuration file, named
struts.xml, to initialize its own resources. These resources include action mappings, to direct input to server-side Action classes, and result types, to select output pages.
Here's a simple configuration (
struts.xml) for a login workflow:
Aside from actions and results, you can also specify exception handlers and interceptors. Interceptors specify the "request-processing lifecycle" for an action. (What happens to the request before and after the Action class fires.) You can specify both global and local lifecycles. If some of your actions respond to AJAX, SOAP, or JSF requests, you can simplify the lifecycle, and even just "pass through" the request, if you like.
Struts 2 is extensible. Very extensible. Every class deployed by the framework is based on an interface. We provide base classes, but you can substitute your own. In the case of Action classes, even the interface is optional. POJO web development is here!
The framework provides general-purpose defaults, and you can start using Struts 2 "out of the box". But you can override any of the defaults in your application's configuration. We provide the base framework, but you can still write your application your way.
The documentation is grouped into three areas.
Our tutorials are designed to get started with the framework soon as possible. We offer an all-purpose "soup to nuts" tutorial as well as specialty tutorials on portlets and database access.
Our FAQs provide a wide range of rapid-fire "HOWTOs" in question and answer format.
Our in-depth guides focus on specific components of the framework, such as Views, the Core framework, and Third-party Extensions.
- See the Migration Guide
- Where do we get the latest version the framework?
- What are some of the framework's best features?
- What are the fundamental differences between Struts and JSF?
- Can you suggest an elevator pitch?
- How can we display dynamic or static images that can be provided as an array of bytes?
- How can we return a text string as the response?
- How can we test applications?
- How can we test Actions?
- How do we upload files?
- How do we download files within the framework?
- How can we force the Action Mappings (struts.xml) to reload?
- How can I test my action output, validation or the action execution outside a container?
- Can we break up a large struts.xml file into smaller pieces?
- Parameters in configuration results
- Make Struts throw exceptions on missing properties, or log them
- How do we get access to the session?
- How do we get invalidate the session?
- How can we access the HttpServletRequest?
- How can we access the HttpServletResponse?
- How can we access request parameters passed into an Action?
- How do we access static parameters from an Action?
- Can we access an Action's Result?
- How do I obtain security details (JAAS)?
- How do we access the Action Invocation, action name or namespace from a view?
- Can I change theme on a per-page basis?
- Can I change templateDir on a per-page basis?
- Can I change templateSuffix on a per-page basis?
- Why isn't our Prepare interceptor being executed?
- Why does my setter not get called by the Params interceptor?
- How do we configure an Interceptor to be used with every Action?
- Why is my action returning "input" when the form is filled out correctly?
- How do I use messages from within the validator?
- How can I fix the "Attribute 'short-circuit'" error message?
- How do we repopulate controls when validation fails?
- How do I unit test my action's validation logic?
- Why does WW ignore my message when its enclosed in CDATA?
- How do we change locales?
- How do I set a global resource bundle?
- How do I decouple XWork LocalizedTextUtil global resource bundle loading from serlvets?
- How do I add I18N to a UI tag, like the textfield tag?
- Can I add I18N outside the Action's context?
- How to support UTF-8 URIEncoding with Tomcat?
- How do I enable encoding in my forms?
- How to escape special chars in resource bundles?
- How do I change the invalid input error message for a particular field?
- Why is the application logging a warning that the Compound Root cannot find a particular Object with a particular property?
- Why do the form tags put table tags around controls?
- Why won't the 'if' tag evaluate a one char string?
- Why does FreeMarker complain that there's an error in my user-directive when I used JSP Tag?
- Can an action tag run another method apart from the default execute method?
- Why didn't my action tag get executed when I have validation errors?
- Why are request parameters appended to our hyperlinks?
- Why doesn't the if tag evaluate test="#parameters.someParam ... " properly
- How do I render a single radio button?
- Why do I get a javax.el.ELException when using OGNL with JSP2.1?
- Why can't I use JSTL-style EL expressions in Struts tags?
- How can I iterate over a range, like with JSTL's forEach tag?
- How can we create our Action objects from the Spring configuration?
- Why would we want to create Action objects from the Spring configuration?
- I'm trying to run the example in the tutorial on Tomcat, and it can't instantiate the VelocityEngine
Issues in Specific Environments
- Does the framework integrate with Hibernate?
- Can we use JSTL with the framework?
- Can we use JUnit with the framework?
- Can we use TestNG with the framework?
- How can we schedule Quartz jobs?
- Can we use Acegi Security with the framework?
We started work on a new User Guide, that should simplify learning process. Please feel free to contribute!
These guides are deprecated and were moved to https://github.com/apache/struts-site
Getting here from there. How are Struts 1 and Struts 2 alike? How are they different? Various issues (and hopefully their solutions!) encountered during migrations to Struts 2. Steps and overall strategies for migrating Struts 1 applications to Struts 2. Development tools to help aid the migration process. A three-part series by Ian Roughley (Sep 2006)
Version Notes 2.5.x
Version Notes 2.3.x
Version Notes 2.2.x
Version Notes 2.1.x
Release Notes 2.0.x
Struts 2.3 to Struts 2.5
Struts 1 to Struts 2
Webwork 2.2 to Struts 2
How are Struts 1 and Struts 2 alike? How are they different?
Various issues (and hopefully their solutions!) encountered during migrations to Struts 2.
Steps and overall strategies for migrating Struts 1 applications to Struts 2.
Development tools to help aid the migration process.
A three-part series by Ian Roughley (Sep 2006)
Core Guide TODOs
Licensing and Copyright
To suggest a change or a correction to any part of the documentation, log in and leave a comment on the appropriate page. We are always looking for help with the documentation!