<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V2.0//EN" "http://forrest.apache.org/dtd/document-v20.dtd">
<document>
	<header>
		<title>Data Validation</title>
	</header>
	<body>
		<section id="introduction">
			<title>Introduction</title>
		</section>
		<p>NetUI offers a declarative validation model.  This means that validation tasks are
			configured using metadata annotations within Page Flow controller classes.  
			Annotations for common validation tasks are already provided: e.g., 
			<a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.ValidateCreditCard.html">@Jpf.ValidateCreditCard</a>, 
			<a href="apidocs/javadoc/org/apache/beehive/netui/pageflow/annotations/Jpf.ValidateDate.html">@Jpf.ValidateDate</a>, etc.</p>

		<section id="validation_annos"><title>Validation Annotations</title>
		<p>Validation annotations can appear in three different places:</p>
		<ul>
			<li>Form Bean Getter Methods</li>
			<li>Action Methods</li>
			<li>Controller Class</li>
		</ul>
        <note>
            If you are using Struts 1.1 in your project, then you need to add an additional build step in order for
            these annotations to take effect. All generated Validator XML config files must be copied out of
            <code>/WEB-INF/classes/_pageflow</code> and into <code>/_pageflow</code>:
            <br/>
            <br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;delete dir="${web.build.dir}/_pageflow"/></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;mkdir dir="${web.build.dir}/_pageflow"/></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;copy todir="${web.build.dir}/_pageflow"></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;fileset dir="${web.build.dir}/WEB-INF/classes/_pageflow" includes="*-validation*.xml"/></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/copy></code><br/>
            <br/>
            <br/>
            Additionally, it is a good idea to make these files inaccessible from a web browser by adding the following
            entries in web.xml:
            <br/>
            <br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;filter></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;filter-name>PageFlowForbiddenFilter&lt;/filter-name></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;filter-class>org.apache.beehive.netui.pageflow.PageFlowForbiddenFilter&lt;/filter-class></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;init-param></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;param-name>response-code&lt;/param-name></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;param-value>404&lt;/param-value></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;/init-param></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/filter></code><br/>
            <br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;...</code><br/>
            <br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;filter-mapping></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;filter-name>PageFlowForbiddenFilter&lt;/filter-name></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;url-pattern>/_pageflow/*&lt;/url-pattern></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&lt;dispatcher>REQUEST&lt;/dispatcher></code><br/>
            <code>&nbsp;&nbsp;&nbsp;&nbsp;&lt;/filter-mapping></code><br/>
            <br/>
            <br/>
            By default, NetUI projects are configured with Struts 1.2.  This workaround is <strong>only</strong>
            necessary when using Struts 1.1.
        </note>

		<section id="bean-level"><title>...on the Form Bean Getter Methods</title>
		<p>
            Form bean getter methods are the simplest place to put validation annotations:
        </p>
        <source>    public static class MyForm implements Serializable
    {
        private String _date;

        @Jpf.ValidatableProperty(
            displayName="This field",
            validateRequired=@Jpf.ValidateRequired(),
            validateDate=@Jpf.ValidateDate(pattern="M-d-y")
        )
        public String getDate()
        {
            return _date;
        }

        public void setDate(String str)
        {
            _date = str;
        }
    }</source>
			</section>
		<section id="method-level"><title>...on the Action Method</title>
		<p>When the validation annotations are applied to the Action Method, you must 
			specify the Form Bean field to which validation will apply.  (You don't need to 
			specify the Form Bean class, because it is already specified by the 
			Bean parameter of the Action Method.)</p>
		<p><code>@Jpf.ValidatableProperty(propertyName)</code> 
			specifies the Form Bean field.</p>
		<source>
    @Jpf.Action(
        forwards={
            @Jpf.Forward(name="success", path="success.jsp")
        },
        validatableProperties={
            @Jpf.ValidatableProperty(
                <strong>propertyName="date"</strong>,
                displayName="This field",
                validateRequired=@Jpf.ValidateRequired(),
                validateDate=@Jpf.ValidateDate(pattern="M-d-y")
            )
        },
        validationErrorForward=@Jpf.Forward(name="fail", path="input.jsp")
    )
    public Forward submitForm(MyForm form)
    {
        return new Forward("success");
    }</source>
		</section>
		<section id="class-level"><title>...on the Controller Class</title>
		<p>The following class-level annotation says that anytime that an instance of 
			MyForm is submitted, then its <code>date</code> field will be validated 
			(against the pattern M-d-y).</p>
		<p>When the validation annotations decorate the Controller class,
			you must specify the Form Bean class and the Form Bean field to which validation 
			will apply.</p>
		<p><code>@Jpf.ValidateableBean(type)</code> specifies the Form Bean class.</p>
		<p><code>@Jpf.ValidatableProperty(propertyName)</code> specifies the Form Bean field.</p>
		<p>Note that the <code>propertyName</code> must match the setter/getter field name
			in the Bean.  In the example below, the setter/getter 
			field name is <strong>date</strong> (because the setter/getter methods are
			setDate(...)/getDate()).</p>
		<source>@Jpf.Controller(
    validatableBeans={
        @Jpf.ValidatableBean(
            <strong>type=Controller.MyForm.class</strong>,
            validatableProperties={
                @Jpf.ValidatableProperty(
                    <strong>propertyName="date"</strong>,
                    displayName="This field",
                    validateDate=@Jpf.ValidateDate(pattern="M-d-y")
                )
            }
        )
    }
)
public class Controller extends PageFlowController
{
    ...

    public static class MyForm implements Serializable
    {
        private String _date;

        public String getDate()
        {
            return _date;
        }

        public void setDate(String str)
        {
            _date = str;
        }	    
    }
}</source>
		</section>
		</section>
		<section id="error_handling"><title>Handling Validation Errors</title>
		<section id="default_error_handling"><title>Default Error Messages</title>
		<p>If validation fails, then an ActionMessage is written describing the error
			under the key <code>propertyNameValue</code>.  
		</p>
<source>                @Jpf.ValidatableProperty(
                    propertyName="<strong>propertyNameValue</strong>",
					...
                )</source>
		<p>	This error is retreivable
			by the &lt;netui:error> tag, using the matching key value.</p>
<source>        &lt;netui:form action="handleSubmit">
            Enter the date (MM-dd-YYYY):
            &lt;netui:textBox dataSource="actionForm.date"/>
            <strong>&lt;netui:error key="propertyNameValue"/></strong>
            &lt;br/>&lt;netui:button value="Submit"/>
        &lt;/netui:form></source>
		<p>The <code>propertyName</code> prepends a string to the error message produced.</p>
<source>                @Jpf.ValidatableProperty(
                    propertyName="propertyNameValue",
                    <strong>displayName="This field"</strong>,
                )</source>			
		<p>For example, if validation fails for a date field, the error message produced would 
			be "<code>This field</code>" + "<code>is not a date.</code>"</p>
		</section>
		<section id="other_message_resources"><title>Other Message Resources</title>
        <p>Other message resources can be specified through the 
			<code>message/messageKey/messageArgs</code>
			attributes.</p>
		<source>                @Jpf.ValidatableProperty(
                    propertyName = "item3",
                    validateMinLength = 
                        @Jpf.ValidateMinLength(
                            chars = 6,
                            message = "{0} {1} for {2} is {3} characters.",
                            messageArgs = {
                                @Jpf.MessageArg(
                                    arg = "The minimum",
                                    position = 0
                                ),
                                @Jpf.MessageArg(
                                    arg = "length"
                                ),
                                @Jpf.MessageArg(
                                    arg = "this field"
                                ),
                                @Jpf.MessageArg(
                                    arg = "six"
                                )
                            }
                        )
                </source>
		<p>If the <code>message/messageKey</code> attributes are not present, then the 
			default message key will be used ("<code>errors.date</code>" for 
			<code>@Jpf.ValidateRequired</code>, "<code>errors.minLength</code>" for 
			<code>@Jpf.ValidateMinLength</code>, etc.)</p>
		<p>If the <code>arg0/arg0Key, etc...</code> attributes are present,
			it is used as the first argument to the message; otherwise, the 
			<code>displayName/displayNameKey</code> attribute on the 
			<code>@Jpf.ValidatableProperty</code> is resolved for the first argument.</p>
		<p>Message resources can be associated with a Form Bean class:</p>
		<source>@Jpf.FormBean(defaultMessageBundle="myFormBean.errors")
public static class MyFormBean</source>
        <p>The &lt;netui:error> and &lt;netui:errors> tags will resolve validation messages in the
		following order:</p>
		<ol>
			<li>The default message bundle associated with the Controller class
<source>@Jpf.Controller(
    messageBundles = {
        @Jpf.MessageBundle(bundlePath = "validation.messages.messages")
    },</source></li>
			<li>The message bundle associated with the current Form Bean</li>
			<li>The fallback message bundle in beehive-netui-pageflow.jar.  
				This contains values for default validation messages (e.g., "This field
				is not a date.")</li>
		</ol>
		</section>
	    <section id="i18n"><title>Internationalization of Validation Rules</title>
		<p>In some cases the parameters to rules (and even the rules themselves) may change 
			depending on the locale.  Rules internationalization is supported through
			the <code>language, country, and variant</code> attributes on
			<code>@Jpf.ValidationRules</code>:</p>
		<source>    @Jpf.ValidatableProperty(
        localeRules={
            @Jpf.ValidationLocaleRules(
                language="fr",
                validateDate=@Jpf.ValidateDate(pattern="DD/MM/YYYY")
            ),
            @Jpf.ValidationLocaleRules(
                language="fr",
                country="CA",
                variant="Quebec",
                validateDate=@Jpf.ValidateDate(pattern="MM/DD/YYYY")
            )
        },
        validateRequired=@Jpf.ValidateRequired()  // this one applies to all locales
    )
    public String getDate()
    {
        ...</source>	
		</section>
		<section id="req_fields"><title>Required Fields</title>
		<p>Required fields can be marked using the <code>validateRequired</code> attribute.</p>
<source>                @Jpf.ValidatableProperty(
                    propertyName="propertyNameValue",
                    displayName="This field",
                    <strong>validateRequired=@Jpf.ValidateRequired()</strong>,
					...
                )</source>
		</section>
		<section id="post_error_nav"><title>Post-Error Navigation</title>
		<p>The action method handling the submit, specifies the JSP to go to, if the validation
			fails.</p>
	    <p>Typically, the user is returned to the same submission page, where the error message
			can prompt the user to correct the invalid submission.</p>

		<source>    @Jpf.Action(
        forwards={
            @Jpf.Forward(name="success", path="success.jsp")
        },
        <strong>validationErrorForward=@Jpf.Forward(name="fail", path="input.jsp")</strong>
    )
    public Forward handleSubmit(MyForm form)</source>
</section>	
	</section>
	</body>
	<footer>
		<legal>Java, J2EE, and JCP are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.<br/>
	&copy; 2004, Apache Software Foundation
	</legal>
	</footer>
</document>
