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
006package fc.web.forms;
007
008import javax.servlet.*;
009import javax.servlet.http.*;
010import java.io.*;
011import java.util.*;
012
013import fc.jdbc.*;
014import fc.io.*;
015import fc.util.*;
016
017/** 
018Represents a form level validator that may examine more than
019one form field for a grouped/form level validation. Form level
020validators differ from {@link FieldValidator} because one may
021need to validate a group of fields together.
022<p>
023Examples include address validation where street, city and zip might
024need to be verified together (for a valid address) or password
025validation where two separate password boxes might need to be
026validated (to be identical). Various subclasses implement
027concrete code (via {@link #validate}) for various validation
028strategies. 
029<p>
030<b>Note 1</b>: Validator objects have state and a particular instance of a
031validator should only be assigned to one form field.
032<p>
033<b>Thread safety:</b> None of the validation classes (like all other
034form-related classes) are thread safe. Synchronization must be 
035done at a higher level, typically the session level. 
036
037@author hursh jain
038**/
039public abstract class FormValidator 
040{
041protected String  name;
042protected String  errorMessage;
043
044/** Creates a new validator and adds it to the specified
045form.
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**/
054public FormValidator(Form f, String name, String errorMessage)
055  {
056  this.name = name;
057  this.errorMessage = errorMessage;
058  f.addValidator(this);
059  }
060
061/** 
062Validates multiple fields together. Note, implementations need
063not call the validator for each field if that field also has a field
064level validator (since each field is individually validated by the
065form). Implementations should validate multiple fields to see if
066they make sense when analysed as a whole. 
067<p>
068<b>Important notes</b>:
069Typically, 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**/
077abstract public boolean validate(FormData fd, HttpServletRequest req);
078
079public String getErrorMessage() {
080  return errorMessage;
081  }
082
083/**
084Sets the error message for this validator -- useful when
085the error message need to be changed dynamically.
086*/
087public void setErrorMessage(String message) {
088  this.errorMessage = message;
089  }
090  
091public String getName() {
092  return name;
093  } 
094
095public String toString() {
096  return "Form validator: " + name;
097  }
098
099}          //~class FormValidator