001    package edu.nrao.sss.validation;
002    
003    import java.util.List;
004    
005    /**
006     * A validator of objects.
007     * The job of this validator is to look at target objects
008     * and see if they are suitable for using for a particular
009     * purpose.
010     * <p>
011     * Clients do not typically fetch a validator and use it to validate
012     * their target objects.  Instead they call the
013     * {@link ValidationManager#validate(Object, ValidationPurpose) validate}
014     * method of {@link ValidationManager}.</p>
015     * <p>
016     * <b>Version Info:</b>
017     * <table style="margin-left:2em">
018     *   <tr><td>$Revision: 868 $</td></tr>
019     *   <tr><td>$Date: 2007-09-12 13:15:10 -0600 (Wed, 12 Sep 2007) $</td></tr>
020     *   <tr><td>$Author: dharland $</td></tr>
021     * </table></p>
022     * 
023     * @author David M. Harland
024     * @since 2007-02-02
025     */
026    public interface Validator
027    {
028      /**
029       * Validates {@code target} for use for the given {@code purpose}.
030       * 
031       * @param target the object to be validated.
032       * 
033       * @param purpose the reason for the validation.
034       * 
035       * @return a list of failures encountered during validation.
036       *         If there were no failures, an empty list is returned.
037       */
038      public List<ValidationFailure> validate(Object            target,
039                                              ValidationPurpose purpose);
040      
041      /**
042       * Sets the manager for which this validator is performing its duties.
043       * It is not necessary for this validator to work for any manager;
044       * therefore <i>null</i> is an acceptable value for {@code newManager}.
045       * <p>
046       * The main use made by this validator of its manager is to request
047       * validators for the component objects held by the target object
048       * of this validator.</p>
049       * 
050       * @param newManager the manager for which this validator is performing
051       *                   its duties.
052       */
053      public void setManager(ValidationManager newManager);
054      
055      /**
056       * Tells this validator whether it should run all validations or stop
057       * after the first validation that fails.  The concrete implementations
058       * of this interface are free to choose their default behavior here.
059       * 
060       * @param stop if <i>true</i> this validator will stop running its
061       *             validations after the first one fails.
062       */
063      public void stopTestingAfterFirstFailure(boolean stop);
064    
065      /**
066       * Returns the name of this validator.
067       * A common construct is for a validator to return its fully qualified
068       * class name.
069       * 
070       * @return the name of this validator.
071       */
072      public String getName();
073      
074      /**
075       * Returns the object most recently subject to validation by this validator.
076       * 
077       * @return the object most recently subject to validation by this validator.
078       *         If this validator has not yet been used, the return value will
079       *         be <i>null</i>.
080       */
081      public Object getTarget();
082      
083      /**
084       * Returns the purpose for which this validator was most recently run.
085       * @return the purpose for which this validator was most recently run.
086       */
087      public ValidationPurpose getPurpose();
088    }