Modified:
websites/production/struts/content/core-developers/wildcard-mappings.html
==============================================================================
--- websites/production/struts/content/core-developers/wildcard-mappings.html
(original)
+++ websites/production/struts/content/core-developers/wildcard-mappings.html
Fri Jul 21 12:44:35 2017
@@ -124,255 +124,210 @@
<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="wildcard-mappings">Wildcard Mappings</h1>
+ <h1 class="no_toc" id="wildcard-mappings">Wildcard Mappings</h1>
-<p>#####Wildcards#####</p>
+<ul id="markdown-toc">
+ <li><a href="#wildcards" id="markdown-toc-wildcards">Wildcards</a></li>
+ <li><a href="#parameters-in-namespaces"
id="markdown-toc-parameters-in-namespaces">Parameters in namespaces</a></li>
+ <li><a href="#parameters-after-the-action-name"
id="markdown-toc-parameters-after-the-action-name">Parameters after the action
name</a></li>
+ <li><a href="#advanced-wildcards"
id="markdown-toc-advanced-wildcards">Advanced Wildcards</a></li>
+</ul>
-<p>As an application grows in size, so will the number of action mappings.
Wildcards can be used to combine similar mappings into one more generic
mapping.</p>
+<h2 id="wildcards">Wildcards</h2>
-<p>The best way to explain wildcards is to show an example and walk through
how it works. This example modifies a conventional mapping to use wildcards to
match all pages that start with /edit:</p>
+<p>As an application grows in size, so will the number of action mappings.
Wildcards can be used to combine similar
+mappings into one more generic mapping.</p>
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<action name="/edit*"
class="org.apache.struts.webapp.example.Edit{1}Action">
- <result name="failure">/mainMenu.jsp</result>
- <result>{1}.jsp</result>
-</action>
+<p>The best way to explain wildcards is to show an example and walk through
how it works. This example modifies
+a conventional mapping to use wildcards to match all pages that start with
<code class="highlighter-rouge">/edit</code>:</p>
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><action</span> <span class="na">name=</span><span
class="s">"/edit*"</span> <span class="na">class=</span><span
class="s">"org.apache.struts.webapp.example.Edit{1}Action"</span><span
class="nt">></span>
+ <span class="nt"><result</span> <span class="na">name=</span><span
class="s">"failure"</span><span class="nt">></span>/mainMenu.jsp<span
class="nt"></result></span>
+ <span class="nt"><result></span>{1}.jsp<span
class="nt"></result></span>
+<span class="nt"></action></span>
</code></pre>
</div>
-<p>The â*â in the name attribute allows the mapping to match the request
URIs /editSubscription, editRegistration, or any other URI that starts with
/edit, however /editSubscription/add would not be matched. The part of the URI
matched by the wildcard will then be substituted into various attributes of the
action mapping and its action results replacing {1}. For the rest of the
request, the framework will see the action mapping and its action results
containing the new values.</p>
+<p>The â*â in the name attribute allows the mapping to match the request
URIs <code class="highlighter-rouge">/editSubscription</code>, <code
class="highlighter-rouge">editRegistration</code>,
+or any other URI that starts with <code
class="highlighter-rouge">/edit</code>, however <code
class="highlighter-rouge">/editSubscription/add</code> would not be matched.
The part of the URI
+matched by the wildcard will then be substituted into various attributes of
the action mapping and its action results
+replacing <code class="highlighter-rouge"><span class="p">{</span><span
class="err">1</span><span class="p">}</span></code>. For the rest of the
request, the framework will see the action mapping and its action results
containing
+the new values.</p>
-<p>Mappings are matched against the request in the order they appear in the
frameworkâs configuration file. If more than one pattern matches <strong>the
last one wins</strong>, so less specific patterns must appear before more
specific ones. However, if the request URL can be matched against a path
without any wildcards in it, no wildcard matching is performed and order is not
important. Also, note that wildcards are not greedy, meaning they only match
until the first occurrence of the following string pattern. For example,
consider the following mapping:</p>
+<p>Mappings are matched against the request in the order they appear in the
frameworkâs configuration file. If more than
+one pattern matches <strong>the last one wins</strong>, so less specific
patterns must appear before more specific ones. However,
+if the request URL can be matched against a path without any wildcards in it,
no wildcard matching is performed
+and order is not important. Also, note that wildcards are not greedy, meaning
they only match until the first
+occurrence of the following string pattern. For example, consider the
following mapping:</p>
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<action name="List*s" class="actions.List{1}s">
- <result>list{1}s.jsp</result>
-</action>
-
-</code></pre>
-</div>
-
-<p>This mapping would work correctly for the URI</p>
-
-<div class="highlighter-rouge"><pre class="highlight"><code>ListAccounts
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><action</span> <span class="na">name=</span><span
class="s">"List*s"</span> <span class="na">class=</span><span
class="s">"actions.List{1}s"</span><span class="nt">></span>
+ <span class="nt"><result></span>list{1}s.jsp<span
class="nt"></result></span>
+<span class="nt"></action></span>
</code></pre>
</div>
-<p>but not</p>
-<div class="highlighter-rouge"><pre class="highlight"><code>ListSponsors
-</code></pre>
-</div>
-<p>, because the latter would turn into this configuration:</p>
-
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<action name="ListSpons" class="actions.ListSpons">
- <result>listSpons.jsp</result>
-</action>
+<p>This mapping would work correctly for the URI <code
class="highlighter-rouge">ListAccounts</code> but not <code
class="highlighter-rouge">ListSponsors</code>, because the latter would turn
into
+this configuration:</p>
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><action</span> <span class="na">name=</span><span
class="s">"ListSpons"</span> <span class="na">class=</span><span
class="s">"actions.ListSpons"</span><span class="nt">></span>
+ <span class="nt"><result></span>listSpons.jsp<span
class="nt"></result></span>
+<span class="nt"></action></span>
</code></pre>
</div>
<p>Wildcard patterns can contain one or more of the following special
tokens:</p>
-<p>|*|Matches zero or more characters excluding the slash (â/â) character.|
-|â|âââââââââââââââââââââââ|
-|**|Matches zero or more characters including the slash (â/â) character.|
-|\character|The backslash character is used as an escape sequence. Thus \
-â\*â matches the character asterisk (â*â), and \
-â\\â matches the character backslash (â\â).|</p>
-
-<p>Patterns can optionally be matched âlooselyâ. When the end of the
pattern matches *[^*]*$ (wildcard, no wildcard, wildcard), if the pattern
fails, it is also matched as if the last two characters didnât exist. The
goal is to support the legacy â*!*â syntax, where the â!*â is
optional.</p>
-
<table>
+ <thead>
+ <tr>
+ <th>*</th>
+ <th>Matches zero or more characters excluding the slash (â/â)
character.</th>
+ </tr>
+ </thead>
<tbody>
<tr>
+ <td>**</td>
+ <td>Matches zero or more characters including the slash (â/â)
character.</td>
+ </tr>
+ <tr>
+ <td>\character</td>
+ <td>The backslash character is used as an escape sequence. Thus <code
class="highlighter-rouge">\\*</code> matches the character asterisk (â*â),
and <code class="highlighter-rouge">'\\'</code> matches the character backslash
(â\â).</td>
</tr>
</tbody>
</table>
-<p>In the action mapping and action results, the wildcard-matched values can
be accessed with the token {N} where N is a number from 1 to 9 indicating which
wildcard-matched value to substitute. The whole request URI can be accessed
with the {0} token.</p>
+<p>Patterns can optionally be matched âlooselyâ. When the end of the
pattern matches <code class="highlighter-rouge">*[^*]*$</code> (wildcard, no
wildcard,
+wildcard), if the pattern fails, it is also matched as if the last two
characters didnât exist. The goal is to support
+the legacy <code class="highlighter-rouge">*!*</code> syntax, where the <code
class="highlighter-rouge">!*</code> is optional.</p>
+
+<p>In the action mapping and action results, the wildcard-matched values can
be accessed with the token <code class="highlighter-rouge"><span
class="p">{</span><span class="err">N</span><span class="p">}</span></code>
where N is
+a number from 1 to 9 indicating which wildcard-matched value to substitute.
The whole request URI can be accessed with
+the <code class="highlighter-rouge"><span class="p">{</span><span
class="err">0</span><span class="p">}</span></code> token.</p>
<p>Also, the action mapping and action result properties will accept
wildcard-matched strings in their value attribute, like:</p>
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<action name="/edit/*"
class="org.apache.struts.webapp.example.Edit{1}Action">
- <param name="id">{1}</param>
- <result>
- <param name="location">/mainMenu.jsp</param>
- <param name="id">{1}</param>
- </result>
-</action>
-
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><action</span> <span class="na">name=</span><span
class="s">"/edit/*"</span> <span class="na">class=</span><span
class="s">"org.apache.struts.webapp.example.Edit{1}Action"</span><span
class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"id"</span><span class="nt">></span>{1}<span
class="nt"></param></span>
+ <span class="nt"><result></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"location"</span><span class="nt">></span>/mainMenu.jsp<span
class="nt"></param></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"id"</span><span class="nt">></span>{1}<span
class="nt"></param></span>
+ <span class="nt"></result></span>
+<span class="nt"></action></span>
</code></pre>
</div>
-<p>(light-on) See also <a href="#PAGE_14122">Wildcard Method</a></p>
-
-<p>#####Parameters in namespaces#####</p>
+<blockquote>
+ <p>See also <a
href="../getting-started/wildcard-method-selection.html">Wildcard Method</a></p>
+</blockquote>
-<p>From Struts 2.1+ namespace patterns can be extracted as request parameters
and bound to the action. To enable this feature, set the following constant in
struts.xml:</p>
+<h2 id="parameters-in-namespaces">Parameters in namespaces</h2>
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<constant name="struts.patternMatcher" value="namedVariable"/>
+<p>From Struts 2.1+ namespace patterns can be extracted as request parameters
and bound to the action. To enable this
+feature, set the following constant in struts.xml:</p>
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><constant</span> <span class="na">name=</span><span
class="s">"struts.patternMatcher"</span> <span class="na">value=</span><span
class="s">"namedVariable"</span><span class="nt">/></span>
</code></pre>
</div>
-<p>With that in place, namespace definitions can contain {PARAM_NAME} patterns
which will be evaluated against the request URL and extracted as parameters,
for example:</p>
-
-<div class="highlighter-rouge"><pre class="highlight"><code>
-@Namespace{"/users/{userID}");
-public class DetailsAction exends ActionSupport {
- private Long userID;
- public void setUserID(Long userID) {...}
-}
+<p>With that in place, namespace definitions can contain {PARAM_NAME} patterns
which will be evaluated against the request
+URL and extracted as parameters, for example:</p>
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nd">@Namespace</span><span class="o">{</span><span
class="s">"/users/{userID}"</span><span class="o">);</span>
+<span class="kd">public</span> <span class="kd">class</span> <span
class="nc">DetailsAction</span> <span class="n">exends</span> <span
class="n">ActionSupport</span> <span class="o">{</span>
+ <span class="kd">private</span> <span class="n">Long</span> <span
class="n">userID</span><span class="o">;</span>
+ <span class="kd">public</span> <span class="kt">void</span> <span
class="n">setUserID</span><span class="o">(</span><span class="n">Long</span>
<span class="n">userID</span><span class="o">)</span> <span
class="o">{...}</span>
+<span class="o">}</span>
</code></pre>
</div>
-<p>If the request URL is <em>/users/10/detail</em> , then the DetailsAction
will be executed and its userID field will be set to <em>10</em> .</p>
-
-<blockquote>
-
-</blockquote>
-
-<blockquote>
-
-</blockquote>
-
-<blockquote>
- <p>Only one PatternMatcher implementation can be used at a time. The two
implementations included with Struts 2 are mutually exclusive. You cannot use
Wildcards and Named Variable patterns at the same application (if that were
required, youâd need to create a custom PatternMatcher implementation).</p>
-</blockquote>
-
-<blockquote>
-
-</blockquote>
-
-<blockquote>
-
-</blockquote>
+<p>If the request URL is <code
class="highlighter-rouge">/users/10/detail</code>, then the <code
class="highlighter-rouge">DetailsAction</code> will be executed and its userID
field will be set
+to <em>10</em>.</p>
<blockquote>
- <p>Some tags tags not are 100% compatible with variables in the namespace.
For instance, they may write the literal namespace into the HTML (eg
/{user}/2w) instead of the path used in the request (ie. /brett/24). This
usually affects attributes that attempt to guess the namespace of an action
(eg. Form tag, Action tag, action=). This problem can be avoided by using HTML
tags directly with relative paths or explicit URLs.</p>
+ <p>Only one <code class="highlighter-rouge">PatternMatcher</code>
implementation can be used at a time. The two implementations included with
Struts 2 are
+mutually exclusive. You cannot use Wildcards and Named Variable patterns at
the same application (if that were required,
+youâd need to create a custom PatternMatcher implementation).</p>
</blockquote>
<blockquote>
-
+ <p>Some tags tags not are 100% compatible with variables in the namespace.
For instance, they may write the literal
+namespace into the HTML (eg.: <code
class="highlighter-rouge">/{user}/2w</code>) instead of the path used in the
request (ie. <code class="highlighter-rouge">/brett/24</code>). This usually
+affects attributes that attempt to guess the namespace of an action (eg. Form
tag, Action tag, action=). This problem
+can be avoided by using HTML tags directly with relative paths or explicit
URLs.</p>
</blockquote>
-<table>
- <tbody>
- <tr>
- </tr>
- </tbody>
-</table>
+<p>Similar functionality can also be implemented using a custom <code
class="highlighter-rouge">ActionMapper</code>. The <code
class="highlighter-rouge">ActionMapper</code> will need to parse
+the namespace and request itself to set parameters on the matched action. The
default <code class="highlighter-rouge">ActonMapper</code> is responsible
+for invoking the <code class="highlighter-rouge">PatternMatcher</code>.</p>
-<table>
- <tbody>
- <tr>
- <td>Similar functionality can also be implemented using a custom
ActionMapper. The ActionMapper will need to parse the namespace and request
itself to set parameters on the matched action. The default ActonMapper is
responsible for invoking the PatternMatcher.</td>
- </tr>
- </tbody>
-</table>
-
-<table>
- <tbody>
- <tr>
- </tr>
- </tbody>
-</table>
-
-<p>#####Parameters after the action name#####</p>
+<h2 id="parameters-after-the-action-name">Parameters after the action name</h2>
<p>To use parameters in the URL, after the action name, make sure this is
set:</p>
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<constant name="struts.enable.SlashesInActionNames" value="true"/>
-<constant name="struts.mapper.alwaysSelectFullNamespace" value="false"/>
-
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><constant</span> <span class="na">name=</span><span
class="s">"struts.enable.SlashesInActionNames"</span> <span
class="na">value=</span><span class="s">"true"</span><span
class="nt">/></span>
+<span class="nt"><constant</span> <span class="na">name=</span><span
class="s">"struts.mapper.alwaysSelectFullNamespace"</span> <span
class="na">value=</span><span class="s">"false"</span><span
class="nt">/></span>
</code></pre>
</div>
<p>Then the action mapping will look like:</p>
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<package name="edit" extends="struts-default" namespace="/edit">
- <action name="/person/*"
class="org.apache.struts.webapp.example.EditAction">
- <param name="id">{1}</param>
- <result>/mainMenu.jsp</result>
- </action>
-</package>
-
-</code></pre>
-</div>
-
-<p>When a URL like</p>
-
-<div class="highlighter-rouge"><pre class="highlight"><code>/edit/person/123
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><package</span> <span class="na">name=</span><span
class="s">"edit"</span> <span class="na">extends=</span><span
class="s">"struts-default"</span> <span class="na">namespace=</span><span
class="s">"/edit"</span><span class="nt">></span>
+ <span class="nt"><action</span> <span class="na">name=</span><span
class="s">"/person/*"</span> <span class="na">class=</span><span
class="s">"org.apache.struts.webapp.example.EditAction"</span><span
class="nt">></span>
+ <span class="nt"><param</span> <span class="na">name=</span><span
class="s">"id"</span><span class="nt">></span>{1}<span
class="nt"></param></span>
+ <span class="nt"><result></span>/mainMenu.jsp<span
class="nt"></result></span>
+ <span class="nt"></action></span>
+<span class="nt"></package></span>
</code></pre>
</div>
-<p>is requested, EditAction will be called, and its âidâ field will be set
to 123.</p>
-<p>#####Advanced Wildcards#####</p>
+<p>When a URL like <code class="highlighter-rouge">/edit/person/123</code> is
requested, <code class="highlighter-rouge">EditAction</code> will be called,
and its âidâ field will be set to 123.</p>
-<p>From 2.1.9+ regular expressions can be defined defined in the action name.
To use this form of wild card, the following constants must be set:</p>
+<h2 id="advanced-wildcards">Advanced Wildcards</h2>
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<constant name="struts.enable.SlashesInActionNames" value="true"/>
-<constant name="struts.mapper.alwaysSelectFullNamespace" value="false"/>
-<constant name="struts.patternMatcher" value="regex" />
+<p>From 2.1.9+ regular expressions can be defined defined in the action name.
To use this form of wild card, the following
+constants must be set:</p>
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><constant</span> <span class="na">name=</span><span
class="s">"struts.enable.SlashesInActionNames"</span> <span
class="na">value=</span><span class="s">"true"</span><span
class="nt">/></span>
+<span class="nt"><constant</span> <span class="na">name=</span><span
class="s">"struts.mapper.alwaysSelectFullNamespace"</span> <span
class="na">value=</span><span class="s">"false"</span><span
class="nt">/></span>
+<span class="nt"><constant</span> <span class="na">name=</span><span
class="s">"struts.patternMatcher"</span> <span class="na">value=</span><span
class="s">"regex"</span> <span class="nt">/></span>
</code></pre>
</div>
-<p>The regular expressions can be in two forms, the simplest one is
{FIELD_NAME}, in which case the field with the FIELD_NAME in the action will be
populated with the matched text, for example:</p>
+<p>The regular expressions can be in two forms, the simplest one is <code
class="highlighter-rouge"><span class="p">{</span><span
class="err">FIELD_NAME</span><span class="p">}</span></code>, in which case the
field with
+the <code class="highlighter-rouge">FIELD_NAME</code> in the action will be
populated with the matched text, for example:</p>
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<package name="books" extends="struts-default" namespace="/">
- <action name="/{type}/content/{title}" class="example.BookAction">
- <result>/books/content.jsp</result>
- </action>
-</package>
-
-</code></pre>
-</div>
-
-<p>In this example, if the url</p>
-
-<div class="highlighter-rouge"><pre
class="highlight"><code>/fiction/content/Frankenstein
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><package</span> <span class="na">name=</span><span
class="s">"books"</span> <span class="na">extends=</span><span
class="s">"struts-default"</span> <span class="na">namespace=</span><span
class="s">"/"</span><span class="nt">></span>
+ <span class="nt"><action</span> <span class="na">name=</span><span
class="s">"/{type}/content/{title}"</span> <span class="na">class=</span><span
class="s">"example.BookAction"</span><span class="nt">></span>
+ <span class="nt"><result></span>/books/content.jsp<span
class="nt"></result></span>
+ <span class="nt"></action></span>
+<span class="nt"></package></span>
</code></pre>
</div>
-<p>is requested, BookActionâs field âtypeâ will be set to âfictionâ,
and the field âtitleâ will be set to âFrankensteinâ.</p>
-<p>The regular expression can also be in the form
{FIELD_NAME:REGULAR_EXPRESSION}. The regular expression is a normal Java
regular expression. For example:</p>
-
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<package name="books" extends="struts-default" namespace="/">
- <action name="/{type}/{author:.+}/list"
class="example.ListBooksAction">
- <result>/books/list.jsp</result>
- </action>
-</package>
-
-</code></pre>
-</div>
+<p>In this example, if the url <code
class="highlighter-rouge">/fiction/content/Frankenstein</code> is requested,
BookActionâs field âtypeâ will be set to
+âfictionâ, and the field âtitleâ will be set to âFrankensteinâ.</p>
-<p>In this example, if the url</p>
+<p>The regular expression can also be in the form <code
class="highlighter-rouge"><span class="p">{</span><span
class="err">FIELD_NAME:REGULAR_EXPRESSION</span><span
class="p">}</span></code>. The regular expression is a normal
+Java regular expression. For example:</p>
-<div class="highlighter-rouge"><pre
class="highlight"><code>/philosophy/AynRand/list
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><package</span> <span class="na">name=</span><span
class="s">"books"</span> <span class="na">extends=</span><span
class="s">"struts-default"</span> <span class="na">namespace=</span><span
class="s">"/"</span><span class="nt">></span>
+ <span class="nt"><action</span> <span class="na">name=</span><span
class="s">"/{type}/{author:.+}/list"</span> <span class="na">class=</span><span
class="s">"example.ListBooksAction"</span><span class="nt">></span>
+ <span class="nt"><result></span>/books/list.jsp<span
class="nt"></result></span>
+ <span class="nt"></action></span>
+<span class="nt"></package></span>
</code></pre>
</div>
-<p>is requested, ListBooksActionâs field âtypeâ will be set to
âphilosophyâ and âauthorâ to âAynRandâ.</p>
-<p>The matched groups can still be accessed using the {X} notation, like:</p>
+<p>In this example, if the url <code
class="highlighter-rouge">/philosophy/AynRand/list</code> is requested,
ListBooksActionâs field âtypeâ will be set to
+âphilosophyâ and âauthorâ to âAynRandâ.</p>
-<div class="highlighter-rouge"><pre class="highlight"><code>
-<package name="books" extends="struts-default" namespace="/">
- <action name="/books/{ISBN}/content" class="example.BookAction">
- <result>/books/{1}.jsp</result>
- </action>
-</package>
+<p>The matched groups can still be accessed using the <code
class="highlighter-rouge"><span class="p">{</span><span
class="err">X</span><span class="p">}</span></code> notation, like:</p>
+<div class="highlighter-rouge"><pre class="highlight"><code><span
class="nt"><package</span> <span class="na">name=</span><span
class="s">"books"</span> <span class="na">extends=</span><span
class="s">"struts-default"</span> <span class="na">namespace=</span><span
class="s">"/"</span><span class="nt">></span>
+ <span class="nt"><action</span> <span class="na">name=</span><span
class="s">"/books/{ISBN}/content"</span> <span class="na">class=</span><span
class="s">"example.BookAction"</span><span class="nt">></span>
+ <span class="nt"><result></span>/books/{1}.jsp<span
class="nt"></result></span>
+ <span class="nt"></action></span>
+<span class="nt"></package></span>
</code></pre>
</div>
