org.jscience.sociology.forms
Interface GroupValidator

All Superinterfaces:
java.io.Serializable
All Known Implementing Classes:
PasswordGroup, SimpleGroup

public interface GroupValidator
extends java.io.Serializable

Defines the interface for classes that will play the role of group-validators.
The simplest criteria of inter-validation in a group of fields is - fields of one group are not required (to be filled or selected) unless one of them is. This criteria of validation is implemented by org.jscience.sociology.forms.util.SimpleGroup class.
Another common criteria is used when submitting a password - fields of one group must have the same value. Class org.jscience.sociology.forms.util.PasswordGroup provides such an implementation for two password fields.
In forms.xml you add a GroupValidator like this:

 <field name="field name"
   type="org.jscience.sociology.forms.TextBox">
   ...............
   ...............
   <field-groupValidator>
      GroupValidator object name
   </field-groupValidator>
 </field>
 

One FormElement object can not be registered in more than one GroupValidator.


Method Summary
 java.util.Hashtable getErrorMessages(java.util.Hashtable nameValuePairs)
           This method takes as argument an Hashtable of : key - a string representing the field name.
 void setGroupErrorMessage(java.lang.String groupErrorMessage)
          This is a utility method that can be used to set or customize an error message that may be used by all fields of this group.
 

Method Detail

getErrorMessages

java.util.Hashtable getErrorMessages(java.util.Hashtable nameValuePairs)
 This method takes as argument an Hashtable of :
  key   - a string representing the field name.
  value - a string or an array of strings representing the value, or the values
  of the corresponding field.
 

This method must return an Hashtable of : key - a string representing the name of the field that resulted with an error message (according to validation). value - a string representing the error message of the field. or it must return null, in case the validation found no errors.

Five important notes : 1 - With TextBox-es, PasswordBox-es and RadioButton-s, their value will come as a simple string. 2 - With subclasses of MultipleChoiceBox-es, their value(s) will come as an array of strings. 3 - When the client does not enter a value or does not make a selection to a field, the value of that field will come as an empty string, or as an array of only one string, whose value is empty. 4 - The nameValuePairs Hashtable will include all fields of this group. 5 - Only name-errormessage pairs of the fields with error messages must be included in the returned Hashtable, and if there aren't any, null must be returned.

Parameters:
nameValuePairs - name-value pairs to be tested.
Returns:
a Hashtable of name-errormessage pairs.

setGroupErrorMessage

void setGroupErrorMessage(java.lang.String groupErrorMessage)
This is a utility method that can be used to set or customize an error message that may be used by all fields of this group.

For example, in a group of password fields you might want to set an error message like "(passwords must be the same)" that will apply to both fields. Implementation classes may supply a default error message, and then let this method to customize it. See org.jscience.sociology.forms.util.PasswordGroup source code.

In forms.xml you set this error message through the attribute errormessage of the field-groupValidator tag.

If you are not interested in this method, you can just empty implement it and then ignore the errormessage attribute of field-groupValidator tag.

Parameters:
groupErrorMessage - an error message for all fields of the group.