Google Git
Sign in
apache / struts-site / 56f3b08bc7780019c769eed45d9d80050018f567 / . / content / plugins / spring / index.html
blob: 9e3d5d6566bcc73791fe59f47fd42c41a8dfb1e5 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<meta name="Date-Revision-yyyymmdd" content="20140918"/>
<meta http-equiv="Content-Language" content="en"/>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Spring Plugin</title>
<link href="//fonts.googleapis.com/css?family=Source+Sans+Pro:300,400,600,700,400italic,600italic,700italic" rel="stylesheet" type="text/css">
<link href="//netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.css" rel="stylesheet">
<link href="/css/main.css" rel="stylesheet">
<link href="/css/custom.css" rel="stylesheet">
<link href="/highlighter/github-theme.css" rel="stylesheet">
<script src="//code.jquery.com/jquery-1.11.0.min.js"></script>
<script type="text/javascript" src="/bootstrap/js/bootstrap.js"></script>
<script type="text/javascript" src="/js/community.js"></script>
</head>
<body>
<a href="http://github.com/apache/struts" class="github-ribbon">
<img style="position: absolute; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png" alt="Fork me on GitHub">
</a>
<header>
<nav>
<div role="navigation" class="navbar navbar-default navbar-fixed-top">
<div class="container">
<div class="navbar-header">
<button type="button" data-toggle="collapse" data-target="#struts-menu" class="navbar-toggle">
Menu
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a href="/index.html" class="navbar-brand logo"><img src="/img/struts-logo.svg"></a>
</div>
<div id="struts-menu" class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Home<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/index.html">Welcome</a></li>
<li><a href="/download.cgi">Download</a></li>
<li><a href="/releases.html">Releases</a></li>
<li><a href="/announce-2021.html">Announcements</a></li>
<li><a href="http://www.apache.org/licenses/">License</a></li>
<li><a href="https://www.apache.org/foundation/thanks.html">Thanks!</a></li>
<li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li>
</ul>
</li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Support<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/mail.html">User Mailing List</a></li>
<li><a href="https://issues.apache.org/jira/browse/WW">Issue Tracker</a></li>
<li><a href="/security.html">Reporting Security Issues</a></li>
<li class="divider"></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Migration+Guide">Version Notes</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Security+Bulletins">Security Bulletins</a></li>
<li class="divider"></li>
<li><a href="/maven/project-info.html">Maven Project Info</a></li>
<li><a href="/maven/struts2-core/dependencies.html">Struts Core Dependencies</a></li>
<li><a href="/maven/struts2-plugins/modules.html">Plugin Dependencies</a></li>
</ul>
</li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Documentation<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/birdseye.html">Birds Eye</a></li>
<li><a href="/primer.html">Key Technologies</a></li>
<li><a href="/kickstart.html">Kickstart FAQ</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Home">Wiki</a></li>
<li class="divider"></li>
<li><a href="/getting-started/">Getting Started</a></li>
<li><a href="/security/">Security Guide</a></li>
<li><a href="/core-developers/">Core Developers Guide</a></li>
<li><a href="/tag-developers/">Tag Developers Guide</a></li>
<li><a href="/maven-archetypes/">Maven Archetypes</a></li>
<li><a href="/plugins/">Plugins</a></li>
<li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li>
<li><a href="/tag-developers/tag-reference.html">Tag reference</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/FAQs">FAQs</a></li>
<li><a href="http://cwiki.apache.org/S2PLUGINS/home.html">Plugin registry</a></li>
</ul>
</li>
<li class="dropdown">
<a data-toggle="dropdown" href="#" class="dropdown-toggle">
Contributing<b class="caret"></b>
</a>
<ul class="dropdown-menu">
<li><a href="/youatstruts.html">You at Struts</a></li>
<li><a href="/helping.html">How to Help FAQ</a></li>
<li><a href="/dev-mail.html">Development Lists</a></li>
<li><a href="/contributors/">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/submitting-patches.html">Submitting patches</a></li>
<li><a href="/builds.html">Source Code and Builds</a></li>
<li><a href="/coding-standards.html">Coding standards</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/WW/Contributors+Guide">Contributors Guide</a></li>
<li class="divider"></li>
<li><a href="/release-guidelines.html">Release Guidelines</a></li>
<li><a href="/bylaws.html">PMC Charter</a></li>
<li><a href="/volunteers.html">Volunteers</a></li>
<li><a href="https://gitbox.apache.org/repos/asf?p=struts.git">Source Repository</a></li>
<li><a href="/updating-website.html">Updating the website</a></li>
</ul>
</li>
<li class="apache"><a href="http://www.apache.org/"><img src="/img/apache.png"></a></li>
</ul>
</div>
</div>
</div>
</nav>
</header>
<article class="container">
<section class="col-md-12">
<a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/plugins/spring/index.md" title="Edit this page on GitHub">Edit on GitHub</a>
<a href="../" title="back to Plugins"><< back to Plugins</a>
<h1 class="no_toc" id="spring-plugin">Spring Plugin</h1>
<ul id="markdown-toc">
<li><a href="#description" id="markdown-toc-description">Description</a></li>
<li><a href="#usage" id="markdown-toc-usage">Usage</a></li>
</ul>
<h2 id="description">Description</h2>
<p><a href="http://www.springframework.org">Spring</a> is a lightweight container, providing centralized, automated configuration and wiring of your application objects, using a technique called “Dependency Injection”.</p>
<p>The Spring Plugin works by overriding the Struts <a href="/core-developers/object-factory.html">ObjectFactory</a> to enhance the creation of core framework objects. When an object is to be created, it uses the <code class="highlighter-rouge">class</code> attribute in the Struts configuration to correspond to the <code class="highlighter-rouge">id</code> attribute in the Spring configuration. If not found, the class will try to be created as usual, then be autowired by Spring. In the case of Actions, Spring 2’s <a href="http://www.springframework.org/docs/reference/beans.html#beans-factory-scopes">bean scope feature</a> can be used to scope an Action instance to the session, application, or a custom scope, providing advanced customization above the default per-request scoping.</p>
<blockquote>
<p>Remember:</p>
<p><strong>registering Actions with Spring is not required</strong>. The Spring alternative is there if you need it, but the framework will automatically create Actions objects from the action mappings. But, if you want to use Spring to inject your Actions, the option is there.</p>
</blockquote>
<p><strong>Features</strong></p>
<ul>
<li>
<p>Allow Actions, Interceptors, and Results to be created by Spring</p>
</li>
<li>
<p>Struts-created objects can be autowired by Spring after creation</p>
</li>
<li>
<p>Provides two interceptors that autowire actions, if not using the Spring ObjectFactory</p>
</li>
</ul>
<h2 id="usage">Usage</h2>
<p>To enable Spring integration, simply include struts2-spring-plugin-x-x-x.jar in your application.</p>
<p>If you are using more than one object factory, (for example, by including both the Spring and Plexus plugins in your application,) you will need to set the struts.objectFactory property in <a href="/core-developers/default-properties.html">default.properties</a> or in one of several XML files via <a href="/core-developers/constant-configuration.html">Constant Configuration</a>:</p>
<p><strong>struts.properties</strong></p>
<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>struts.objectFactory = spring
</code></pre></div></div>
<p><strong>struts.xml</strong></p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;struts&gt;</span>
<span class="nt">&lt;constant</span> <span class="na">name=</span><span class="s">"struts.objectFactory"</span> <span class="na">value=</span><span class="s">"spring"</span> <span class="nt">/&gt;</span>
...
<span class="nt">&lt;/struts&gt;</span>
</code></pre></div></div>
<p><strong>Autowiring</strong></p>
<p>The framework enables “autowiring” by default. (Autowiring means to look for objects defined in Spring with the same name as your object property). To change the wiring mode, modify the <code class="highlighter-rouge">spring.autowire</code> property.</p>
<p><strong>Wiring Mode</strong></p>
<div class="language-text highlighter-rouge"><div class="highlight"><pre class="highlight"><code>struts.objectFactory.spring.autoWire = type
</code></pre></div></div>
<p>The <code class="highlighter-rouge">autowire</code> property can be set to several options.</p>
<table>
<thead>
<tr>
<th>option</th>
<th>description</th>
</tr>
</thead>
<tbody>
<tr>
<td>name</td>
<td>Auto-wire by matching the name of the bean in Spring with the name of the property in your action. <strong>This is the default</strong></td>
</tr>
<tr>
<td>type</td>
<td>Auto-wire by looking for a bean registered with Spring of the same type as the property in your action. This requires you to have only one bean of this type registered with Spring</td>
</tr>
<tr>
<td>auto</td>
<td>Spring will attempt to auto-detect the best method for auto-wiring your action</td>
</tr>
<tr>
<td>constructor</td>
<td>Spring will auto-wire the parameters of the bean’s constructor</td>
</tr>
<tr>
<td>no</td>
<td>Turn off externally defined autowiring. Annotation-driven injection and injection based on Springs *Aware-interfaces still applies</td>
</tr>
</tbody>
</table>
<p>By default, the framework will at least try to use Spring to create all its objects. If the object cannot be created by Spring, then the framework will create the object itself.</p>
<p>Enabling Spring integration for other application objects is a two-step process.</p>
<ol>
<li>Configure the Spring listener</li>
</ol>
<p><strong>web.xml</strong></p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;listener&gt;</span>
<span class="nt">&lt;listener-class&gt;</span>org.springframework.web.context.ContextLoaderListener<span class="nt">&lt;/listener-class&gt;</span>
<span class="nt">&lt;/listener&gt;</span>
</code></pre></div></div>
<ol start="2">
<li>Register your objects via the Spring configuration</li>
</ol>
<p><strong>applicationContext.xml</strong></p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</span>
<span class="cp">&lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd"&gt;</span>
<span class="nt">&lt;beans</span> <span class="na">default-autowire=</span><span class="s">"autodetect"</span><span class="nt">&gt;</span>
<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">"personManager"</span> <span class="na">class=</span><span class="s">"com.acme.PersonManager"</span> <span class="na">scope=</span><span class="s">"prototype"</span><span class="nt">/&gt;</span>
...
<span class="nt">&lt;/beans&gt;</span>
</code></pre></div></div>
<p>More applicationContext configuration files needed?</p>
<p>Since the Spring integration uses a standard Listener, it can be configured to support configuration files other than applicationContext.xml. Adding the following to your web.xml will cause Spring’s ApplicationContext to be inititalized from all files matching the given pattern:</p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c">&lt;!-- Context Configuration locations for Spring XML files --&gt;</span>
<span class="nt">&lt;context-param&gt;</span>
<span class="nt">&lt;param-name&gt;</span>contextConfigLocation<span class="nt">&lt;/param-name&gt;</span>
<span class="nt">&lt;param-value&gt;</span>/WEB-INF/applicationContext-*.xml,classpath*:applicationContext-*.xml<span class="nt">&lt;/param-value&gt;</span>
<span class="nt">&lt;/context-param&gt;</span>
</code></pre></div></div>
<p>See the Spring documentation for a full description of this parameter.</p>
<p><strong>Initializing Actions from Spring</strong></p>
<p>Normally, in <code class="highlighter-rouge">struts.xml</code> you specify the class for each Action. When using the default SpringObjectFactory, the framework will ask Spring to create the Action and wire up dependencies as specified by the default auto-wire behavior.</p>
<p>We <strong>strongly</strong> recommend that you find declarative ways of letting Spring know what to provide for your actions. This includes making your beans able to be autowired by either naming your dependent properties on your action the same as the bean defined in Spring which should be provided (to allow for name-based autowiring), or using autowire-by-type and only having one of the required type registered with Spring. It also can include using JDK5 annotations to declare transactional and security requirements rather than having to explicitly set up proxies in your Spring configuration. If you can find ways to let Spring know what it needs to do for your action without needing any explicit configuration in the Spring applicationContext.xml, then you won’t have to maintain this configuration in both places.</p>
<p>However, sometimes you might want the bean to be completely managed by Spring. This is useful, for example, if you wish to apply more complex AOP or Spring-enabled technologies, such as Acegi, to your beans. To do this, all you have to do is configure the bean in your Spring <code class="highlighter-rouge">applicationContext.xml</code> and then <em>change</em> the class attribute from your Action in the <code class="highlighter-rouge">struts.xml</code> to use the bean name defined in Spring instead of the class name.</p>
<p>Your <code class="highlighter-rouge">struts.xml</code> file would then have the Action class attributes changed.</p>
<p><strong>struts.xml</strong></p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;!DOCTYPE struts PUBLIC
"-//Apache Software Foundation//DTD Struts Configuration 2.0//EN"
"http://struts.apache.org/dtds/struts-2.0.dtd"&gt;</span>
<span class="nt">&lt;struts&gt;</span>
<span class="nt">&lt;include</span> <span class="na">file=</span><span class="s">"struts-default.xml"</span><span class="nt">/&gt;</span>
<span class="nt">&lt;package</span> <span class="na">name=</span><span class="s">"default"</span> <span class="na">extends=</span><span class="s">"struts-default"</span><span class="nt">&gt;</span>
<span class="nt">&lt;action</span> <span class="na">name=</span><span class="s">"foo"</span> <span class="na">class=</span><span class="s">"com.acme.Foo"</span><span class="nt">&gt;</span>
<span class="nt">&lt;result&gt;</span>foo.ftl<span class="nt">&lt;/result&gt;</span>
<span class="nt">&lt;/action&gt;</span>
<span class="nt">&lt;/package&gt;</span>
<span class="nt">&lt;package</span> <span class="na">name=</span><span class="s">"secure"</span> <span class="na">namespace=</span><span class="s">"/secure"</span> <span class="na">extends=</span><span class="s">"default"</span><span class="nt">&gt;</span>
<span class="nt">&lt;action</span> <span class="na">name=</span><span class="s">"bar"</span> <span class="na">class=</span><span class="s">"bar"</span><span class="nt">&gt;</span>
<span class="nt">&lt;result&gt;</span>bar.ftl<span class="nt">&lt;/result&gt;</span>
<span class="nt">&lt;/action&gt;</span>
<span class="nt">&lt;/package&gt;</span>
<span class="nt">&lt;/struts&gt;</span>
</code></pre></div></div>
<p>Where you have a Spring bean defined in your <code class="highlighter-rouge">applicationContext.xml</code> named “bar”. Note that the <code class="highlighter-rouge">com.acme.Foo</code> Action did not need to be changed, because it can be autowired.</p>
<p>A typical spring configuration for bar could look as following.</p>
<p><strong>applicationConext.xml</strong></p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">&lt;?xml version="1.0" encoding="UTF-8"?&gt;</span>
<span class="cp">&lt;!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd"&gt;</span>
<span class="nt">&lt;beans</span> <span class="na">default-autowire=</span><span class="s">"autodetect"</span><span class="nt">&gt;</span>
<span class="nt">&lt;bean</span> <span class="na">id=</span><span class="s">"bar"</span> <span class="na">class=</span><span class="s">"com.my.BarClass"</span> <span class="na">singleton=</span><span class="s">"false"</span><span class="nt">/&gt;</span>
...
<span class="nt">&lt;/beans&gt;</span>
</code></pre></div></div>
<p>To use session-scoped components with Spring and Struts, see the <a href="spring-session-components-workarounds.html">Spring Session Components Workarounds</a> analysis.</p>
<p><strong>Class Reloading</strong></p>
<p>The Spring plugin can be configured to automatically reload classes that change in the file system. This feature will enable code changes to be “hot deployed” without having to restart the web container. To enable this feature follow these steps:</p>
<ol>
<li>
<p>Set “struts.devMode” to “true”</p>
</li>
<li>
<p>Set “struts.class.reloading.watchList” to a comma separated list of directories, or jar files (absolute or relative paths)</p>
</li>
<li>
<p>Add this to web.xml:</p>
</li>
</ol>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="nt">&lt;context-param&gt;</span>
<span class="nt">&lt;param-name&gt;</span>contextClass<span class="nt">&lt;/param-name&gt;</span>
<span class="nt">&lt;param-value&gt;</span>org.apache.struts2.spring.ClassReloadingXMLWebApplicationContext<span class="nt">&lt;/param-value&gt;</span>
<span class="nt">&lt;/context-param&gt;</span>
</code></pre></div></div>
<ol start="4">
<li>Add Apache Commons JCI FAM to the classpath. If you are using maven, add this to pom.xml</li>
</ol>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code> <span class="nt">&lt;dependency&gt;</span>
<span class="nt">&lt;groupId&gt;</span>org.apache.commons<span class="nt">&lt;/groupId&gt;</span>
<span class="nt">&lt;artifactId&gt;</span>commons-jci-fam<span class="nt">&lt;/artifactId&gt;</span>
<span class="nt">&lt;version&gt;</span>1.0<span class="nt">&lt;/version&gt;</span>
<span class="nt">&lt;/dependency&gt;</span>
</code></pre></div></div>
<p>Letting the reloading class loader handle all the classes can lead to ClassCastException(s) because instances of the same classes loaded by different class loaders can not be assigned to each other. To prevent this problem we suggest that <code class="highlighter-rouge">struts.class.reloading.acceptClasses</code> is used to limit the classes loaded by the reloading class loader, so only actions are handled by it. This constant supports a comma separated list of regular expressions:</p>
<div class="language-xml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nt">&lt;constant</span> <span class="na">name=</span><span class="s">"struts.class.reloading.acceptClasses"</span> <span class="na">value=</span><span class="s">"com.myproject.example.actions..*"</span> <span class="nt">/&gt;</span>
</code></pre></div></div>
<blockquote>
<p>This feature is experimental, and <strong>should never</strong> be used in production systems.</p>
</blockquote>
<p><strong>Settings</strong></p>
<p>The following settings can be customized. See the <a href="/core-developers/configuration-files.html">developer guide</a>.</p>
<table>
<thead>
<tr>
<th>Setting</th>
<th>Description</th>
<th>Default</th>
<th>Possible Values</th>
</tr>
</thead>
<tbody>
<tr>
<td>struts.objectFactory.spring.autoWire</td>
<td>The autowire strategy</td>
<td>name</td>
<td>name,type,auto, or constructor</td>
</tr>
<tr>
<td>struts.objectFactory.spring.autoWire.alwaysRespect</td>
<td>Whether the autowire strategy should always be used, or if the framework should try to guess the best strategy based on the situation</td>
<td>false for backwards-compatibility</td>
<td>true or false</td>
</tr>
<tr>
<td>struts.objectFactory.spring.useClassCache</td>
<td>Whether to have Spring use its class cache or not</td>
<td>true</td>
<td>true or false</td>
</tr>
<tr>
<td>struts.class.reloading.watchList</td>
<td>List of jar files or directories to watch for changes</td>
<td>null</td>
<td>Comma separated list of absolute or relative paths to jars or directories</td>
</tr>
<tr>
<td>struts.class.reloading.acceptClasses</td>
<td>List of regular expressions of accepted class names</td>
<td>null</td>
<td>Comma separated list of regular expressions of classes that will be loaded by the reloading class loader(we suggest to add regular expressions so only action classes are handled by the reloading class loader)</td>
</tr>
<tr>
<td>struts.class.reloading.reloadConfig</td>
<td>Reload the runtime configuration (action mappings, results etc) when a change is detected in one of the watched directories</td>
<td>false</td>
<td>true or false</td>
</tr>
<tr>
<td>DEPRECATED: struts.objectFactory.spring.enableAopSupport</td>
<td>Uses different logic to construct beans to allow support AOP, it uses an old approach to create a bean, switch this flag if you have problems with Spring beans and AOP</td>
<td>false</td>
<td>true or false</td>
</tr>
</tbody>
</table>
<p><strong>Installation</strong></p>
<p>This plugin can be installed by copying the plugin jar into your application’s <code class="highlighter-rouge">/WEB-INF/lib</code> directory. No other files need to be copied or created.</p>
</section>
</article>
<footer class="container">
<div class="col-md-12">
Copyright &copy; 2000-2018 <a href="http://www.apache.org/">The Apache Software Foundation </a>.
All Rights Reserved.
</div>
<div class="col-md-12">
Apache Struts, Struts, Apache, the Apache feather logo, and the Apache Struts project logos are
trademarks of The Apache Software Foundation.
</div>
<div class="col-md-12">Logo and website design donated by <a href="https://softwaremill.com/">SoftwareMill</a>.</div>
</footer>
<script>!function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (!d.getElementById(id)) {
js = d.createElement(s);
js.id = id;
js.src = "//platform.twitter.com/widgets.js";
fjs.parentNode.insertBefore(js, fjs);
}
}(document, "script", "twitter-wjs");</script>
<script src="https://apis.google.com/js/platform.js" async="async" defer="defer"></script>
<div id="fb-root"></div>
<script>(function (d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s);
js.id = id;
js.src = "//connect.facebook.net/en_GB/all.js#xfbml=1";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>
</body>
</html>