Source

xwork / docs / wikidocs / Standard Validators.html

<html>
    <head>
        <title>XWork : Standard Validators</title>
	    <link rel="stylesheet" href="styles/site.css" type="text/css" />
        <META http-equiv="Content-Type" content="text/html; charset=UTF-8">	    
    </head>

    <body>
	    <table class="pagecontent" border="0" cellpadding="0" cellspacing="0" width="100%" bgcolor="#ffffff">
		    <tr>
			    <td valign="top" class="pagebody">
				    <div class="pageheader">
					    <span class="pagetitle">
                            XWork : Standard Validators
                                                    </span>
				    </div>
				    <div class="pagesubheading">
					    This page last changed on Jul 16, 2004 by <font color="#0050B2">unkyaku</font>.
				    </div>

				    <p class="paragraph">These are the standard validators that come with XWork:
<ul class="star">
<li> <a href="#StandardValidators-RequiredFieldValidator" title="RequiredFieldValidator on Standard Validators">#RequiredFieldValidator</a></li>
<li> <a href="#StandardValidators-RequiredStringValidator" title="RequiredStringValidator on Standard Validators">#RequiredStringValidator</a></li>
<li> <a href="#StandardValidators-StringLengthFieldValidator" title="StringLengthFieldValidator on Standard Validators">#StringLengthFieldValidator</a></li>
<li> <a href="#StandardValidators-EmailValidator" title="EmailValidator on Standard Validators">#EmailValidator</a></li>
<li> <a href="#StandardValidators-URLValidator" title="URLValidator on Standard Validators">#URLValidator</a></li>
<li> <a href="#StandardValidators-IntRangeFieldValidator" title="IntRangeFieldValidator on Standard Validators">#IntRangeFieldValidator</a></li>
<li> <a href="#StandardValidators-DateRangeFieldValidator" title="DateRangeFieldValidator on Standard Validators">#DateRangeFieldValidator</a></li>
<li> <a href="#StandardValidators-ConversionErrorFieldValidator" title="ConversionErrorFieldValidator on Standard Validators">#ConversionErrorFieldValidator</a></li>
<li> <a href="#StandardValidators-ExpressionValidator" title="ExpressionValidator on Standard Validators">#ExpressionValidator</a></li>
<li> <a href="#StandardValidators-FieldExpressionValidator" title="FieldExpressionValidator on Standard Validators">#FieldExpressionValidator</a></li>
<li> <a href="#StandardValidators-VisitorFieldValidator" title="VisitorFieldValidator on Standard Validators">#VisitorFieldValidator</a></li>
</ul><br/>
All the example XML validation rule snippets below have been put together into one big example <a href="Sample Validation Rules.html" title="Sample Validation Rules">here</a>.</p><br clear="all" />
<a name="StandardValidators-RequiredFieldValidator"></a>
<h2 class="heading2"><a name="StandardValidators-RequiredFieldValidator"> RequiredFieldValidator</a></h2><p class="paragraph">This validator checks that a field is non-null.</p>Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;    <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;user&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;required&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message&gt;</span>You must enter a value for user.<span class="xml&#45;tag">&lt;/message&gt;</span>&#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div>
<p class="paragraph"><br clear="all" />
<a name="StandardValidators-RequiredStringValidator"></a>
<h2 class="heading2"><a name="StandardValidators-RequiredStringValidator"> RequiredStringValidator</a></h2></p>This validator checks that a String field is not empty (i.e. non-null with a length &gt; 0).  <br/>

<table class="wikitable">
<tr>
<th> Parameter </th><th> Required </th><th> Default </th><th> Notes </th>
</tr><tr>
<td> trim </td><td> no </td><td> true </td><td> Boolean property.  Determines whether the String is trimmed before performing the length check.  </td>
</tr>
</table><br/>
Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;    <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;userName&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;requiredstring&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message&gt;</span>You must enter an username.<span class="xml&#45;tag">&lt;/message&gt;</span>&#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div>
<p class="paragraph"><br clear="all" />
<a name="StandardValidators-StringLengthFieldValidator"></a>
<h2 class="heading2"><a name="StandardValidators-StringLengthFieldValidator"> StringLengthFieldValidator</a></h2></p>This validator checks that a String field is of the right length.  It assumes that the field is a String.<br/>

