Repository: struts-site Updated Branches: refs/heads/asf-site 68ba32a9e -> f694fc8f7
http://git-wip-us.apache.org/repos/asf/struts-site/blob/f694fc8f/content/core-developers/validation.html ---------------------------------------------------------------------- diff --git a/content/core-developers/validation.html b/content/core-developers/validation.html index 9be2ef9..55c16f4 100644 --- a/content/core-developers/validation.html +++ b/content/core-developers/validation.html @@ -127,427 +127,498 @@ <a class="edit-on-gh" href="https://github.com/apache/struts-site/edit/master/source/core-developers/validation.md"; title="Edit this page on GitHub">Edit on GitHub</a> <h1 id="validation">Validation</h1> -<p>Struts 2 validation is configured via XML or annotations. Manual validation in the action is also possible, and may be combined with XML and annotation-driven validation.</p> +<p>Struts 2 validation is configured via XML or annotations. Manual validation in the action is also possible, and may be +combined with XML and annotation-driven validation.</p> -<p>Validation also depends on both the</p> +<p>Validation also depends on both the <code class="highlighter-rouge">validation</code> and <code class="highlighter-rouge">workflow</code> interceptors (both are included in the default interceptor +stack). The <code class="highlighter-rouge">validation</code> interceptor does the validation itself and creates a list of field-specific errors. +The <code class="highlighter-rouge">workflow</code> interceptor checks for the presence of validation errors: if any are found, it returns the âinputâ result +(by default), taking the user back to the form which contained the validation errors.</p> -<div class="highlighter-rouge"><pre class="highlight"><code>validation -</code></pre> -</div> -<p>and</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>workflow -</code></pre> -</div> -<p>interceptors (both are included in the default interceptor stack). The</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>validation -</code></pre> -</div> -<p>interceptor does the validation itself and creates a list of field-specific errors. The</p> - -<div class="highlighter-rouge"><pre class="highlight"><code>workflow -</code></pre> -</div> -<p>interceptor checks for the presence of validation errors: if any are found, it returns the âinputâ result (by default), taking the user back to the form which contained the validation errors.</p> - -<p>If weâre using the default settings <em>and</em> our action doesnât have an âinputâ result defined <em>and</em> there are validation (or, incidentally, type conversion) errors, weâll get an error message back telling us thereâs no âinputâ result defined for the action.</p> - -<p><strong>CONTENTS</strong></p> - -<p>####Using Annotations####</p> - -<p><a href="validation-annotation.html">Annotations</a> can be used as an alternative to XML for validation.</p> +<p>If weâre using the default settings <em>and</em> our action does not have an âinputâ result defined <em>and</em> there are validation +(or, incidentally, type conversion) errors, weâll get an error message back telling us thereâs no âinputâ result defined +for the action.</p> -<p>Â </p> +<h2 id="using-annotations">Using Annotations</h2> -<p>####Bean Validation####</p> +<p><a href="validation-annotation.html">Annotations</a> can be used as an alternative to XML for validation. +Â +## Bean Validation</p> -<p>With struts 2.5 comes the Bean Validation Plugin. That is an alternative to the classic struts validation described here. See the <em>Plugin Page</em> for details.</p> +<p>With struts 2.5 comes the Bean Validation Plugin. That is an alternative to the classic struts validation described here. +See the <a href="../plugins/">Plugin Page</a> for details.</p> -<p>####Examples####</p> +<h2 id="examples">Examples</h2> -<p>In all examples given here, the validation message displayed is given in plain English - to internationalize the message, put the string in a properties file and use a property key instead, specified by the âkeyâ attribute. It will be looked up by the framework (see <a href="localization.html">Localization</a>).</p> +<p>In all examples given here, the validation message displayed is given in plain English - to internationalize the message, +put the string in a properties file and use a property key instead, specified by the âkeyâ attribute. It will be looked +up by the framework (see <a href="localization.html">Localization</a>).</p> <ol> - <li> - <p><a href="basic-validation.html">Basic Validation</a></p> - </li> - <li> - <p><a href="client-side-validation.html">Client-side Validation</a></p> - </li> - <li> - <p><em>AJAX Validation</em></p> - </li> - <li> - <p><a href="using-field-validators.html">Using Field Validators</a></p> - </li> - <li> - <p><a href="using-non-field-validators.html">Using Non Field Validators</a></p> - </li> - <li> - <p><a href="using-visitor-field-validator.html">Using Visitor Field Validator</a></p> - </li> - <li> - <p><em>How do we repopulate controls when validation fails</em> (FAQ entry)</p> - </li> + <li><a href="basic-validation.html">Basic Validation</a></li> + <li><a href="client-side-validation.html">Client-side Validation</a></li> + <li><em>AJAX Validation</em></li> + <li><a href="using-field-validators.html">Using Field Validators</a></li> + <li><a href="using-non-field-validators.html">Using Non Field Validators</a></li> + <li><a href="using-visitor-field-validator.html">Using Visitor Field Validator</a></li> + <li><em>How do we repopulate controls when validation fails</em> (FAQ entry)</li> </ol> -<p>####Bundled Validators####</p> +<h2 id="bundled-validators">Bundled Validators</h2> -<p>When using a Field Validator, Field Validator Syntax is <strong>ALWAYS</strong> preferable than using the Plain Validator Syntax as it facilitates grouping of field-validators according to fields. This is very handy especially if a field needs to have many field-validators which is almost always the case.</p> - -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<p>When using a Field Validator, Field Validator Syntax is <strong>ALWAYS</strong> preferable than using the Plain Validator Syntax +as it facilitates grouping of field-validators according to fields. This is very handy especially if a field needs +to have many field-validators which is almost always the case.</p> <ol> - <li> - <p><a href="conversion-validator.html">conversion validator</a></p> - </li> - <li> - <p><a href="date-validator.html">date validator</a></p> - </li> - <li> - <p><a href="double-validator.html">double validator</a></p> - </li> - <li> - <p><a href="email-validator.html">email validator</a></p> - </li> - <li> - <p><a href="expression-validator.html">expression validator</a></p> - </li> - <li> - <p><a href="fieldexpression-validator.html">fieldexpression validator</a></p> - </li> - <li> - <p><a href="int-validator.html">int validator</a></p> - </li> - <li> - <p><a href="regex-validator.html">regex validator</a></p> - </li> - <li> - <p><a href="required-validator.html">required validator</a></p> - </li> - <li> - <p><a href="requiredstring-validator.html">requiredstring validator</a></p> - </li> - <li> - <p><a href="short-validator.html">short validator</a></p> - </li> - <li> - <p><a href="stringlength-validator.html">stringlength validator</a></p> - </li> - <li> - <p><a href="url-validator.html">url validator</a></p> - </li> - <li> - <p><a href="visitor-validator.html">visitor validator</a></p> - </li> - <li> - <p><a href="conditionalvisitor-validator.html">conditionalvisitor validator</a></p> - </li> + <li><a href="conversion-validator.html">conversion validator</a></li> + <li><a href="date-validator.html">date validator</a></li> + <li><a href="double-validator.html">double validator</a></li> + <li><a href="email-validator.html">email validator</a></li> + <li><a href="expression-validator.html">expression validator</a></li> + <li><a href="fieldexpression-validator.html">fieldexpression validator</a></li> + <li><a href="int-validator.html">int validator</a></li> + <li><a href="regex-validator.html">regex validator</a></li> + <li><a href="required-validator.html">required validator</a></li> + <li><a href="requiredstring-validator.html">requiredstring validator</a></li> + <li><a href="short-validator.html">short validator</a></li> + <li><a href="stringlength-validator.html">stringlength validator</a></li> + <li><a href="url-validator.html">url validator</a></li> + <li><a href="visitor-validator.html">visitor validator</a></li> + <li><a href="conditionalvisitor-validator.html">conditionalvisitor validator</a></li> </ol> -<p>####Registering Validators####</p> +<h2 id="registering-validators">Registering Validators</h2> + +<p>Validation rules are handled by validators, which must be registered with the ValidatorFactory (using the +<code class="highlighter-rouge">registerValidator</code> method). The simplest way to do so is to add a file name <code class="highlighter-rouge">validators.xml</code> in the root of the classpath +(/WEB-INF/classes) that declares all the validators you intend to use.</p> + +<p>The following list shows the default validators included in the framework and is an example of the syntax used to declare +our own validators.</p> + +<figure class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="cp"><?xml version="1.0" encoding="UTF-8"?></span> +<span class="cp"><!DOCTYPE validators PUBLIC + "-//Apache Struts//XWork Validator Definition 1.0//EN" + "http://struts.apache.org/dtds/xwork-validator-definition-1.0.dtd"></span> + +<span class="c"><!-- START SNIPPET: validators-default --></span> +<span class="nt"><validators></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"required"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.RequiredFieldValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"requiredstring"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.RequiredStringValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"int"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.IntRangeFieldValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"long"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.LongRangeFieldValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"short"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.ShortRangeFieldValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"double"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.DoubleRangeFieldValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"date"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.DateRangeFieldValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"expression"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.ExpressionValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"fieldexpression"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.FieldExpressionValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"email"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.EmailValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"creditcard"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.CreditCardValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"url"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.URLValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"visitor"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.VisitorFieldValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"conversion"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.ConversionErrorFieldValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"stringlength"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.StringLengthFieldValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"regex"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.RegexFieldValidator"</span><span class="nt">/></span> + <span class="nt"><validator</span> <span class="na">name=</span><span class="s">"conditionalvisitor"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.validator.validators.ConditionalVisitorFieldValidator"</span><span class="nt">/></span> +<span class="nt"></validators></span> +<span class="c"><!-- END SNIPPET: validators-default --></span></code></pre></figure> + +<blockquote> + <p><strong>Struts 2.1 and Prior</strong> +The <code class="highlighter-rouge">validators.xml</code> used to reference a DTD hosted by Opensymphony, the original location of the XWork project. +Since they moved to Apache Struts, DTDs were changed. Please ensure in your projects to include the DTD header +as described in the examples found here.</p> +</blockquote> + +<blockquote> + <p><strong>Struts 2.0.7 and Prior</strong> +The <code class="highlighter-rouge">validators.xml</code> containing custom validators needs to contain a copy of the default validators. No DTD was used +in <code class="highlighter-rouge">validators.xml</code>. See: <a href="http://struts.apache.org/docs/release-notes-208.html#ReleaseNotes2.0.8-MigrationfrompreviousReleases";>http://struts.apache.org/docs/release-notes-208.html#ReleaseNotes2.0.8-MigrationfrompreviousReleases</a></p> +</blockquote> + +<h2 id="turning-on-validation">Turning on Validation</h2> + +<p>The default interceptor stack, âdefaultStackâ, already has validation turned on. When creating your own interceptor-stack +be sure to include <strong>both</strong> the <code class="highlighter-rouge">validation</code> and <code class="highlighter-rouge">workflow</code> interceptors. From <code class="highlighter-rouge">struts-default.xml</code>:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><interceptor-stack</span> <span class="na">name=</span><span class="s">"defaultStack"</span><span class="nt">></span> + ... + <span class="nt"><interceptor-ref</span> <span class="na">name=</span><span class="s">"validation"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"excludeMethods"</span><span class="nt">></span>input,back,cancel,browse<span class="nt"></param></span> + <span class="nt"></interceptor-ref></span> + <span class="nt"><interceptor-ref</span> <span class="na">name=</span><span class="s">"workflow"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"excludeMethods"</span><span class="nt">></span>input,back,cancel,browse<span class="nt"></param></span> + <span class="nt"></interceptor-ref></span> +<span class="nt"></interceptor-stack></span> +</code></pre> +</div> + +<p>Beginning with version 2.0.4 Struts provides an extension to XWorkâs <code class="highlighter-rouge">com.opensymphony.xwork2.validator.ValidationInterceptor</code> +interceptor.</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><interceptor</span> <span class="na">name=</span><span class="s">"validation"</span> <span class="na">class=</span><span class="s">"org.apache.struts2.interceptor.validation.AnnotationValidationInterceptor"</span><span class="nt">/></span> +</code></pre> </div> -<p>The following list shows the default validators included in the framework and is an example of the syntax used to declare our own validators.</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:lang=xml|url=struts2/core/src/main/resources/com/opensymphony/xwork2/validator/validators/default.xml</span><span class="p">}</span><span class="w"> -</span></code></pre> +<p>This interceptor allows us to turn off validation for a specific method by using the <code class="highlighter-rouge">@org.apache.struts2.interceptor.validation.SkipValidation</code> +annotation on the action method.</p> + +<h2 id="validator-scopes">Validator Scopes</h2> + +<p>Field validators, as the name indicate, act on single fields accessible through an action. A validator, in contrast, +is more generic and can do validations in the full action context, involving more than one field (or even no field +at all) in validation rule. Most validations can be defined on per field basis. This should be preferred over non-field +validation wherever possible, as field validator messages are bound to the related field and will be presented next +to the corresponding input element in the respecting view.</p> + +<p>Non-field validators only add action level messages. Non-field validators are mostly domain specific and therefore +offer custom implementations. The most important standard non-field validator provided by XWork is <code class="highlighter-rouge">ExpressionValidator</code>.</p> + +<h2 id="notes">Notes</h2> + +<p>Non-field validators takes precedence over field validators regardless of the order they are defined in <code class="highlighter-rouge">*-validation.xml</code>. +If a non-field validator is <code class="highlighter-rouge">short-circuited</code>, it will causes its non-field validator to not being executed. +See validation framework documentation for more info.</p> + +<h2 id="defining-validation-rules">Defining Validation Rules</h2> + +<p>Validation rules can be specified: +1. Per Action class: in a file named <code class="highlighter-rouge">ActionName-validation.xml</code> +2. Per Action alias: in a file named <code class="highlighter-rouge">ActionName-alias-validation.xml</code> +3. Inheritance hierarchy and interfaces implemented by Action class: + XWork searches up the inheritance tree of the action to find default + validations for parent classes of the Action and interfaces implemented</p> + +<p>Here is an example for SimpleAction-validation.xml:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><span class="cp"><!DOCTYPE validators PUBLIC "-//Apache Struts//XWork Validator 1.0.3//EN" + "http://struts.apache.org/dtds/xwork-validator-1.0.3.dtd"></span> +<span class="nt"><validators></span> + <span class="nt"><field</span> <span class="na">name=</span><span class="s">"bar"</span><span class="nt">></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"required"</span><span class="nt">></span> + <span class="nt"><message></span>You must enter a value for bar.<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"int"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"min"</span><span class="nt">></span>6<span class="nt"></param></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"max"</span><span class="nt">></span>10<span class="nt"></param></span> + <span class="nt"><message></span>bar must be between ${min} and ${max}, current value is ${bar}.<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"></field></span> + <span class="nt"><field</span> <span class="na">name=</span><span class="s">"bar2"</span><span class="nt">></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"regex"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"expression"</span><span class="nt">></span>[0-9],[0-9]<span class="nt"></param></span> + <span class="nt"><message></span>The value of bar2 must be in the format "x, y", where x and y are between 0 and 9<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"></field></span> + <span class="nt"><field</span> <span class="na">name=</span><span class="s">"date"</span><span class="nt">></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"date"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"min"</span><span class="nt">></span>12/22/2002<span class="nt"></param></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"max"</span><span class="nt">></span>12/25/2002<span class="nt"></param></span> + <span class="nt"><message></span>The date must be between 12-22-2002 and 12-25-2002.<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"></field></span> + <span class="nt"><field</span> <span class="na">name=</span><span class="s">"foo"</span><span class="nt">></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"int"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"min"</span><span class="nt">></span>0<span class="nt"></param></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"max"</span><span class="nt">></span>100<span class="nt"></param></span> + <span class="nt"><message</span> <span class="na">key=</span><span class="s">"foo.range"</span><span class="nt">></span>Could not find foo.range!<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"></field></span> + <span class="nt"><validator</span> <span class="na">type=</span><span class="s">"expression"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"expression"</span><span class="nt">></span>foo lt bar <span class="nt"></param></span> + <span class="nt"><message></span>Foo must be greater than Bar. Foo = ${foo}, Bar = ${bar}.<span class="nt"></message></span> + <span class="nt"></validator></span> +<span class="nt"></validators></span> +</code></pre> </div> -<p>The validators.xml used to reference a DTD hosted by Opensymphony, the original location of the XWork project. Since the the move to Apache Struts, DTDs were changed. Please ensure in your projects to include the DTD header as described in the examples found here</p> +<p>Here we can see the configuration of validators for the <code class="highlighter-rouge">SimpleActio</code>n class. Validators (and field-validators) must have +a <code class="highlighter-rouge">type</code> attribute, which refers to a name of an Validator registered with the <code class="highlighter-rouge">ValidatorFactory </code>as above. Validator elements +may also have <code class="highlighter-rouge"><param></code> elements with name and value attributes to set arbitrary parameters into the Validator instance. +See below for discussion of the message element.</p> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<p>In this context, âAction Aliasâ refers to the action name as given in the Struts configuration. Often, the name attribute +matches the method name, but they may also differ.</p> -<p>The validators.xml containing custom validators needs to contain a copy of the default validators. No DTD was used in validators.xml. See: <a href="http://struts\.apache\.org/2\.x/docs/release\-notes\-208\.html\#ReleaseNotes2\.0\.8\-MigrationfrompreviousReleases";>http://struts.apache.org/2.x/docs/release-notes-208.html#ReleaseNotes2.0.8-MigrationfrompreviousReleases</a></p> +<h2 id="localizing-and-parameterizing-messages">Localizing and Parameterizing Messages</h2> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<p>Each Validator or Field-Validator element must define one message element inside the validator element body. The message +element has 1 attributes, key which is not required. The body of the message tag is taken as the default message which +should be added to the Action if the validator fails. Key gives a message key to look up in the Actionâs ResourceBundles +using <code class="highlighter-rouge">getText()</code> from <code class="highlighter-rouge">LocaleAware</code> if the Action implements that interface (as <code class="highlighter-rouge">ActionSupport</code> does). This provides +for Localized messages based on the <code class="highlighter-rouge">Locale</code> of the user making the request (or whatever <code class="highlighter-rouge">Locale</code> youâve set into +the <code class="highlighter-rouge">LocaleAware</code> Action). After either retrieving the message from the ResourceBundle using the Key value, or using +the Default message, the current Validator is pushed onto the ValueStack, then the message is parsed for <code class="highlighter-rouge">${...}</code> +sections which are replaced with the evaluated value of the string between the <code class="highlighter-rouge">${</code> and <code class="highlighter-rouge">}</code>. This allows you +to parameterize your messages with values from the Validator, the Action, or both.</p> -<p>####Turning on Validation####</p> +<p>If the validator fails, the validator is pushed onto the ValueStack and the message - either the default or +the locale-specific one if the key attribute is defined (and such a message exists) - is parsed for <code class="highlighter-rouge">${...}</code> sections +which are replaced with the evaluated value of the string between the <code class="highlighter-rouge">${</code> and <code class="highlighter-rouge">}</code>. This allows you to parameterize +your messages with values from the validator, the Action, or both.</p> -<p>The default interceptor stack, âdefaultStackâ, already has validation turned on. When creating your own interceptor-stack be sure to include <strong>both</strong> the</p> +<blockquote> + <p>Since validation rules are in an XML file, you must make sure you escape special characters. For example, notice +that in the expression validator rule above we use â>â instead of â>â. Consult a resource on XML +for the full list of characters that must be escaped. The most commonly used characters that must be escaped +are: & (use &), < (use <), and > (use >).</p> +</blockquote> -<div class="highlighter-rouge"><pre class="highlight"><code>validation -</code></pre> -</div> -<p>and</p> +<p>Here is an example of a parameterized message:</p> -<div class="highlighter-rouge"><pre class="highlight"><code>workflow -</code></pre> -</div> -<p>interceptors. From</p> +<p>This will pull the min and max parameters from the IntRangeFieldValidator and the value of bar from the Action.</p> -<div class="highlighter-rouge"><pre class="highlight"><code>struts-default.xml +<div class="highlighter-rouge"><pre class="highlight"><code>bar must be between ${min} and ${max}, current value is ${bar}. </code></pre> </div> -<p>:</p> -<div class="highlighter-rouge"><pre class="highlight"><code><interceptor-stack name="defaultStack"> - ... - <interceptor-ref name="validation"> - <param name="excludeMethods">input,back,cancel,browse</param> - </interceptor-ref> - <interceptor-ref name="workflow"> - <param name="excludeMethods">input,back,cancel,browse</param> - </interceptor-ref> -</interceptor-stack> +<p>Another notable fact is that the provided message value is capable of containing OGNL expressions. Keeping this in mind, +it is possible to construct quite sophisticated messages.</p> + +<p>See the following example to get an impression:</p> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><message></span>${getText("validation.failednotice")} ! ${getText("reason")}: ${getText("validation.inputrequired")}<span class="nt"></message></span> </code></pre> </div> -<p>Beginning with version 2.0.4 Struts provides an extension to XWorkâs</p> +<h2 id="validator-flavor">Validator Flavor</h2> -<div class="highlighter-rouge"><pre class="highlight"><code>com.opensymphony.xwork2.validator.ValidationInterceptor -</code></pre> -</div> -<p>interceptor.</p> +<p>The validators supplied by the XWork distribution (and any validators you might write yourself) come in two different +flavors:</p> -<div class="highlighter-rouge"><pre class="highlight"><code><interceptor name="validation" class="org.apache.struts2.interceptor.validation.AnnotationValidationInterceptor"/> +<ol> + <li>Plain Validators / Non-Field validators</li> + <li>FieldValidators</li> +</ol> -</code></pre> -</div> +<p>Plain Validators (such as the <code class="highlighter-rouge">ExpressionValidator</code>) perform validation checks that are not inherently tied to a single +specified field. When you declare a plain Validator in your <code class="highlighter-rouge">-validation.xml</code> file you do not associate a <code class="highlighter-rouge">fieldname</code> +attribute with it. You should avoid using plain Validators within the <code class="highlighter-rouge"><field-validator></code> syntax described below.</p> -<p>This interceptor allows us to turn off validation for a specific method by using the</p> +<p>FieldValidators (such as the <code class="highlighter-rouge">EmailValidator</code>) are designed to perform validation checks on a single field. They require +that you specify a <code class="highlighter-rouge">fieldname</code> attribute in your <code class="highlighter-rouge">-validation.xml</code> file. There are two different (but equivalent) +XML syntaxes you can use to declare FieldValidators (see â<validator> vs. <field-validator> syntax" below).</field-validator></validator></p> -<div class="highlighter-rouge"><pre class="highlight"><code>@org.apache.struts2.interceptor.validation.SkipValidation -</code></pre> -</div> -<p>annotation on the action method.</p> +<p>There are two places where the differences between the two validator flavors are important to keep in mind:</p> -<p>####Validator Scopes####</p> +<ol> + <li>when choosing the xml syntax used for declaring a validator (either <code class="highlighter-rouge"><validator></code> or <code class="highlighter-rouge"><field-validator></code>)</li> + <li>when using the <code class="highlighter-rouge">short-circuit</code> capability</li> +</ol> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=fieldValidators|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<blockquote> + <p>Note that you do not declare what âflavorâ of validator you are using in your <code class="highlighter-rouge">-validation.xml</code> file, you just declare +the name of the validator to use and Struts will know whether itâs a âplain Validatorâ or a âFieldValidatorâ +by looking at the validation class that the validatorâs programmer chose to implement.</p> +</blockquote> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=nonFieldValidators|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<h2 id="non-field-validator-vs-field-validator-validatortypes">Non-Field Validator Vs Field-Validator validatortypes</h2> -<p>#####Notes#####</p> +<p>There are two ways you can define validators in your <code class="highlighter-rouge">-validation.xml</code> file:</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=validatorsNote|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<ol> + <li><code class="highlighter-rouge"><validator></code></li> + <li><code class="highlighter-rouge"><field-validator></code></li> +</ol> -<p>####Defining Validation Rules####</p> +<p>Keep the following in mind when using either syntax:</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=validationRules1|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<p>Non-Field-Validator: The <code class="highlighter-rouge"><validator></code> element allows you to declare both types of validators (either a plain Validator +a field-specific FieldValidator).</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=exValidationRules1|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><validator</span> <span class="na">type=</span><span class="s">"expression</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"expression"</span><span class="nt">></span>foo gt bar<span class="nt"></param></span> + <span class="nt"><message></span>foo must be great than bar.<span class="nt"></message></span> +<span class="nt"></validator></span> +</code></pre> </div> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=validationRules2|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><validator</span> <span class="na">type=</span><span class="s">"required"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"fieldName"</span><span class="nt">></span>bar<span class="nt"></param></span> + <span class="nt"><message></span>You must enter a value for bar.<span class="nt"></message></span> +<span class="nt"></validator></span> +</code></pre> </div> -<p>In this context, âAction Aliasâ refers to the action name as given in the Struts configuration. Often, the name attribute matches the method name, but they may also differ.</p> +<p><strong>field-validator</strong>: The <code class="highlighter-rouge"><field-validator></code> elements are basically the same as the <code class="highlighter-rouge"><validator></code> elements except that +they inherit the <code class="highlighter-rouge">fieldName</code> attribute from the enclosing <code class="highlighter-rouge"><field></code> element. FieldValidators defined within a <code class="highlighter-rouge"><field-validator</code>> +element will have their <code class="highlighter-rouge">fieldName</code> automatically filled with the value of the parent <code class="highlighter-rouge"><field></code> elementâs <code class="highlighter-rouge">fieldName</code> + attribute. The reason for this structure is to conveniently group the validators for a particular field under one element, + otherwise the fieldName attribute would have to be repeated, over and over, for each individual <code class="highlighter-rouge"><validator></code>.</p> -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> +<p>It is always better to defined field-validator inside a <code class="highlighter-rouge"><field></code> tag instead of using a <code class="highlighter-rouge"><validator></code> tag and supplying +<code class="highlighter-rouge">fieldName</code> as its param as the xml code itself is clearer (grouping of field is clearer).</p> -<p>####Localizing and Parameterizing Messages####</p> +<blockquote> + <p>Note that you should only use FieldValidators (not plain Validators) within a block. A plain Validator inside +a <code class="highlighter-rouge"><field></code> will not be allowed and would generate error when parsing the xml, as it is not allowed +in the defined DTD (xwork-validator-1.0.2.dtd)</p> +</blockquote> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=validationRules3|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<p>Declaring a FieldValidator using the <code class="highlighter-rouge"><field-validator></code> syntax:</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=exValidationRules3|javadoc=true|lang=xml|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><field</span> <span class="na">name=</span><span class="s">"email_address"</span><span class="nt">></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"required"</span><span class="nt">></span> + <span class="nt"><message></span>You cannot leave the email address field empty.<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"email"</span><span class="nt">></span> + <span class="nt"><message></span>The email address you entered is not valid.<span class="nt"></message></span> + <span class="nt"></field-validator></span> +<span class="nt"></field></span> +</code></pre> </div> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=validationRules4|javadoc=true|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<p>The choice is yours. Itâs perfectly legal to only use elements without the elements and set the <code class="highlighter-rouge">fieldName</code> attribute +for each of them. The following are effectively equal:</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=exValidationRules4|javadoc=true|lang=xml|url=com.opensymphony.xwork2.validator/ValidatorFactory.java</span><span class="p">}</span><span class="w"> -</span></code></pre> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><field</span> <span class="na">name=</span><span class="s">"email_address"</span><span class="nt">></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"required"</span><span class="nt">></span> + <span class="nt"><message></span>You cannot leave the email address field empty.<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"email"</span><span class="nt">></span> + <span class="nt"><message></span>The email address you entered is not valid.<span class="nt"></message></span> + <span class="nt"></field-validator></span> +<span class="nt"></field></span> + +<span class="nt"><validator</span> <span class="na">type=</span><span class="s">"required"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"fieldName"</span><span class="nt">></span>email_address<span class="nt"></param></span> + <span class="nt"><message></span>You cannot leave the email address field empty.<span class="nt"></message></span> +<span class="nt"></validator></span> +<span class="nt"><validator</span> <span class="na">type=</span><span class="s">"email"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"fieldName"</span><span class="nt">></span>email_address<span class="nt"></param></span> + <span class="nt"><message></span>The email address you entered is not valid.<span class="nt"></message></span> +<span class="nt"></validator></span> +</code></pre> </div> -<p>####Validator Flavor####</p> - -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=validatorFlavours|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java</span><span class="p">}</span><span class="w"> -</span></code></pre> +<h2 id="short-circuiting-validator">Short-Circuiting Validator</h2> + +<p>It is possible to <code class="highlighter-rouge">short-circuit</code> a stack of validators. Here is another sample config file containing validation +rules from the Xwork test cases: Notice that some of the <code class="highlighter-rouge"><field-validator></code> and <code class="highlighter-rouge"><validator></code> elements have +the <code class="highlighter-rouge">short-circuit</code> attribute set to true.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code><span class="cp"><!DOCTYPE validators PUBLIC + "-//Apache Struts//XWork Validator 1.0.3//EN" + "http://struts.apache.org/dtds/xwork-validator-1.0.3.dtd"></span> +<span class="nt"><validators></span> + <span class="c"><!-- Field Validators for email field --></span> + <span class="nt"><field</span> <span class="na">name=</span><span class="s">"email"</span><span class="nt">></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"required"</span> <span class="na">short-circuit=</span><span class="s">"true"</span><span class="nt">></span> + <span class="nt"><message></span>You must enter a value for email.<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"email"</span> <span class="na">short-circuit=</span><span class="s">"true"</span><span class="nt">></span> + <span class="nt"><message></span>Not a valid e-mail.<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"></field></span> + <span class="c"><!-- Field Validators for email2 field --></span> + <span class="nt"><field</span> <span class="na">name=</span><span class="s">"email2"</span><span class="nt">></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"required"</span><span class="nt">></span> + <span class="nt"><message></span>You must enter a value for email2.<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"><field-validator</span> <span class="na">type=</span><span class="s">"email"</span><span class="nt">></span> + <span class="nt"><message></span>Not a valid e-mail2.<span class="nt"></message></span> + <span class="nt"></field-validator></span> + <span class="nt"></field></span> + <span class="c"><!-- Plain Validator 1 --></span> + <span class="nt"><validator</span> <span class="na">type=</span><span class="s">"expression"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"expression"</span><span class="nt">></span>email.equals(email2)<span class="nt"></param></span> + <span class="nt"><message></span>Email not the same as email2<span class="nt"></message></span> + <span class="nt"></validator></span> + <span class="c"><!-- Plain Validator 2 --></span> + <span class="nt"><validator</span> <span class="na">type=</span><span class="s">"expression"</span> <span class="na">short-circuit=</span><span class="s">"true"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"expression"</span><span class="nt">></span>email.startsWith('mark')<span class="nt"></param></span> + <span class="nt"><message></span>Email does not start with mark<span class="nt"></message></span> + <span class="nt"></validator></span> +<span class="nt"></validators></span> +</code></pre> </div> -<p>####Non-Field Validator Vs Field-Validator validatortypes####</p> - -<p>There are two ways you can define validators in your -validation.xml file:</p> +<p><strong>short-circuiting and Validator flavors</strong></p> -<ol> - <li> - <validator> +<p>Plain validator takes precedence over field-validator. They get validated first in the order they are defined and then +the field-validator in the order they are defined. Failure of a particular validator marked as short-circuit will +prevent the evaluation of subsequent validators and an error (action error or field error depending on the type of validator) +will be added to the <code class="highlighter-rouge">ValidationContext</code> of the object being validated.</p> -</validator> - </li> - <li> - <field-validator> +<p>In the example above, the actual execution of validator would be as follows:</p> -</field-validator> - </li> +<ol> + <li>Plain Validator 1</li> + <li>Plain Validator 2</li> + <li>Field Validators for email field</li> + <li>Field Validators for email2 field</li> </ol> -<p>Keep the following in mind when using either syntax:</p> -<p>Non-Field-Validator: The <validator> element allows you to declare both types of validators (either a plain Validator a field-specific FieldValidator).</p> +<p>Since Plain Validator 2 is short-circuited, if its validation failed, it will causes Field validators for email field +and Field validators for email2 field to not be validated as well.</p> -<div class="highlighter-rouge"><pre class="highlight"><code><validator type="expression> - <param name="expression">foo gt bar</param> - <message>foo must be great than bar.</message> -</validator> +<p><strong>Usefull Information:</strong> +More complicated validation should probably be done in the <code class="highlighter-rouge">validate()</code> method on the action itself (assuming the action +implements <code class="highlighter-rouge">Validatable</code> interface which <code class="highlighter-rouge">ActionSupport</code> already does).</p> -</code></pre> -</div> +<p>A plain Validator (non FieldValidator) that gets short-circuited will completely break out of the validation stack. +No other validators will be evaluated and plain validators takes precedence over field validators meaning that they +get evaluated in the order they are defined before field validators get a chance to be evaluated.</p> -<div class="highlighter-rouge"><pre class="highlight"><code><validator type="required"> - <param name="fieldName">bar</param> - <message>You must enter a value for bar.</message> -</validator> +<p><strong>Short cuircuiting and validator flavours</strong></p> -</code></pre> -</div> +<p>A FieldValidator that gets short-circuited will only prevent other FieldValidators for the same field from being +evaluated. Note that this âsame fieldâ behavior applies regardless of whether the <code class="highlighter-rouge"><validator></code> or <code class="highlighter-rouge"><field-validator></code> +syntax was used to declare the validation rule. By way of example, given this <code class="highlighter-rouge">-validation.xml</code> file:</p> -<p><strong>field-validator</strong>: The <field-validator> elements are basically the same as the <validator> elements except that they inherit the fieldName attribute from the enclosing <field> element. FieldValidators defined within a <field-validator> element will have their fieldName automatically filled with the value of the parent <field> elementâs fieldName attribute. The reason for this structure is to conveniently group the validators for a particular field under one element, otherwise the fieldName attribute would have to be repeated, over and over, for each individual <validator>.</p> - -<table> - <tbody> - <tr> - <td>It is always better to defined field-validator inside a <field> tag instead of using a <validator> tag and supplying fieldName as its param as the xml code itself is clearer (grouping of field is clearer)</td> - </tr> - </tbody> -</table> - -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> - -<p>Note that you should only use FieldValidators (not plain Validators) within a block. A plain Validator inside a <field> will not be allowed and would generate error when parsing the xml, as it is not allowed in the defined dtd (xwork-validator-1.0.2.dtd)</p> - -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> - -<p>Declaring a FieldValidator using the <field-validator> syntax:</p> - -<div class="highlighter-rouge"><pre class="highlight"><code><field name="email_address"> - <field-validator type="required"> - <message>You cannot leave the email address field empty.</message> - </field-validator> - <field-validator type="email"> - <message>The email address you entered is not valid.</message> - </field-validator> -</field> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><validator</span> <span class="na">type=</span><span class="s">"required"</span> <span class="na">short-circuit=</span><span class="s">"true"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"fieldName"</span><span class="nt">></span>bar<span class="nt"></param></span> + <span class="nt"><message></span>You must enter a value for bar.<span class="nt"></message></span> +<span class="nt"></validator></span> +<span class="nt"><validator</span> <span class="na">type=</span><span class="s">"expression"</span><span class="nt">></span> + <span class="nt"><param</span> <span class="na">name=</span><span class="s">"expression"</span><span class="nt">></span>foo gt bar<span class="nt"></param></span> + <span class="nt"><message></span>foo must be great than bar.<span class="nt"></message></span> +<span class="nt"></validator></span> </code></pre> </div> -<p>The choice is yours. Itâs perfectly legal to only use elements without the elements and set the fieldName attribute for each of them. The following are effectively equal:</p> - -<div class="highlighter-rouge"><pre class="highlight"><code><field name="email_address"> - <field-validator type="required"> - <message>You cannot leave the email address field empty.</message> - </field-validator> - <field-validator type="email"> - <message>The email address you entered is not valid.</message> - </field-validator> -</field> - -<validator type="required"> - <param name="fieldName">email_address</param> - <message>You cannot leave the email address field empty.</message> -</validator> -<validator type="email"> - <param name="fieldName">email_address</param> - <message>The email address you entered is not valid.</message> -</validator> - -</code></pre> -</div> +<p>both validators will be run, even if the ârequiredâ validator short-circuits. ârequiredâ validators are FieldValidatorâs +and will not short-circuit the plain ExpressionValidator because FieldValidators only short-circuit other checks on that +same field. Since the plain Validator is not field specific, it is not short-circuited.</p> -<p>####Short-Circuiting Validator####</p> +<h2 id="how-validators-of-an-action-are-found">How Validators of an Action are Found</h2> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=shortCircuitingValidators1|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<p>As mentioned above, the framework will also search up the inheritance tree of the action to find default validations +for interfaces and parent classes of the Action. If you are using the short-circuit attribute and relying on default +validators higher up in the inheritance tree, make sure you donât accidentally short-circuit things higher in the tree +that you really want!</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=exShortCircuitingValidators|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<p>The effect of having common validators on both</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=shortCircuitingValidators2|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> - -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=scAndValidatorFlavours1|1=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> - -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=exScAndValidatorFlavours|lang=xml|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> - -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=scAndValidatorFlavours2|1=javadoc|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<ul> + <li><code class="highlighter-rouge"><actionClass>-validation.xml</code></li> + <li><code class="highlighter-rouge"><actionClass>-<actionAlias>-validation.xml</code></li> +</ul> -<p>####How Validators of an Action are Found####</p> +<p>It should be noted that the nett effect will be validation on both the validators available in both validation +configuration file. For example if we have ârequiredstringâ validators defined in both validation xml file for field +named âaddressâ, we will see 2 validation error indicating that the the address cannot be empty (assuming validation +failed). This is due to WebWork will merge validators found in both validation configuration files.</p> -<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="err">snippet:id=howXworkFindsValidatorForAction|javadoc=true|url=com.opensymphony.xwork2.validator/Validator.java</span><span class="p">}</span><span class="w"> -</span></code></pre> -</div> +<p>The logic behind this design decision is such that we could have common validators in <code class="highlighter-rouge"><actionClass>-validation.xml</code> +and more context specific validators to be located in <code class="highlighter-rouge"><actionClass>-<actionAlias>-validation.xml</code>.</p> -<p>####Writing custom validators####</p> +<h2 id="writing-custom-validators">Writing custom validators</h2> <p>If you want to write custom validator use on of these classes as a starting point:</p> <ul> - <li> - <p>com.opensymphony.xwork2.validator.validators.ValidatorSupport</p> - </li> - <li> - <p>com.opensymphony.xwork2.validator.validators.FieldValidatorSupport</p> - </li> - <li> - <p>com.opensymphony.xwork2.validator.validators.RangeValidatorSupport</p> - </li> - <li> - <p>com.opensymphony.xwork2.validator.validators.RepopulateConversionErrorFieldValidatorSupport</p> - </li> + <li><code class="highlighter-rouge">com.opensymphony.xwork2.validator.validators.ValidatorSupport</code></li> + <li><code class="highlighter-rouge">com.opensymphony.xwork2.validator.validators.FieldValidatorSupport</code></li> + <li><code class="highlighter-rouge">com.opensymphony.xwork2.validator.validators.RangeValidatorSupport</code></li> + <li><code class="highlighter-rouge">com.opensymphony.xwork2.validator.validators.RepopulateConversionErrorFieldValidatorSupport</code></li> </ul> -<p>####Resources####</p> +<h2 id="resources">Resources</h2> -<p><a href="http://today\.java\.net/pub/a/today/2006/01/19/webwork\-validation\.html";>WebWork Validation</a>^[http://today.java.net/pub/a/today/2006/01/19/webwork-validation.html]</p> +<p><a href="http://today.java.net/pub/a/today/2006/01/19/webwork-validation.html";>WebWork Validation</a></p> </section> </article> http://git-wip-us.apache.org/repos/asf/struts-site/blob/f694fc8f/content/core-developers/writing-interceptors.html ---------------------------------------------------------------------- diff --git a/content/core-developers/writing-interceptors.html b/content/core-developers/writing-interceptors.html index 8e42fd8..d4e16dd 100644 --- a/content/core-developers/writing-interceptors.html +++ b/content/core-developers/writing-interceptors.html @@ -129,111 +129,91 @@ <p>See the <a href="interceptors.html">Interceptors</a> page for an overview of how interceptors work.</p> -<p><strong>Interceptor interface</strong></p> +<h2 id="interceptor-interface">Interceptor interface</h2> -<p>Interceptors must implement the com.opensymphony.xwork2.interceptor.Interceptor interface.</p> +<p>Interceptors must implement the <code class="highlighter-rouge">com.opensymphony.xwork2.interceptor.Interceptor</code> interface.</p> <p><strong>Interceptor.java</strong></p> -<div class="highlighter-rouge"><pre class="highlight"><code> -public interface Interceptor extends Serializable { +<div class="highlighter-rouge"><pre class="highlight"><code><span class="kd">public</span> <span class="kd">interface</span> <span class="nc">Interceptor</span> <span class="kd">extends</span> <span class="n">Serializable</span> <span class="o">{</span> - void destroy(); + <span class="kt">void</span> <span class="n">destroy</span><span class="o">();</span> - void init(); - - String intercept(ActionInvocation invocation) throws Exception; -} + <span class="kt">void</span> <span class="n">init</span><span class="o">();</span> + <span class="n">String</span> <span class="n">intercept</span><span class="o">(</span><span class="n">ActionInvocation</span> <span class="n">invocation</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">Exception</span><span class="o">;</span> +<span class="o">}</span> </code></pre> </div> -<p>The <em>init</em> method is called the after interceptor is instantiated and before calling <em>intercept</em> . This is the place to allocate any resources used by the interceptor.</p> - -<p>The <em>intercept</em> method is where the interceptor code is written. Just like an action method, <em>intercept</em> returns a result used by Struts to forward the request to another web resource. Calling <em>invoke</em> on the parameter of type ActionInvocation will execute the action (if this is the last interceptor on the stack) or another interceptor.</p> - -<table> - <tbody> - <tr> - <td>Keep in mind that <em>invoke</em> will return <strong>after</strong> the result has been called (eg. after you JSP has been rendered), making it perfect for things like open-session-in-view patterns. If you want to do something before the result gets called, you should implement a PreResultListener.</td> - </tr> - </tbody> -</table> - -<table> - <tbody> - <tr> - </tr> - </tbody> -</table> - -<p>Overwrite <em>destroy</em> to release resources on application shutdown.</p> +<p>The <code class="highlighter-rouge">init</code> method is called the after interceptor is instantiated and before calling <code class="highlighter-rouge">intercept</code>. This is the place +to allocate any resources used by the interceptor.</p> -<p><strong>Thread Safety</strong></p> - -<p><strong>Interceptors must be thread-safe!</strong></p> +<p>The <code class="highlighter-rouge">intercept</code> method is where the interceptor code is written. Just like an action method, <code class="highlighter-rouge">intercept</code> returns +a result used by Struts to forward the request to another web resource. Calling <code class="highlighter-rouge">invoke</code> on the parameter of type +<code class="highlighter-rouge">ActionInvocation</code> will execute the action (if this is the last interceptor on the stack) or another interceptor.</p> <blockquote> - + <p>Keep in mind that <code class="highlighter-rouge">invoke</code> will return <strong>after</strong> the result has been called (eg. after you JSP has been rendered), +making it perfect for things like open-session-in-view patterns. If you want to do something before the result gets +called, you should implement a <code class="highlighter-rouge">PreResultListener</code>.</p> </blockquote> -<blockquote> +<p>Overwrite <code class="highlighter-rouge">destroy</code> to release resources on application shutdown.</p> -</blockquote> +<h2 id="thread-safety">Thread Safety</h2> -<blockquote> - <p>A Struts 2 Action instance is created for every request and do not need to be thread-safe. Conversely, Interceptors are shared between requests and must be <a href="http://en\.wikipedia\.org/wiki/Thread\-safety";>thread-safe</a>^[http://en.wikipedia.org/wiki/Thread-safety].</p> -</blockquote> +<p><strong>Interceptors must be thread-safe!</strong></p> <blockquote> - + <p>A Struts 2 Action instance is created for every request and do not need to be thread-safe. Conversely, Interceptors +are shared between requests and must be <a href="http://en.wikipedia.org/wiki/Thread-safety";>thread-safe</a>.</p> </blockquote> -<p><strong>AbstractInterceptor</strong></p> +<h2 id="abstractinterceptor">AbstractInterceptor</h2> -<p>The AbstractInterceptor class provides an empty implementation of <em>init</em> and <em>destroy</em> , and can be used if these methods are not going to be implemented.</p> +<p>The AbstractInterceptor class provides an empty implementation of <code class="highlighter-rouge">init</code> and <code class="highlighter-rouge">destroy</code>, and can be used if these +methods are not going to be implemented.</p> -<p><strong>Mapping</strong></p> +<h2 id="mapping">Mapping</h2> -<p>Interceptors are declared using the <em>interceptor</em> element, nested inside the <em>interceptors</em> element. Example from struts-default.xml:</p> +<p>Interceptors are declared using the <code class="highlighter-rouge"><interceptor/></code> element, nested inside the <code class="highlighter-rouge"><interceptors/></code> element. +Example from <code class="highlighter-rouge">struts-default.xml</code>:</p> -<div class="highlighter-rouge"><pre class="highlight"><code> -<struts> +<div class="highlighter-rouge"><pre class="highlight"><code><span class="nt"><struts></span> ... - <package name="struts-default"> - <interceptors> - <interceptor name="alias" class="com.opensymphony.xwork2.interceptor.AliasInterceptor"/> - <interceptor name="autowiring" class="com.opensymphony.xwork2.spring.interceptor.ActionAutowiringInterceptor"/> + <span class="nt"><package</span> <span class="na">name=</span><span class="s">"struts-default"</span><span class="nt">></span> + <span class="nt"><interceptors></span> + <span class="nt"><interceptor</span> <span class="na">name=</span><span class="s">"alias"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.interceptor.AliasInterceptor"</span><span class="nt">/></span> + <span class="nt"><interceptor</span> <span class="na">name=</span><span class="s">"autowiring"</span> <span class="na">class=</span><span class="s">"com.opensymphony.xwork2.spring.interceptor.ActionAutowiringInterceptor"</span><span class="nt">/></span> ... - </interceptors> - </package> + <span class="nt"></interceptors></span> + <span class="nt"></package></span> ... -</struts> - +<span class="nt"></struts></span> </code></pre> </div> -<p><strong>Example</strong></p> +<h3 id="example">Example</h3> -<p>Assuming there is an action of type âMyActionâ, with a setDate(Date) method, this simple interceptor will set the date of the action to the current date:</p> +<p>Assuming there is an action of type âMyActionâ, with a setDate(Date) method, this simple interceptor will set the date +of the action to the current date:</p> <p><strong>Interceptor Example</strong></p> -<div class="highlighter-rouge"><pre class="highlight"><code> -import com.opensymphony.xwork2.ActionInvocation; -import com.opensymphony.xwork2.interceptor.AbstractInterceptor; +<div class="highlighter-rouge"><pre class="highlight"><code><span class="kn">import</span> <span class="nn">com.opensymphony.xwork2.ActionInvocation</span><span class="o">;</span> +<span class="kn">import</span> <span class="nn">com.opensymphony.xwork2.interceptor.AbstractInterceptor</span><span class="o">;</span> -public class SimpleInterceptor extends AbstractInterceptor { - - public String intercept(ActionInvocation invocation) throws Exception { - MyAction action = (MyAction)invocation.getAction(); - action.setDate(new Date()); - return invocation.invoke(); - } -} +<span class="kd">public</span> <span class="kd">class</span> <span class="nc">SimpleInterceptor</span> <span class="kd">extends</span> <span class="n">AbstractInterceptor</span> <span class="o">{</span> + <span class="kd">public</span> <span class="n">String</span> <span class="n">intercept</span><span class="o">(</span><span class="n">ActionInvocation</span> <span class="n">invocation</span><span class="o">)</span> <span class="kd">throws</span> <span class="n">Exception</span> <span class="o">{</span> + <span class="n">MyAction</span> <span class="n">action</span> <span class="o">=</span> <span class="o">(</span><span class="n">MyAction</span><span class="o">)</span><span class="n">invocation</span><span class="o">.</span><span class="na">getAction</span><span class="o">();</span> + <span class="n">action</span><span class="o">.</span><span class="na">setDate</span><span class="o">(</span><span class="k">new</span> <span class="n">Date</span><span class="o">());</span> + <span class="k">return</span> <span class="n">invocation</span><span class="o">.</span><span class="na">invoke</span><span class="o">();</span> + <span class="o">}</span> +<span class="o">}</span> </code></pre> </div>
