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 }