Added: websites/production/struts/content/core-developers/action-configuration.html ============================================================================== --- websites/production/struts/content/core-developers/action-configuration.html (added) +++ websites/production/struts/content/core-developers/action-configuration.html Thu Jun 1 11:35:58 2017 @@ -0,0 +1,1007 @@ +<!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>Action Configuration</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="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.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="/downloads.html">Downloads</a></li> + <li><a href="/announce.html">Announcements</a></li> + <li><a href="http://www.apache.org/licenses/";>License</a></li> + <li><a href="http://apache.org/foundation/thanks.html";>Thanks!</a></li> + <li><a href="http://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="/maven/project-info.html">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="/docs/tutorials.html">Tutorials</a></li> + <li><a href="/docs/faqs.html">FAQs</a></li> + <li><a href="/docs/guides.html">Guides</a></li> + <li class="divider"></li> + <li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li> + <li><a href="/docs/plugins.html">Plugin APIs</a></li> + <li><a href="/docs/tag-reference.html">Tag reference</a></li> + <li><a href="http://cwiki.apache.org/S2PLUGINS/home.html";>Plugin registry</a></li> + <li class="divider"></li> + <li><a href="/security/">Security Guide (WIP)</a></li> + <li><a href="/core-developers/">Core Developers Guide (WIP)</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 class="divider"></li> + <li><a href="/submitting-patches.html">Submitting patches</a></li> + <li><a href="/builds.html">Source Code</a></li> + <li><a href="/coding-standards.html">Coding standards</a></li> + <li class="divider"></li> + <li><a href="/releases.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://git-wip-us.apache.org/repos/asf?p=struts.git";>Source Repository</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 href="index.html" title="back to Core Developers Guide"><< back to Core Developers Guide</a> + <h1 id="action-configuration">Action Configuration</h1> + +<p>The action mappings are the basic âunit-of-workâ in the framework. Essentially, the action maps an identifier to a handler class. When a request matches the actionâs name, the framework uses the mapping to determine how to process the request.</p> + +<p>#####Action Mappings#####</p> + +<p>The action mapping can specify a set of result types, a set of exception handlers, and an interceptor stack. Only the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>name +</code></pre> +</div> +<p>attribute is required. The other attributes can also be provided at package scope.</p> + +<p><strong>A Logon Action</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code><action name="Logon" class="tutorial.Logon"> + <result type="redirectAction">Menu</result> + <result name="input">/Logon.jsp</result> +</action> +</code></pre> +</div> + +<p>When using <em>Convention Plugin</em> the action mapping can be configured with annotations:</p> + +<p><strong>A Logon Action with annotations</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code>package tutorial + +@Action("Logon") // actually that is not necessary as it is added by convention +@Results( + @Result(type="redirectAction", location="Menu"), + @Result(name="input", location="/Logon.jsp") +) +public class Logon { +</code></pre> +</div> + +<p>#####Action Names#####</p> + +<p>In a web application, the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>name +</code></pre> +</div> +<p>attribute is matched as part of the location requested by a browser (or other HTTP client). The framework will drop the host and application name and the extension and match whatâs in the middle: the action name. So, a request for</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>http://www.planetstruts.org/struts2-mailreader/Welcome.action +</code></pre> +</div> +<p>will map to the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>Welcome +</code></pre> +</div> +<p>action.</p> + +<p>Within an application a link to an action is usually generated by a Struts Tag. The tag can specify the action by name, and the framework will render the default extension and anything else that is needed. Forms may also submit directly to a Struts Action name (rather than a ârawâ URI).</p> + +<p><strong>A Hello Form</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code><s:form action="Hello"> + <s:textfield label="Please enter your name" name="name"/> + <s:submit/> +</s:form> + +</code></pre> +</div> + +<p><strong>Action Names With Slashes</strong></p> + +<p>If your action names have slashes in them (for example,</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><action name="admin/home" class="tutorial.Admin"/> +</code></pre> +</div> +<p>) you need to specifically allow slashes in your action names via a constant in the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.xml +</code></pre> +</div> +<p>file by specifying</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><constant name="struts.enable.SlashesInActionNames" value="true"/> +</code></pre> +</div> +<p>. See <a href="https://issues\.apache\.org/jira/browse/WW\-1383";>JIRA Issue WW-1383</a>^[https://issues.apache.org/jira/browse/WW-1383] for discussion as there are side effects to setting this property to</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>true +</code></pre> +</div> +<p>.</p> + +<p><strong>Action Names with Dots and Dashes</strong></p> + +<p>Although action naming is pretty flexible, one should pay attention when using dots (eg. create.user) and/or dashes (eg. my-action). While the dot notation has no known side effects at this time, the dash notation will cause problems with the generated JavaScript for certain tags and themes. Use with caution, and always try to use camelcase action names (eg. createUser) or underscores (eg. my_action).</p> + +<p><strong>Allowed action names</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code>DefaultActionMapper +</code></pre> +</div> +<p>is using pre-defined RegEx to check if action name matches allowed names. The default RegEx is defined as follow: </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>[a-zA-Z0-9._!/\-]* +</code></pre> +</div> +<p>- if at some point this doesnât match your action naming schema you can define your own RegEx and override the default using constant named </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.allowed.action.names +</code></pre> +</div> +<p>, e.g.:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><struts> + <constant name="struts.allowed.action.names" value="[a-z{}]"*/> + ... +</struts> +</code></pre> +</div> + +<p><strong>NOTE</strong>: Please be aware that action names not matching the RegEx will rise an exception.</p> + +<p>#####Action Methods#####</p> + +<p>The default entry method to the handler class is defined by the Action interface.</p> + +<p><strong>Action interface</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code>public interface Action { + public String execute() throws Exception; +} + +</code></pre> +</div> + +<p>(information) Implementing the Action interface is optional. If Action is not implemented, the framework will use reflection to look for an</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute +</code></pre> +</div> +<p>method.</p> + +<p>Sometimes, developers like to create more than one entry point to an Action. For example, in the case of a data-access Action, a developer might want separate entry-points for</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>create +</code></pre> +</div> +<p>,</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>retrieve +</code></pre> +</div> +<p>,</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>update +</code></pre> +</div> +<p>, and</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>delete +</code></pre> +</div> +<p>. A different entry point can be specified by the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>method +</code></pre> +</div> +<p>attribute.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><action name="delete" class="example.CrudAction" method="delete"> + ... + +</code></pre> +</div> + +<p>(!) If there is no</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute +</code></pre> +</div> +<p>method and no other method specified in the configuration the framework will throw an exception.</p> + +<p> </p> + +<p><em>Convention Plugin</em> allows that by annotating methods:</p> + +<p><strong>Annotated action method</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code>@Action("crud") +public class CrudAction { + @Action("delete") + public String delete() { + ... + +</code></pre> +</div> + +<p>#####Wildcard Method#####</p> + +<p>Many times, a set of action mappings will share a common pattern. For example, all your</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>edit +</code></pre> +</div> +<p>actions might start with the word âeditâ, and call the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>edit +</code></pre> +</div> +<p>method on the Action class. The</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>delete +</code></pre> +</div> +<p>actions might use the same pattern, but call the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>delete +</code></pre> +</div> +<p>method instead.</p> + +<p>Rather than code a separate mapping for each action class that uses this pattern, you can write it once as a wildcard mapping.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><action name="*Crud" class="example.Crud" method="{1}"> + ... + +</code></pre> +</div> + +<p>Here, a reference to âeditCrudâ will call the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>edit +</code></pre> +</div> +<p>method on an instance of the Crud Action class. Likewise, a reference to âdeleteCrudâ will call the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>delete +</code></pre> +</div> +<p>method instead.</p> + +<p>Another common approach is to postfix the method name and set it off with an exclamation point (aka âbangâ), underscore, or other special character.</p> + +<ul> + <li> + <p>âaction=Crud_inputâ</p> + </li> + <li> + <p>âaction=Crud_deleteâ</p> + </li> +</ul> + +<p>To use a postfix wildcard, just move the asterisk and add an underscore.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><action name="Crud_*" class="example.Crud" method="{1}"> + +</code></pre> +</div> + +<p>From the frameworkâs perspective, a wildcard mapping creates a new âvirtualâ mapping with all the same attributes as a conventional, static mapping. As a result, you can use the expanded wildcard name as the name of validation, type conversion, and message resource files, just as if it were an Action name (which it is!).</p> + +<ul> + <li></li> +</ul> + +<div class="highlighter-rouge"><pre class="highlight"><code>Crud_input-validation.xml +</code></pre> +</div> + +<ul> + <li></li> +</ul> + +<div class="highlighter-rouge"><pre class="highlight"><code>Crud_delete-conversion.xml +</code></pre> +</div> + +<p>If Wildcard Method mapping uses a â!â in the action name, the Wildcard Method will overlap with another flexible approach to mapping, . To use action names that include the â!â character, set struts.enable.DynamicMethodInvocation to FALSE in the application configuration.</p> + +<blockquote> + +</blockquote> + +<p>#####Dynamic Method Invocation#####</p> + +<p>Thereâs a feature embedded in Struts 2 that lets the â!â (bang) character invoke a method other than</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute +</code></pre> +</div> +<p>. It is called âDynamic Method Invocationâ aka DMI.</p> + +<p>DMI will use the string following a â!â character in an action name as the name of a method to invoke (instead of</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute +</code></pre> +</div> +<p>). A reference to â</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>Category!create.action +</code></pre> +</div> +<p>â, says to use the âCategoryâ action mapping, but call the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>create +</code></pre> +</div> +<p>method instead.</p> + +<p>Another way to use DMI is to provide HTTP parameters prefixed with â</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>method: +</code></pre> +</div> +<p>â. For example in the URL it could be â</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>Category.action?method:create=foo +</code></pre> +</div> +<p>â, the parameter value is ignored. In POST-Requests that can be used e.g. with a hidden parameter (</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><s:hidden name="method:create" value="foo" /> +</code></pre> +</div> +<p>) or along with a button (</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><s:submit method="create" /> +</code></pre> +</div> +<p>).</p> + +<p>For Struts 2, we added a switch to disable DMI for two reasons. First, DMI can cause security issues if POJO actions are used. Second, DMI overlaps with the Wildcard Method feature that we brought over from Struts 1 (and from Cocoon before that). If you have security concerns, or would like to use the â!â character with Wildcard Method actions, then set</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.enable.DynamicMethodInvocation +</code></pre> +</div> +<p>to</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>FALSE +</code></pre> +</div> +<p>in the application configuration.</p> + +<p>The framework does support DMI, but there are problems with way DMI is implemented. Essentially, the code scans the action name for a â!â character, and finding one, tricks the framework into invoking the other method instead of</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute +</code></pre> +</div> +<p>. The other method is invoked, but it uses the same configuration as the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute +</code></pre> +</div> +<p>method, including validations. The framework âbelievesâ it is invoking the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>Category +</code></pre> +</div> +<p>action with the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute +</code></pre> +</div> +<p>method.</p> + +<p>The Wildcard Method feature is implemented differently. When a Wildcard Method action is invoked, the framework acts as if the matching action had been hardcoded in the configuration. The framework âbelievesâ itâs executing the action</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>Category!create +</code></pre> +</div> +<p>and âknowsâ it is executing the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>create +</code></pre> +</div> +<p>method of the corresponding Action class. Accordingly, we can add for a Wildcard Method action mapping its own validations, message resources, and type converters, just like a conventional action mapping. For this reason, the is preferred.</p> + +<p><strong>Strict DMI</strong></p> + +<p>In Struts 2.3, an option was added to restrict the methods that DMI can invoke. First, set the attribute</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>strict-method-invocation="true" +</code></pre> +</div> +<p>on your</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><package> +</code></pre> +</div> +<p>element. This tells Struts to reject any method that is not explicitly allowed via either the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>method +</code></pre> +</div> +<p>attribute (including wildcards) or the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><allowed-methods> +</code></pre> +</div> +<p>tag. Then specify</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><allowed-methods> +</code></pre> +</div> +<p>as a comma-separated list of method names in your</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><action> +</code></pre> +</div> +<p>. (If you specify a</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>method +</code></pre> +</div> +<p>attribute for your action, you do not need to list it in</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><allowed-methods> +</code></pre> +</div> +<p>.)</p> + +<p>Note that you can specify</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><allowed-methods> +</code></pre> +</div> +<p>even without</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>strict-method-invocation +</code></pre> +</div> +<p>. This restricts access only for the specific actions that have</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><allowed-methods> +</code></pre> +</div> +<p>.</p> + +<p><strong>Example struts.xml</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code><span class="cp"><?xml version="1.0" encoding="UTF-8" ?></span> +<span class="cp"><!DOCTYPE struts PUBLIC + "-//Apache Software Foundation//DTD Struts Configuration 2.3//EN" + "http://struts.apache.org/dtds/struts-2.3.dtd"></span> +<span class="nt"><struts></span> + + <span class="nt"><constant</span> <span class="na">name=</span><span class="s">"struts.enable.DynamicMethodInvocation"</span> <span class="na">value=</span><span class="s">"true"</span><span class="nt">/></span> + + <span class="nt"><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="na">strict-method-invocation=</span><span class="s">"true"</span><span class="nt">></span> + + <span class="nt"><action</span> <span class="na">name=</span><span class="s">"index"</span> <span class="na">class=</span><span class="s">"org.apache.struts2.examples.actions.Index"</span><span class="nt">></span> + <span class="nt"><result</span> <span class="na">name=</span><span class="s">"success"</span> <span class="na">type=</span><span class="s">"redirectAction"</span><span class="nt">></span>hello<span class="nt"></result></span> + <span class="nt"></action></span> + + <span class="nt"><action</span> <span class="na">name=</span><span class="s">"hello"</span> <span class="na">class=</span><span class="s">"org.apache.struts2.examples.actions.HelloAction"</span><span class="nt">></span> + <span class="nt"><result</span> <span class="na">name=</span><span class="s">"success"</span><span class="nt">></span>/WEB-INF/content/hello.jsp<span class="nt"></result></span> + <span class="nt"><result</span> <span class="na">name=</span><span class="s">"redisplay"</span> <span class="na">type=</span><span class="s">"redirectAction"</span><span class="nt">></span>hello<span class="nt"></result></span> + <span class="nt"><allowed-methods></span>add<span class="nt"></allowed-methods></span> + <span class="nt"></action></span> + + <span class="nt"></package></span> +<span class="nt"></struts></span> + +</code></pre> +</div> + +<p><strong>Strict Method Invocation</strong></p> + +<p>In Struts 2.5 the Strict DMI was extended and itâs called <strong>Strict Method Invocation</strong> aka SMI. You can imagine that the DMI is a âborder policeâ, where SMI is a âtax policeâ and keeps eye on internals. With this version, SMI is enabled by default (</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>strict-method-invocation +</code></pre> +</div> +<p>attribute is set to </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>true +</code></pre> +</div> +<p>by default in </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts-default +</code></pre> +</div> +<p>package), you have option to disable it per package - there is no global switch to disable SMI for the whole application. To gain advantage of new configuration option please use the latest DTD definition:</p> + +<p><strong>Struts 2.5 DTD</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code><span class="cp"><?xml version="1.0" encoding="UTF-8" ?></span> +<span class="cp"><!DOCTYPE struts PUBLIC + "-//Apache Software Foundation//DTD Struts Configuration 2.5//EN" + "http://struts.apache.org/dtds/struts-2.5.dtd"></span> +<span class="nt"><struts></span> +... +<span class="nt"></struts></span> +</code></pre> +</div> + +<p>SMI works in the following way:</p> + +<ul> + <li></li> +</ul> + +<div class="highlighter-rouge"><pre class="highlight"><code><allowed-methods> +</code></pre> +</div> +<p> /</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>@AllowedMethods +</code></pre> +</div> +<p> is defined per action - SMI works without switching it on but just for those actions (plus adding</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><global-allowed-methods/> +</code></pre> +</div> +<p>)</p> + +<ul> + <li>SMI is enabled but no</li> +</ul> + +<div class="highlighter-rouge"><pre class="highlight"><code><allowed-methods> +</code></pre> +</div> +<p> /</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>@AllowedMethods +</code></pre> +</div> +<p> are defined - SMI works but only with</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><global-allowed-methods/> +</code></pre> +</div> + +<ul> + <li>SMI is disabled - call to any action method is allowed that matches the default RegEx - </li> +</ul> + +<div class="highlighter-rouge"><pre class="highlight"><code>([A-Za-z0-9_$]*) +</code></pre> +</div> + +<p>You can redefine the default RegEx by using a constant as follow </p> + +<div class="highlighter-rouge"><pre class="highlight"><code><constant name="struts.strictMethodInvocation.methodRegex" value="([a-zA-Z]*)"/> +</code></pre> +</div> + +<p>When using wildcard mapping in actionsâ definitions SMI works in two ways:</p> + +<table> + <tbody> + <tr> + </tr> + </tbody> +</table> + +<table> + <tbody> + <tr> + </tr> + </tbody> +</table> + +<table> + <tbody> + <tr> + <td>+ SMI is disabled - any wildcard will be substituted with the default RegEx, ie.: <action name=âPerson*â method=âperform*â> will be translated into allowedMethod = âregex:perform([A-Za-z0-9_$]*)â.</td> + </tr> + </tbody> +</table> + +<table> + <tbody> + <tr> + </tr> + </tbody> +</table> + +<table> + <tbody> + <tr> + <td>+ SMI is enabled - no wildcard substitution will happen, you must strictly define which methods can be accessed by annotations or <allowed-method/> tag.</td> + </tr> + </tbody> +</table> + +<table> + <tbody> + <tr> + </tr> + </tbody> +</table> + +<table> + <tbody> + <tr> + </tr> + </tbody> +</table> + +<p>You can configure SMI per</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><action/> +</code></pre> +</div> +<p>using </p> + +<div class="highlighter-rouge"><pre class="highlight"><code><allowed-methods/> +</code></pre> +</div> +<p>tag or via </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>@AllowedMethod +</code></pre> +</div> +<p>annotation plus using per </p> + +<div class="highlighter-rouge"><pre class="highlight"><code><package/> +</code></pre> +</div> +<p> </p> + +<div class="highlighter-rouge"><pre class="highlight"><code><global-allowed-methods/> +</code></pre> +</div> +<p>, see the examples below:</p> + +<p><strong>SMI via struts.xml</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code><package ...> + ... + <global-allowed-methods>execute,input,back,cancel,browse</global-allowed-methods> + ... + + <action name="Bar"> + <allowed-methods>foo,bar</allowed-methods> + </action> + + ... +</package> + + +</code></pre> +</div> + +<p><strong>SMI via annotation on action class level</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code>@AllowedMethods("end") +public class ClassLevelAllowedMethodsAction { + public String execute() { + return ... + } +} +</code></pre> +</div> + +<p><strong>SMI via annotation on package level (in package-info.java)</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code>@org.apache.struts2.convention.annotation.AllowedMethods({"home", "start"}) +package org.apache.struts2.convention.actions.allowedmethods; +</code></pre> +</div> + +<p>Allowed methods can be defined as:</p> + +<ul> + <li>literals ie. in xml:</li> +</ul> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute,cancel +</code></pre> +</div> +<p>or in annotation:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><span class="w"> </span><span class="p">{</span><span class="nt">"execute"</span><span class="err">,</span><span class="w"> </span><span class="nt">"cancel"</span><span class="err">}</span><span class="w"> +</span></code></pre> +</div> + +<ul> + <li>patterns when using with wildcard mapping, i.e</li> +</ul> + +<div class="highlighter-rouge"><pre class="highlight"><code><action ... method="do{2}"/> +</code></pre> +</div> + +<ul> + <li>RegExs using</li> +</ul> + +<div class="highlighter-rouge"><pre class="highlight"><code>regex: +</code></pre> +</div> +<p> prefix, ie: </p> + +<div class="highlighter-rouge"><pre class="highlight"><code><global-allowed-methods>execute,input,cancel,regex:user([A-Z]*)</global-allowed-methods> +</code></pre> +</div> + +<p>Please be aware when using your own Configurationprovider that the logic to set allowed methods is defined in built-in providers - XmlConfigurationProvider and PackageBasedActionConfigBuilder - and you must replicate such logic in your code as by default only execute method is allowed, even when SMI is disabled.</p> + +<table> + <tbody> + <tr> + </tr> + </tbody> +</table> + +<p>#####ActionSupport Default#####</p> + +<p>If the class attribute in an action mapping is left blank, the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>com.opensymphony.xwork2.ActionSupport +</code></pre> +</div> +<p>class is used as a default.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><action name="Hello"> + // ... +</action> + +</code></pre> +</div> + +<p>(information) The ActionSupport class has an</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute +</code></pre> +</div> +<p>method that returns âsuccessâ and an</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>input +</code></pre> +</div> +<p>method that returns âinputâ. +(information) To specify a different class as the default Action class, set the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>default-class-ref +</code></pre> +</div> +<p>package attribute.</p> + +<p>(light-on) For more about using wildcards, see <a href="wildcard-mappings.html">Wildcard Mappings</a>.</p> + +<p>#####Post-Back Default#####</p> + +<p>A good practice is to link to actions rather than pages. Linking to actions encapsulates which server page renders, and ensures that an Action class can fire before a page renders.</p> + +<p>Another common workflow stategy is to first render a page using an alternate method, like</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>input +</code></pre> +</div> +<p>and then have it submit back to the default</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute +</code></pre> +</div> +<p>method.</p> + +<p>Using these two strategies together creates an opportunity to use a âpost-backâ form that doesnât specify an action. The form simply submits back to the action that created it.</p> + +<p><strong>Posting Back</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code><s:form> + <s:textfield label="Please enter your name" name="name"/> + <s:submit/> +</s:form> + +</code></pre> +</div> + +<p>#####Action Default#####</p> + +<p>Usually, if an action is requested, and the framework canât map the request to an action name, the result will be the usual â404 - Page not foundâ error. But, if you would prefer that an omnibus action handle any unmatched requests, you can specify a default action. If no other action matches, the default action is used instead.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><package name="Hello" extends="action-default"> + + <default-action-ref name="UnderConstruction"/> + + <action name="UnderConstruction"> + <result>/UnderConstruction.jsp</result> + </action> + + ... + +</code></pre> +</div> + +<p>There are no special requirements for the default action. Each package can have its own default action, but there should only be one default action per namespace.</p> + +<p><strong>(!) One to a Namespace</strong></p> + +<blockquote> + +</blockquote> + +<blockquote> + +</blockquote> + +<blockquote> + <p>The default action features should be set up so that there is only one default action per namespace. If you have multiple packages declaring a default action with the same namespace, there is no guarantee which action will be the default.</p> +</blockquote> + +<blockquote> + +</blockquote> + +<p><strong>Wildcard Default</strong></p> + +<p>Using wildcards is another approach to default actions. A wildcard action at the end of the configuration can be used to catch unmatched references.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><action name="*"> + <result>/{1}.jsp</result> +</action> + +</code></pre> +</div> + +<p>When a new action is needed, just add a stub page.</p> + +<p>(!) Itâs important to put a âcatchallâ wildcard mapping like this at the end of your configuration so it wonât attempt to map every request!</p> + + </section> +</article> + + +<footer class="container"> + <div class="col-md-12"> + Copyright © 2000-2016 <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> + + +<script> +$(function() { + return $("h2, h3, h4, h5, h6").each(function(i, el) { + var $el, id; + $el = $(el); + id = $el.attr('id'); + if (id) { + $el.removeAttr('id'); + return $el.before($("<a />").addClass('anchor').attr('name', id)); + } + }); +}); +</script> + +</body> +</html>
Added: websites/production/struts/content/core-developers/action-event-listener.html ============================================================================== --- websites/production/struts/content/core-developers/action-event-listener.html (added) +++ websites/production/struts/content/core-developers/action-event-listener.html Thu Jun 1 11:35:58 2017 @@ -0,0 +1,216 @@ +<!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>ActionEventListener</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="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.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="/downloads.html">Downloads</a></li> + <li><a href="/announce.html">Announcements</a></li> + <li><a href="http://www.apache.org/licenses/";>License</a></li> + <li><a href="http://apache.org/foundation/thanks.html";>Thanks!</a></li> + <li><a href="http://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="/maven/project-info.html">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="/docs/tutorials.html">Tutorials</a></li> + <li><a href="/docs/faqs.html">FAQs</a></li> + <li><a href="/docs/guides.html">Guides</a></li> + <li class="divider"></li> + <li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li> + <li><a href="/docs/plugins.html">Plugin APIs</a></li> + <li><a href="/docs/tag-reference.html">Tag reference</a></li> + <li><a href="http://cwiki.apache.org/S2PLUGINS/home.html";>Plugin registry</a></li> + <li class="divider"></li> + <li><a href="/security/">Security Guide (WIP)</a></li> + <li><a href="/core-developers/">Core Developers Guide (WIP)</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 class="divider"></li> + <li><a href="/submitting-patches.html">Submitting patches</a></li> + <li><a href="/builds.html">Source Code</a></li> + <li><a href="/coding-standards.html">Coding standards</a></li> + <li class="divider"></li> + <li><a href="/releases.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://git-wip-us.apache.org/repos/asf?p=struts.git";>Source Repository</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 href="index.html" title="back to Core Developers Guide"><< back to Core Developers Guide</a> + <h1 id="actioneventlistener">ActionEventListener</h1> + +<p>A ActionEventListener can be used to add some logic when actionâs instance is created or when exception occurred during processing the action.</p> + +<p>#####Configuration#####</p> + +<p>Right now there can be only one instance of ActionEventListener for the whole Struts2 application. You can configure it via struts.xml by adding bean definition:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code> +<bean type="com.opensymphony.xwork2.ActionEventListener" class="com.demo.MyActionEventListener"/> + +</code></pre> +</div> + +<p>#####Examples#####</p> + +<div class="highlighter-rouge"><pre class="highlight"><code> +public class MyActionEventListener implements ActionEventListener { + + public Object prepare(Object action, ValueStack stack) { + if (action instanceof MyBaseAction) { + ((MyBaseAction)action).setUserService(stack.findValue("userService")); + } + } + + public String handleException(Throwable t, ValueStack stack) { + if (t instanceof MyBusinessException) { + return stack.findString("defaultBusinesResult"); + } + return null; + } +} + +</code></pre> +</div> + + </section> +</article> + + +<footer class="container"> + <div class="col-md-12"> + Copyright © 2000-2016 <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> + + +<script> +$(function() { + return $("h2, h3, h4, h5, h6").each(function(i, el) { + var $el, id; + $el = $(el); + id = $el.attr('id'); + if (id) { + $el.removeAttr('id'); + return $el.before($("<a />").addClass('anchor').attr('name', id)); + } + }); +}); +</script> + +</body> +</html> Added: websites/production/struts/content/core-developers/action-mapper-and-action-mapping.html ============================================================================== --- websites/production/struts/content/core-developers/action-mapper-and-action-mapping.html (added) +++ websites/production/struts/content/core-developers/action-mapper-and-action-mapping.html Thu Jun 1 11:35:58 2017 @@ -0,0 +1,223 @@ +<!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>Action Mapper & Action Mapping</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="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.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="/downloads.html">Downloads</a></li> + <li><a href="/announce.html">Announcements</a></li> + <li><a href="http://www.apache.org/licenses/";>License</a></li> + <li><a href="http://apache.org/foundation/thanks.html";>Thanks!</a></li> + <li><a href="http://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="/maven/project-info.html">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="/docs/tutorials.html">Tutorials</a></li> + <li><a href="/docs/faqs.html">FAQs</a></li> + <li><a href="/docs/guides.html">Guides</a></li> + <li class="divider"></li> + <li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li> + <li><a href="/docs/plugins.html">Plugin APIs</a></li> + <li><a href="/docs/tag-reference.html">Tag reference</a></li> + <li><a href="http://cwiki.apache.org/S2PLUGINS/home.html";>Plugin registry</a></li> + <li class="divider"></li> + <li><a href="/security/">Security Guide (WIP)</a></li> + <li><a href="/core-developers/">Core Developers Guide (WIP)</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 class="divider"></li> + <li><a href="/submitting-patches.html">Submitting patches</a></li> + <li><a href="/builds.html">Source Code</a></li> + <li><a href="/coding-standards.html">Coding standards</a></li> + <li class="divider"></li> + <li><a href="/releases.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://git-wip-us.apache.org/repos/asf?p=struts.git";>Source Repository</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 href="index.html" title="back to Core Developers Guide"><< back to Core Developers Guide</a> + <h1 id="action-mapper--action-mapping">Action Mapper & Action Mapping</h1> + +<p>The ActionMapper fetches the ActionMapping object corresponding to a given request. Essentially, the ActionMapping is a data transfer object that collects together details such as the Action class and method to execute. The mapping is utilized by the Dispatcher and various user interface components. It is customizable through</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.mapper.class +</code></pre> +</div> +<p>entry in</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.properties +</code></pre> +</div> +<p>.</p> + +<p>####Customize####</p> + +<p>Custom ActionMapper must implement ActionMapper interface and have a default constructor.</p> + +<blockquote> + +</blockquote> + +<div class="highlighter-rouge"><pre class="highlight"><code> +struts.mapper.class=foo.bar.MyCustomActionMapper + +</code></pre> +</div> + +<div class="highlighter-rouge"><pre class="highlight"><code> +public class MyCustomActionMapper implements ActionMapper { + public ActionMapping getMapping(HttpServletRequest request, + ConfigurationManager configManager) { + .... + } + + public String getUriFromActionMapping(ActionMapping mapping) { + .... + } +} + +</code></pre> +</div> + + </section> +</article> + + +<footer class="container"> + <div class="col-md-12"> + Copyright © 2000-2016 <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> + + +<script> +$(function() { + return $("h2, h3, h4, h5, h6").each(function(i, el) { + var $el, id; + $el = $(el); + id = $el.attr('id'); + if (id) { + $el.removeAttr('id'); + return $el.before($("<a />").addClass('anchor').attr('name', id)); + } + }); +}); +</script> + +</body> +</html> Added: websites/production/struts/content/core-developers/action-mapper.html ============================================================================== --- websites/production/struts/content/core-developers/action-mapper.html (added) +++ websites/production/struts/content/core-developers/action-mapper.html Thu Jun 1 11:35:58 2017 @@ -0,0 +1,542 @@ +<!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>ActionMapper</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="//ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.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="/downloads.html">Downloads</a></li> + <li><a href="/announce.html">Announcements</a></li> + <li><a href="http://www.apache.org/licenses/";>License</a></li> + <li><a href="http://apache.org/foundation/thanks.html";>Thanks!</a></li> + <li><a href="http://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="/maven/project-info.html">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="/docs/tutorials.html">Tutorials</a></li> + <li><a href="/docs/faqs.html">FAQs</a></li> + <li><a href="/docs/guides.html">Guides</a></li> + <li class="divider"></li> + <li><a href="/maven/struts2-core/apidocs/index.html">Struts Core API</a></li> + <li><a href="/docs/plugins.html">Plugin APIs</a></li> + <li><a href="/docs/tag-reference.html">Tag reference</a></li> + <li><a href="http://cwiki.apache.org/S2PLUGINS/home.html";>Plugin registry</a></li> + <li class="divider"></li> + <li><a href="/security/">Security Guide (WIP)</a></li> + <li><a href="/core-developers/">Core Developers Guide (WIP)</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 class="divider"></li> + <li><a href="/submitting-patches.html">Submitting patches</a></li> + <li><a href="/builds.html">Source Code</a></li> + <li><a href="/coding-standards.html">Coding standards</a></li> + <li class="divider"></li> + <li><a href="/releases.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://git-wip-us.apache.org/repos/asf?p=struts.git";>Source Repository</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 href="index.html" title="back to Core Developers Guide"><< back to Core Developers Guide</a> + <h1 id="actionmapper">ActionMapper</h1> + +<p>####Description####</p> + +<p>The ActionMapper interface provides a mapping between HTTP requests and action invocation requests and vice-versa.</p> + +<p>When given an HttpServletRequest, the ActionMapper may return null if no action invocation request matches or it may return an {{ActionMapping}} that describes an action invocation for the framework to try.</p> + +<p>The ActionMapper is not required to guarantee that the {{ActionMapping}} returned be a real action or otherwise ensure a valid request. Accordingly, most ActionMappers do not need to consult the Struts configuration just to determine if a request should be mapped.</p> + +<p>Just as requests can be mapped from HTTP to an action invocation, the opposite is true as well. However, because HTTP requests (when shown in HTTP responses) must be in String form, a String is returned rather than an actual request object.</p> + +<p>####DefaultActionMapper####</p> + +<p>Default action mapper implementation, using the standard</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>*.[ext] +</code></pre> +</div> +<p> (where ext usually <strong>action</strong>) pattern. The extension is looked up from the Struts configuration key {<b>{struts.action.extension}}.</p> + +<p>To help with dealing with buttons and other related requirements, this mapper (and other {{ActionMapper}}s, we hope) has the ability to name a button with some predefined prefix and have that button name alter the execution behaviour. The four prefixes are:</p> + +<ul> + <li>Method prefix - </li> +</ul> + +<div class="highlighter-rouge"><pre class="highlight"><code>method:default +</code></pre> +</div> + +<ul> + <li>Action prefix - </li> +</ul> + +<div class="highlighter-rouge"><pre class="highlight"><code>action:dashboard +</code></pre> +</div> + +<p>In addition to these four prefixes, this mapper also understands the action naming pattern of</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>foo!bar +</code></pre> +</div> +<p> in either the extension form (eg: </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>foo!bar.action +</code></pre> +</div> +<p>) or in the prefix form (eg:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>action:foo!bar +</code></pre> +</div> +<p>). This syntax tells this mapper to map to the action named</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>foo +</code></pre> +</div> +<p> and the method</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>bar +</code></pre> +</div> +<p>.</p> + +<p>#####Method prefix#####</p> + +<p>With method-prefix, instead of calling baz actionâs</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute() +</code></pre> +</div> +<p> method (by default if it isnât overridden in</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.xml +</code></pre> +</div> +<p> to be something else), the baz actionâs</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>anotherMethod() +</code></pre> +</div> +<p> will be called. A very elegant way determine which button is clicked. Alternatively, one would have submit button set a particular value on the action when clicked, and the</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute() +</code></pre> +</div> +<p> method decides on what to do with the setted value depending on which button is clicked.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><!-- START SNIPPET: method-example --> +<s:form action="baz"> + <s:textfield label="Enter your name" name="person.name"/> + <s:submit value="Create person"/> + <s:submit method="anotherMethod" value="Cancel"/> +</s:form> +<!-- END SNIPPET: method-example --> +</code></pre> +</div> + +<p>#####Action prefix#####</p> + +<p>With action-prefix, instead of executing baz actionâs</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute() +</code></pre> +</div> +<p> method (by default if it isnât overridden in struts.xml to be something else), the anotherAction actionâs</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute() +</code></pre> +</div> +<p> method (assuming again if it isnât overridden with something else in</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.xml +</code></pre> +</div> +<p>) will be executed.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><!-- START SNIPPET: action-example --> +<s:form action="baz"> + <s:textfield label="Enter your name" name="person.name"/> + <s:submit value="Create person"/> + <s:submit action="anotherAction" value="Cancel"/> +</s:form> +<!-- END SNIPPET: action-example --> +</code></pre> +</div> + +<p>#####Allowed action name RegEx#####</p> + +<p>By default the mapper will check if extracted action name matches provided RegEx, i.e. </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>[a-zA-Z0-9._!/\-]* +</code></pre> +</div> +<p>. You redefine this RegEx by defining a constant in </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.xml +</code></pre> +</div> +<p>named </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.allowed.action.names +</code></pre> +</div> +<p>. If action name doesnât match the RegEx a default action name will be returned which is defined as </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>index +</code></pre> +</div> +<p>. You can also redefine this by specifying constant </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.default.action.name +</code></pre> +</div> +<p>in </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.xml +</code></pre> +</div> + +<p>#####Allowed method name RegEx#####</p> + +<p>The same logic as above is used for extracted methods, the default RegEx</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>( +</code></pre> +</div> + +<div class="highlighter-rouge"><pre class="highlight"><code>[a-zA-Z_]*[0-9]*) +</code></pre> +</div> +<p>is used to check if method is allowed, you can change this by setting constant </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.allowed.method.names +</code></pre> +</div> +<p>in </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.xml +</code></pre> +</div> +<p>. If method doesnât match the RegEx a default method is returned, i.e. </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>execute +</code></pre> +</div> +<p>. This can be changed by defining constant </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.default.method.name +</code></pre> +</div> +<p>in </p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.xml +</code></pre> +</div> +<p>.</p> + +<p>Please note that this funcionallity only works when <a href="https://cwiki\.apache\.org/confluence/display/WW/Action\+Configuration\#ActionConfiguration\-DynamicMethodInvocation";>Dynamic Method Invocation</a>^[https://cwiki.apache.org/confluence/display/WW/Action+Configuration#ActionConfiguration-DynamicMethodInvocation] is enabled.</p> + +<p>####Custom ActionMapper####</p> + +<p>You can define your own ActionMapper by implementing</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>org.apache.struts2.dispatcher.mapper.ActionMapper +</code></pre> +</div> +<p>then configuring Struts 2 to use the new class in struts.xml</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><bean type="org.apache.struts2.dispatcher.mapper.ActionMapper" name="mymapper" class="com.mycompany.myapp.MyActionMapper" /> +<constant name="struts.mapper.class" value="mymapper" /> + +</code></pre> +</div> + +<p>Possible uses of the ActionMapper include defining your own, cleaner namespaces, such as URLs like <strong>/person/1</strong>, which would be similar to a request to <strong>/getPerson.action?personID=1</strong> using the DefaultActionMapper.</p> + +<p>####CompositeActionMapper####</p> + +<p>A composite action mapper that is capable of delegating to a series of if the former failed to obtained a valid <em>ActionMapping</em> or uri.</p> + +<p>It is configured through <a href="struts-xml.html">struts.xml</a>. For example, with the following entries in struts.xml</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><constant name="struts.mapper.class" value="composite" /> +<constant name="struts.mapper.composite" value="struts,restful,restful2" /> + +</code></pre> +</div> + +<p>When</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>CompositeActionMapper#getMapping(HttpServletRequest, ConfigurationManager) +</code></pre> +</div> +<p>or</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>CompositeActionMapper#getUriFromActionMapping(ActionMapping) +</code></pre> +</div> +<p>is invoked,</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>CompositeActionMapper +</code></pre> +</div> +<p>would go through these s in sequence starting from identified by</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.mapper.composite.1 +</code></pre> +</div> +<p>, followed by</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.mapper.composite.2 +</code></pre> +</div> +<p>and finally</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.mapper.composite.3 +</code></pre> +</div> +<p>(in this case) until either one of the return a valid result (not null) or it runs out of in which case it will just return null for both</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>CompositeActionMapper#getMapping(HttpServletRequest, ConfigurationManager) +</code></pre> +</div> +<p>and</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>CompositeActionMapper#getUriFromActionMapping(ActionMapping) +</code></pre> +</div> +<p>methods.</p> + +<p>For example with the following in struts.xml:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><constant name="struts.mapper.class" value="composite" /> +<constant name="struts.mapper.composite" value="struts,restful" /> + +</code></pre> +</div> + +<div class="highlighter-rouge"><pre class="highlight"><code>CompositeActionMapper +</code></pre> +</div> +<p>will be configured with 2 ActionMapper, namely âstrutsâ which is</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>org.apache.struts2.dispatcher.mapper.DefaultActionMapper +</code></pre> +</div> +<p>and ârestfulâ which is</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>org.apache.struts2.dispatcher.mapper.RestfulActionMapperRestfulActionMapper +</code></pre> +</div> +<p>.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>CompositeActionMapper +</code></pre> +</div> +<p>would consult each of them in order described above.</p> + +<p>####PrefixBasedActionMapper####</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=description|javadoc=true|url=org.apache.struts2.dispatcher.mapper.PrefixBasedActionMapper</span><span class="p">}</span><span class="w"> +</span></code></pre> +</div> + +<p><strong>PrefixBasedActionProxyFactory</strong></p> + +<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=description|javadoc=true|url=org.apache.struts2.factory.PrefixBasedActionProxyFactory</span><span class="p">}</span><span class="w"> +</span></code></pre> +</div> + +<p>####ActionMapper and ActionMapping objects####</p> + +<p>The ActionMapper fetches the ActionMapping object corresponding to a given request. Essentially, the ActionMapping is a data transfer object that collects together details such as the Action class and method to execute. The mapping is utilized by the Dispatcher and various user interface components. It is customizable through</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.mapper.class +</code></pre> +</div> +<p>entry in</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.properties +</code></pre> +</div> +<p>or</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>struts.xml +</code></pre> +</div> +<p>. Note that the value of this constant is the name of the bean of the new mapper.</p> + +<p>#####Customize#####</p> + +<p>Custom ActionMapper must implement ActionMapper interface and have a default constructor.</p> + +<blockquote> + +</blockquote> + +<div class="highlighter-rouge"><pre class="highlight"><code><bean type="org.apache.struts2.dispatcher.mapper.ActionMapper" name="mymapper" class="com.mycompany.myapp.MyActionMapper" /> +<constant name="struts.mapper.class" value="mymapper" /> + +</code></pre> +</div> + +<div class="highlighter-rouge"><pre class="highlight"><code>public class MyCustomActionMapper implements ActionMapper { + public ActionMapping getMapping(HttpServletRequest request, + ConfigurationManager configManager) { + .... + } + + public String getUriFromActionMapping(ActionMapping mapping) { + .... + } +} + +</code></pre> +</div> + +<p>(light-on) See also: <a href="restful-action-mapper.html">RestfulActionMapper</a></p> + + </section> +</article> + + +<footer class="container"> + <div class="col-md-12"> + Copyright © 2000-2016 <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> + + +<script> +$(function() { + return $("h2, h3, h4, h5, h6").each(function(i, el) { + var $el, id; + $el = $(el); + id = $el.attr('id'); + if (id) { + $el.removeAttr('id'); + return $el.before($("<a />").addClass('anchor').attr('name', id)); + } + }); +}); +</script> + +</body> +</html>
![https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"](https://s3.amazonaws.com/github/ribbons/forkme_right_red_aa0000.png"){kind=link}