<table class="wikitable">
<tr>
<th> Parameter </th><th> Required </th><th> Default </th><th> Notes </th>
</tr><tr>
<td> trim </td><td> no </td><td> true </td><td> Boolean property.  Determines whether the String is trimmed before performing the length check.  </td>
</tr><tr>
<td> minLength </td><td> no </td><td> </td><td> Integer property.  The minimum length the String must be. </td>
</tr><tr>
<td> maxLength </td><td> no </td><td> </td><td> Integer property.  The maximum length the String can be. </td>
</tr>
</table><br/>
If neither <em class="emphasis">minLength</em> nor <em class="emphasis">maxLength</em> is set, nothing will be done.<p class="paragraph">Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;    <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;userName&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;stringlength&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;param name=<span class="xml&#45;quote">&quot;minLength&quot;</span>&gt;</span>3<span class="xml&#45;tag">&lt;/param&gt;</span>&#10;            <span class="xml&#45;tag">&lt;param name=<span class="xml&#45;quote">&quot;maxLength&quot;</span>&gt;</span>10<span class="xml&#45;tag">&lt;/param&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message&gt;</span>Username must be between $&#123;minLength&#125; and $&#123;maxLength&#125; characters long.<span class="xml&#45;tag">&lt;/message&gt;</span>&#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div></p><br clear="all" />
<a name="StandardValidators-EmailValidator"></a>
<h2 class="heading2"><a name="StandardValidators-EmailValidator"> EmailValidator</a></h2><p class="paragraph">This validator checks that a field is a valid e-mail address if it contains a non-empty String.</p>Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;    <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;email&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;email&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message&gt;</span>You must enter a valid email address.<span class="xml&#45;tag">&lt;/message&gt;</span>&#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div>
<p class="paragraph"><br clear="all" />
<a name="StandardValidators-URLValidator"></a>
<h2 class="heading2"><a name="StandardValidators-URLValidator"> URLValidator</a></h2></p>This validator checks that a field is a valid URL.<p class="paragraph">Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;     <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;homepage&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;url&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message&gt;</span>You must enter a valid URL.<span class="xml&#45;tag">&lt;/message&gt;</span>            &#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div></p><br clear="all" />
<a name="StandardValidators-IntRangeFieldValidator"></a>
<h2 class="heading2"><a name="StandardValidators-IntRangeFieldValidator"> IntRangeFieldValidator</a></h2><p class="paragraph">This validator checks that a numeric field has a value within a specified range.</p><table class="wikitable">
<tr>
<th> Parameter </th><th> Required </th><th> Default </th><th> Notes </th>
</tr><tr>
<td> min </td><td> no </td><td> </td><td> Integer property.  The minimum the number must be. </td>
</tr><tr>
<td> max </td><td> no </td><td> </td><td> Integer property.  The maximum number can be. </td>
</tr>
</table><br/>
If neither <em class="emphasis">min</em> nor <em class="emphasis">max</em> is set, nothing will be done.<p class="paragraph">Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;    <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;age&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;int&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;param name=<span class="xml&#45;quote">&quot;min&quot;</span>&gt;</span>0<span class="xml&#45;tag">&lt;/param&gt;</span>&#10;            <span class="xml&#45;tag">&lt;param name=<span class="xml&#45;quote">&quot;max&quot;</span>&gt;</span>100<span class="xml&#45;tag">&lt;/param&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message&gt;</span>Not a valid age&#33;<span class="xml&#45;tag">&lt;/message&gt;</span>&#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div></p><br clear="all" />
<a name="StandardValidators-DateRangeFieldValidator"></a>
<h2 class="heading2"><a name="StandardValidators-DateRangeFieldValidator">  DateRangeFieldValidator</a></h2><p class="paragraph">This validator checks that a date field has a value within a specified range.</p><table class="wikitable">
<tr>
<th> Parameter </th><th> Required </th><th> Default </th><th> Notes </th>
</tr><tr>
<td> min </td><td> no </td><td> </td><td> Date property.  The minimum the date must be. </td>
</tr><tr>
<td> max </td><td> no </td><td> </td><td> Date property.  The maximum date can be. </td>
</tr>
</table><br/>
If neither <em class="emphasis">min</em> nor <em class="emphasis">max</em> is set, nothing will be done.<p class="paragraph">Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;    <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;startDate&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;date&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;param name=<span class="xml&#45;quote">&quot;min&quot;</span>&gt;</span>12/22/2002<span class="xml&#45;tag">&lt;/param&gt;</span>&#10;            <span class="xml&#45;tag">&lt;param name=<span class="xml&#45;quote">&quot;max&quot;</span>&gt;</span>12/25/2002<span class="xml&#45;tag">&lt;/param&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message&gt;</span>The date must be between 12&#45;22&#45;2002 and 12&#45;25&#45;2002.<span class="xml&#45;tag">&lt;/message&gt;</span>&#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div></p><br clear="all" />
<a name="StandardValidators-ConversionErrorFieldValidator"></a>
<h2 class="heading2"><a name="StandardValidators-ConversionErrorFieldValidator"> ConversionErrorFieldValidator</a></h2><p class="paragraph">This validator checks if there are any conversion errors for a field and applies them if they exist.  See <a href="Type Conversion Error Handling.html" title="Type Conversion Error Handling">Type Conversion Error Handling</a> for details.</p>Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;    <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;startDate&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;conversion&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message&gt;</span>Could not convert input to a valid date.<span class="xml&#45;tag">&lt;/message&gt;</span>&#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div>
<p class="paragraph"><br clear="all" />
<a name="StandardValidators-ExpressionValidator"></a>
<h2 class="heading2"><a name="StandardValidators-ExpressionValidator"> ExpressionValidator</a></h2></p>This validator uses an <a href="OGNL.html" title="Ognl">OGNL</a> expression to perform its validation.  The error message will be added to the <b class="strong">action</b> if the expression returns false when it is evaluated against the value stack.<br/>

