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 jakarta.servlet.*;
009import jakarta.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@param  f       the form to validate
048@param  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<code>DependentField.shouldValidate</code> method returns <code>false</code>.
074</ul>
075
076@return <code>true</code> is validation succeeded, <code>false</code> otherwise
077**/
078abstract public boolean validate(FormData fd, HttpServletRequest req);
079
080public String getErrorMessage() {
081  return errorMessage;
082  }
083
084/**
085Sets the error message for this validator -- useful when
086the error message need to be changed dynamically.
087*/
088public void setErrorMessage(String message) {
089  this.errorMessage = message;
090  }
091  
092public String getName() {
093  return name;
094  } 
095
096public String toString() {
097  return "Form validator: " + name;
098  }
099
100}          //~class FormValidator