001    // Copyright (c) 2001 Hursh Jain (http://www.mollypages.org) 
002    // The Molly framework is freely distributable under the terms of an
003    // MIT-style license. For details, see the molly pages web site at:
004    // http://www.mollypages.org/. Use, modify, have fun !
005    
006    package fc.web.forms;
007    
008    import javax.servlet.*;
009    import javax.servlet.http.*;
010    import java.io.*;
011    import java.util.*;
012    
013    import fc.jdbc.*;
014    import fc.io.*;
015    import fc.util.*;
016    
017    /** 
018    Represents a form level validator that may examine more than
019    one form field for a grouped/form level validation. Form level
020    validators differ from {@link FieldValidator} because one may
021    need to validate a group of fields together.
022    <p>
023    Examples include address validation where street, city and zip might
024    need to be verified together (for a valid address) or password
025    validation where two separate password boxes might need to be
026    validated (to be identical). Various subclasses implement
027    concrete code (via {@link #validate}) for various validation
028    strategies. 
029    <p>
030    <b>Note 1</b>: Validator objects have state and a particular instance of a
031    validator should only be assigned to one form field.
032    <p>
033    <b>Thread safety:</b> None of the validation classes (like all other
034    form-related classes) are thread safe. Synchronization must be 
035    done at a higher level, typically the session level. 
036    
037    @author hursh jain
038    **/
039    public abstract class FormValidator 
040    {
041    protected String  name;
042    protected String  errorMessage;
043    
044    /** Creates a new validator and adds it to the specified
045    form.
046    
047    @parm f       the form to validate
048    @pararm name      an arbitrary name for this group validator (used in
049                debugging and logging messages)
050    @param  errorMessage  the error message associated with invalid data
051                See {@link #getErrorMessage}
052    
053    **/
054    public FormValidator(Form f, String name, String errorMessage)
055      {
056      this.name = name;
057      this.errorMessage = errorMessage;
058      f.addValidator(this);
059      }
060    
061    /** 
062    Validates multiple fields together. Note, implementations need
063    not call the validator for each field if that field also has a field
064    level validator (since each field is individually validated by the
065    form). Implementations should validate multiple fields to see if
066    they make sense when analysed as a whole. 
067    <p>
068    <b>Important notes</b>:
069    Typically, validation should be skipped in the following circumstances:
070    <ul>
071    <li>The field is disabled.
072    <li>The field is an instance of {@link DependentField} and the
073    {@link DependentField#shouldValidate} method returns <tt>false</tt>.
074    
075    @return <tt>true</tt> is validation succeeded, <tt>false</tt> otherwise
076    **/
077    abstract public boolean validate(FormData fd, HttpServletRequest req);
078    
079    public String getErrorMessage() {
080      return errorMessage;
081      }
082    
083    /**
084    Sets the error message for this validator -- useful when
085    the error message need to be changed dynamically.
086    */
087    public void setErrorMessage(String message) {
088      this.errorMessage = message;
089      }
090      
091    public String getName() {
092      return name;
093      } 
094    
095    public String toString() {
096      return "Form validator: " + name;
097      }
098    
099    }          //~class FormValidator