<table class="wikitable">
<tr>
<th> Parameter </th><th> Required </th><th> Default </th><th> Notes </th>
</tr><tr>
<td> expression </td><td> yes </td><td> </td><td> An OGNL expression that returns a boolean value.  </td>
</tr>
</table><br/>
Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validator type=<span class="xml&#45;quote">&quot;expression&quot;</span>&gt;</span>&#10;    <span class="xml&#45;tag">&lt;param name=<span class="xml&#45;quote">&quot;expression&quot;</span>&gt;</span>foo &gt; bar<span class="xml&#45;tag">&lt;/param&gt;</span>&#10;    <span class="xml&#45;tag">&lt;message default=<span class="xml&#45;quote">&quot;Foo must be greater than Bar. Foo = $&#123;foo&#125;, Bar = $&#123;bar&#125;.&quot;</span>/&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validator&gt;</span></pre>
</div></div>
<p class="paragraph"><br clear="all" />
<a name="StandardValidators-FieldExpressionValidator"></a>
<h2 class="heading2"><a name="StandardValidators-FieldExpressionValidator"> FieldExpressionValidator</a></h2></p>This validator uses an <a href="OGNL.html" title="Ognl">OGNL</a> expression to perform its validation.  The error message will be added to the <b class="strong">field</b> if the expression returns false when it is evaluated against the value stack. <br/>

<table class="wikitable">
<tr>
<th> Parameter </th><th> Required </th><th> Default </th><th> Notes </th>
</tr><tr>
<td> expression </td><td> yes </td><td> </td><td> An OGNL expression that returns a boolean value.  </td>
</tr>
</table><br/>
Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;     <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;homepage&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;fieldexpression&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;param name=<span class="xml&#45;quote">&quot;expression&quot;</span>&gt;</span>homepage.indexOf(&#039;opensymphony.com&#039;) == &#45;1<span class="xml&#45;tag">&lt;/param&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message&gt;</span>Please provide an OpenSymphony website<span class="xml&#45;tag">&lt;/message&gt;</span>&#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div>
<p class="paragraph"><br clear="all" />
<a name="StandardValidators-VisitorFieldValidator"></a>
<h2 class="heading2"><a name="StandardValidators-VisitorFieldValidator"> VisitorFieldValidator</a></h2></p>The validator allows you to forward validation to object properties of your action using the objects own validation files. This allows you to use the ModelDriven development pattern and manage your validations for your models in one place, where they belong, next to your model classes. The VisitorFieldValidator can handle either simple Object properties, Collections of Objects, or Arrays.<p class="paragraph">The error message for the VisitorFieldValidator will be appended in front of validation messages added by the validations for the Object message.</p><table class="wikitable">
<tr>
<th> Parameter </th><th> Required </th><th> Default </th><th> Notes </th>
</tr><tr>
<td> context </td><td> no </td><td> action alias </td><td> Determines the context to use for validating the Object property. If not defined, the context of the Action validation is propogated to the Object property validation.  In the case of Action validation, this context is the Action alias.  </td>
</tr><tr>
<td> appendPrefix </td><td> no </td><td> true </td><td> Determines whether the field name of this field validator should be prepended to the field name of the visited field to determine the full field name when an error occurs.  For example, suppose that the bean being validated has a &quot;name&quot; property.  If <em class="emphasis">appendPrefix</em> is true, then the field error will be stored under the field &quot;bean.name&quot;.  If <em class="emphasis">appendPrefix</em> is false, then the field error will be stored under the field &quot;name&quot;.  <br clear="all" />
<img src="./icons/emoticons/warning.png" height="16" width="16" align="absmiddle" alt="" border="0"/> If you are using the VisitorFieldValidator to validate the model from a ModelDriven Action, you should set <em class="emphasis">appendPrefix</em> to false unless you are using &quot;model.name&quot; to reference the properties on your model. </td>
</tr>
</table><br/>
Example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;    <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;user&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;visitor&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;param name=<span class="xml&#45;quote">&quot;context&quot;</span>&gt;</span>anotherContext<span class="xml&#45;tag">&lt;/param&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message&gt;</span>user: <span class="xml&#45;tag">&lt;/message&gt;</span>&#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div><p class="paragraph">Here we see the <em class="emphasis">context</em> being overridden in the validator mapping, so the action alias context will not be propogated.</p>ModelDriven example:
<div class="code"><div class="codeContent">
<pre><span class="xml&#45;tag">&lt;validators&gt;</span>&#10;    <span class="xml&#45;tag">&lt;field name=<span class="xml&#45;quote">&quot;model&quot;</span>&gt;</span>&#10;        <span class="xml&#45;tag">&lt;field&#45;validator type=<span class="xml&#45;quote">&quot;visitor&quot;</span>&gt;</span>&#10;            <span class="xml&#45;tag">&lt;param name=<span class="xml&#45;quote">&quot;appendPrefix&quot;</span>&gt;</span>false<span class="xml&#45;tag">&lt;/param&gt;</span>&#10;            <span class="xml&#45;tag">&lt;message /&gt;</span>&#10;        <span class="xml&#45;tag">&lt;/field&#45;validator&gt;</span>&#10;    <span class="xml&#45;tag">&lt;/field&gt;</span>&#10;<span class="xml&#45;tag">&lt;/validators&gt;</span></pre>
</div></div><p class="paragraph">This will use the model&#039;s validation rules and any errors messages will be applied directly (nothing is prefixed because of the empty message).</p>

				    
                    			    </td>
		    </tr>
	    </table>
	    <table border="0" cellpadding="0" cellspacing="0" width="100%">
			<tr>
				<td height="12" background="border/border_bottom.gif"><img src="border/spacer.gif" width="1" height="1" border="0"/></td>
			</tr>
		    <tr>
			    <td align="center"><font color="grey">Document generated by Confluence on Sep 07, 2004 00:34</font></td>
		    </tr>
	    </table>
    </body>
</html>