import java.lang.annotation.Annotation;

/**
 * A constraint validator for a particular annotation
 *
 * @author Gavin King
 */
public interface Validator<A extends Annotation> {
  /**
   * does the object/element pass the constraints
   */
  public boolean isValid(Object value);

  /**
   * Take the annotations values
   * @param parameters
   */
  public void initialize(A parameters);
}

import java.io.Serializable;

/**
 * A single violation of a class level or method level constraint.
 *
 * @author Gavin King
 */
public class InvalidValue implements Serializable {
  private final String message;
  private final Object value;
  private final String propertyName;
  private final Class beanClass;
  private final Object bean;
  private Object rootBean;

  public Object getRootBean() {
    return rootBean;
  }

  public String getPropertyPath() {
    return propertyPath;
  }

  private String propertyPath;

  public InvalidValue(String message, Class beanClass, String propertyName, Object value, Object bean) {
    this.message = message;
    this.value = value;
    this.beanClass = beanClass;
    this.propertyName = propertyName;
    this.bean = bean;
    this.rootBean = bean;
    this.propertyPath = propertyName;
  }

  public void addParentBean(Object parentBean, String propertyName) {
    this.rootBean = parentBean;
    this.propertyPath = propertyName + "." + this.propertyPath;
  }

  public Class getBeanClass() {
    return beanClass;
  }

  public String getMessage() {
    return message;
  }

  public String getPropertyName() {
    return propertyName;
  }

  public Object getValue() {
    return value;
  }

  public Object getBean() {
    return bean;
  }

  public String toString() {
    return propertyName + ' ' + message;
  }

} 

/**
 * Engine that take a bean and check every expressed annotation restrictions
 *
 * @author Gavin King
 */
public class ClassValidator<T> implements Serializable {
  private static Log log = LogFactory.getLog( ClassValidator.class );
  private static final InvalidValue[] EMPTY_INVALID_VALUE_ARRAY = new InvalidValue[]{};
  private final Class<T> beanClass;
  private transient ResourceBundle messageBundle;
  private transient boolean defaultResourceBundle;

  private final transient Map<Class, ClassValidator> childClassValidators;
  private transient List<Validator> beanValidators;
  private transient List<Validator> memberValidators;
  private transient List<Member> memberGetters;
  private transient Map<Validator, String> messages;
  private transient List<Member> childGetters;
  private static final String DEFAULT_VALIDATOR_MESSAGE = "org.hibernate.validator.resources.DefaultValidatorMessages";


  /**
   * create the validator engine for this bean type
   */
  public ClassValidator(Class<T> beanClass) {
    this( beanClass, null );
  }

  /**
   * create the validator engine for a particular bean class, using a resource bundle
   * for message rendering on violation
   */
  public ClassValidator(Class<T> beanClass, ResourceBundle resourceBundle) {
    this( beanClass, resourceBundle, new HashMap<Class, ClassValidator>() );
  }

  protected ClassValidator(
      Class<T> beanClass, ResourceBundle resourceBundle, Map<Class, ClassValidator> childClassValidators
  ) {
    this.beanClass = beanClass;
    this.messageBundle = resourceBundle == null ?
        getDefaultResourceBundle() :
        resourceBundle;
    this.childClassValidators = childClassValidators;
    initValidator( beanClass, childClassValidators, this.messageBundle );  //重要的是該初始化函數
  }

  private ResourceBundle getDefaultResourceBundle() {
    ResourceBundle rb;
    try {
      rb = ResourceBundle.getBundle( "ValidatorMessages" );
    }
    catch( MissingResourceException e) {
      //the user did not override the default ValidatorMessages
      log.debug( "ResourceBundle ValidatorMessages not found. Delegate to " + DEFAULT_VALIDATOR_MESSAGE);
      rb = ResourceBundle.getBundle( DEFAULT_VALIDATOR_MESSAGE );
    }
    defaultResourceBundle = true;
    return rb;
  }

  private void initValidator(
      Class<T> beanClass, Map<Class, ClassValidator> childClassValidators,
      ResourceBundle resourceBundle
  ) {
    beanValidators = new ArrayList<Validator>(); // 保存類級別的驗證約束實現類
    memberValidators = new ArrayList<Validator>(); // 保存方法級別的驗證約束實現類
    memberGetters = new ArrayList<Member>();// 保存類的成員(字段or方法)和構造函數方法的標識信息
    messages = new HashMap<Validator, String>(); // 利用Map保存與每個Validator相對應的驗證消息
    childGetters = new ArrayList<Member>();//  保存子類的成員(字段or方法)和構造函數方法的標識信息

    childClassValidators.put( beanClass, this ); //map Map<Class, ClassValidator> childClassValidators;
    Annotation[] classAnnotations = beanClass.getAnnotations();
    for ( int i = 0; i < classAnnotations.length ; i++ ) {
      Annotation classAnnotation = classAnnotations[i];
     Validator beanValidator = createValidator( classAnnotation );//根據Annotation來得到Validator,參考對該函數的解釋
      if ( beanValidator != null ) beanValidators.add( beanValidator );//保存該Validator
    }
    //build the class hierarchy to look for members in
    Collection<Class> classes = new HashSet<Class>();
    addSuperClassesAndInterfaces( beanClass, classes );//把beanClass的所有超類和實現的接口添加的集合classes中

    //Check on all selected classes
    for ( Class currClass : classes ) {
      Method[] methods = currClass.getDeclaredMethods();// 掃描Method上面的注釋
      for ( int i = 0; i < methods.length ; i++ ) {
        Method method = methods[i];
        createMemberValidator( method ); // 創建方法上的約束實現類(Validator), 參考對該函數的解釋
        Class clazz = method.getReturnType();// 得到該方法的返回類型
        createChildValidator( resourceBundle, method, clazz );// 創建子類的Validator
      }

      Field[] fields = currClass.getDeclaredFields(); // 掃描Field上面的注釋, 下面和上面Method的實現一樣
      for ( int i = 0; i < fields.length ; i++ ) {
        Field field = fields[i];
        createMemberValidator( field );
        Class clazz = field.getType();
        createChildValidator( resourceBundle, field, clazz );
      }
    }
  }

  private void addSuperClassesAndInterfaces(Class clazz, Collection<Class> classes) {
    for ( Class currClass = clazz; currClass != null ; currClass = currClass.getSuperclass() ) {
      if ( ! classes.add( currClass ) ) return;
      Class[] interfaces = currClass.getInterfaces();
      for (Class interf : interfaces) {
        addSuperClassesAndInterfaces( interf, classes );
      }
    }
  }

  /**
   * 創建內嵌類的Validator. 如果該內嵌類被Valid Annotation 注釋的話則 
   * 創建另外一個ClassValidator
   * @param resourceBundle
   * @param member
   * @param clazz
   */
  private void createChildValidator(ResourceBundle resourceBundle, Member member, Class clazz) {
    if ( ( (AnnotatedElement) member ).isAnnotationPresent( Valid.class ) ) {
      setAccessible( member );
      childGetters.add( member );
      if ( !childClassValidators.containsKey( clazz ) ) {
        new ClassValidator( clazz, resourceBundle, childClassValidators );
      }
    }
  }

  /**
   * 利用傳入的Method(實現了AnnotatedElement, GenericDeclaration, Member接口)
   * 得到 方法上的Annotations 然后利用私有方法createValidator(Annotation a)來創建
   * 每一個Annotation 的實現類 Validator 并保存Validator和member
   * @param member
   */
  private void createMemberValidator(Member member) {
    Annotation[] memberAnnotations = ( (AnnotatedElement) member ).getAnnotations();
    for ( int j = 0; j < memberAnnotations.length ; j++ ) {
      Annotation methodAnnotation = memberAnnotations[j];
      Validator propertyValidator = createValidator( methodAnnotation );
      if ( propertyValidator != null ) {
        memberValidators.add( propertyValidator );
        setAccessible( member ); // 設置訪問屬性
        memberGetters.add( member );
      }
    }
  }

  private static void setAccessible(Member member) {
    if ( !Modifier.isPublic( member.getModifiers() ) ) {
      ( (AccessibleObject) member ).setAccessible( true );
    }
  }

  /**
   * 該方法產生了該Annotation的約束實現類 并初始化該類對應的消息
   */
  private Validator createValidator(Annotation annotation) {
    try {
      //得到ValidatorClass Annotation 
      ValidatorClass validatorClass = annotation.annotationType().getAnnotation( ValidatorClass.class );
      if ( validatorClass == null ) {
        return null;
      }
      // 然后 利用ValidatorClass Annotation 來得到里面的值(即實現該注釋的Class),
      //再利用Class 構造一個instance
      Validator beanValidator = validatorClass.value().newInstance();
      beanValidator.initialize( annotation ); // 初始化Annotation中的參數(注意:在自定義約束中該方法有你來實現)
      String messageTemplate = (String) annotation.getClass()
          .getMethod( "message", (Class[]) null )
          .invoke( annotation );  // 取得 constraint descriptor  中的message 的值
      String message = replace( messageTemplate, annotation ); // 初始化取得的模板消息 請參考 replace函數
      messages.put( beanValidator, message ); // 把message 放在map中,以便使用
      return beanValidator; // 返回 產生的Validator
    }
    catch (Exception e) {
      throw new IllegalArgumentException( "could not instantiate ClassValidator", e );
    }
  }

  public boolean hasValidationRules() {
    return beanValidators.size() != 0 || memberValidators.size() != 0;
  }

  /**
   * apply constraints on a bean instance and return all the failures.
   */
  public InvalidValue[] getInvalidValues(T bean) {
    return this.getInvalidValues( bean, new IdentitySet() );
  }

  /**
   * apply constraints on a bean instance and return all the failures.
   */
  protected InvalidValue[] getInvalidValues(T bean, Set<Object> circularityState) {
    if ( circularityState.contains( bean ) ) {  // 該if else 是和Hibernate Core由關的,
      return EMPTY_INVALID_VALUE_ARRAY; //Avoid circularity
    }
    else {
      circularityState.add( bean );
    }

    if ( !beanClass.isInstance( bean ) ) { // 如果beanClass不是該bean的實例,則拋出異常
      throw new IllegalArgumentException( "not an instance of: " + bean.getClass() );
    }

    List<InvalidValue> results = new ArrayList<InvalidValue>();

    for ( int i = 0; i < beanValidators.size() ; i++ ) { // 驗證類級別的約束
      Validator validator = beanValidators.get( i );
      if ( !validator.isValid( bean ) ) { //調用isValid方法,如果沒有通過則添加到list<InvalidValue>中
                        //如果是自定義約束則isValid方法 由你來實現
        results.add( new InvalidValue( messages.get( validator ), beanClass, null, bean, bean ) );
      }
    }

    for ( int i = 0; i < memberValidators.size() ; i++ ) {//驗證方法級別的約束
      Member getter = memberGetters.get( i );
      if ( Hibernate.isPropertyInitialized(bean, getter.getName() ) ) {// ? 檢查該屬性是否已初始化
        Object value = getMemberValue( bean, getter );//利用反射 取得該屬性的值
        Validator validator = memberValidators.get( i ); //取得該約束的驗證實現類
        if ( !validator.isValid( value ) ) {//調用isValid方法,如果沒有通過則添加到list<InvalidValue>中
          String propertyName = getPropertyName( getter );
          results.add( new InvalidValue( messages.get( validator ), beanClass, propertyName, value, bean ) );
        }
      }
    }

    for ( int i = 0; i < childGetters.size() ; i++ ) {// 處理子類類
      Member getter = childGetters.get( i );
      if ( Hibernate.isPropertyInitialized(bean, getter.getName() ) ) { //檢查該屬性是否已初始化
        Object value = getMemberValue( bean, getter );
        if ( value != null && Hibernate.isInitialized( value ) ) {
          String propertyName = getPropertyName( getter );
          InvalidValue[] invalidValues = getClassValidator( value )
              .getInvalidValues( value, circularityState );// 通過參數value 得到 Class, 然后由Class作為key          //在childClassValidators map中得到其ClassValidator
                                     //如果不存在 則創建新的 ,然后再調用ClassValidator的getInvalidValues方法
          // 注意在調用getInvalidValues方法時 用到了circularityState 參數, 當調用循環一周時 返回(遞歸結束)
          for ( InvalidValue invalidValue : invalidValues ) {
            invalidValue.addParentBean( bean, propertyName );
            results.add( invalidValue ); //添加的結果中
          }
        }
      }
    }

    return results.toArray( new InvalidValue[results.size()] ); //返回InvalidValue數組
  }

  /**
   * 通過參數value 得到 Class, 然后由Class作為key 在childClassValidators map中得到其ClassValidator
   * 如果不存在 則創建新的 然后返回
   * @param value
   * @return
   */
  private ClassValidator getClassValidator(Object value) {
    Class clazz = value.getClass();
    ClassValidator validator = childClassValidators.get( clazz );
    if ( validator == null ) { //handles polymorphism
      validator = new ClassValidator( clazz );
    }
    return validator;
  }

  /**
   * Apply constraints of a particular property on a bean instance and return all the failures.
   * Note this is not recursive.
   * 驗證單個屬性的約束.
   */
  //TODO should it be recursive ?
  public InvalidValue[] getInvalidValues(T bean, String propertyName) {
    List<InvalidValue> results = new ArrayList<InvalidValue>();

    for ( int i = 0; i < memberValidators.size() ; i++ ) {
      Member getter = memberGetters.get( i );
      if ( getPropertyName( getter ).equals( propertyName ) ) {// 驗證該屬性的約束
        Object value = getMemberValue( bean, getter );
        Validator validator = memberValidators.get( i );
        if ( !validator.isValid( value ) ) {
          results.add( new InvalidValue( messages.get( validator ), beanClass, propertyName, value, bean ) );
        }
      }
    }

    return results.toArray( new InvalidValue[results.size()] );
  }

  /**
   * Apply constraints of a particular property value of a bean type and return all the failures.
   * The InvalidValue objects returns return null for InvalidValue#getBean() and InvalidValue#getRootBean()
   * Note this is not recursive.
   * 驗證 value 是否滿足當前屬性的約束.
   */
  //TODO should it be recursive?
  public InvalidValue[] getPotentialInvalidValues(String propertyName, Object value) {
    List<InvalidValue> results = new ArrayList<InvalidValue>();

    for ( int i = 0; i < memberValidators.size() ; i++ ) {
      Member getter = memberGetters.get( i );
      if ( getPropertyName( getter ).equals( propertyName ) ) {
        Validator validator = memberValidators.get( i );
        if ( !validator.isValid( value ) ) {
          results.add( new InvalidValue( messages.get( validator ), beanClass, propertyName, value, null ) );
        }
      }
    }

    return results.toArray( new InvalidValue[results.size()] );
  }

  private Object getMemberValue(T bean, Member getter) {
    Object value;
    try {
      value = getValue( getter, bean );
    }
    catch (Exception e) {
      throw new IllegalStateException( "Could not get property value", e );
    }
    return value;
  }

  private Object getValue(Member member, T bean) throws IllegalAccessException, InvocationTargetException {
    if ( member instanceof Field ) {
      return ( (Field) member ).get( bean );
    }
    else if ( member instanceof Method ) {
      return ( (Method) member ).invoke( bean );
    }
    else {
      throw new AssertionFailure( "Unexpected member: " + member.getClass().getName() );
    }
  }

  public String getPropertyName(Member member) {
    //Do no try to cache the result in a map, it's actually much slower (2.x time)
    String propertyName;
    if ( member instanceof Field ) {
      propertyName = member.getName();
    }
    else if ( member instanceof Method ) {
      propertyName = member.getName();
      if ( propertyName.startsWith( "is" ) ) {
        propertyName = Introspector.decapitalize( propertyName.substring( 2 ) );
      }
      else if ( propertyName.startsWith( "get" ) ) {
        propertyName = Introspector.decapitalize( propertyName.substring( 3 ) );
      }
      //do nothing for non getter method, in case someone want to validate a PO Method
    }
    else {
      throw new AssertionFailure( "Unexpected member: " + member.getClass().getName() );
    }
    return propertyName;
  }

  private String replace(String message, Annotation parameters) {
    StringTokenizer tokens = new StringTokenizer( message, "{}", true );
    StringBuilder buf = new StringBuilder( 30 );
    boolean escaped = false;
    while ( tokens.hasMoreTokens() ) {
      String token = tokens.nextToken();
      if ( "{".equals( token ) ) {
        escaped = true;
      }
      else if ( "}".equals( token ) ) {
        escaped = false;
      }
      else if ( !escaped ) {
        buf.append( token );
      }
      else {
        Method member;
        try {
          member = parameters.getClass().getMethod( token, (Class[]) null );
        }
        catch (NoSuchMethodException nsfme) {
          member = null;
        }
        if ( member != null ) {
          try {
            buf.append( member.invoke( parameters ) );
          }
          catch (Exception e) {
            throw new IllegalArgumentException( "could not render message", e );
          }
        }
        else if ( messageBundle != null ) {
          String string = messageBundle.getString( token );
          if ( string != null ) buf.append( replace( string, parameters ) );
        }
      }
    }
    return buf.toString();
  }

  /**
   * apply the registred constraints rules on the hibernate metadata (to be applied on DB schema...)
   *該方法是與實體類綁定的 不推薦使用 有興趣的讀者可以自己研究一下
   * @param persistentClass hibernate metadata
   */
  public void apply(PersistentClass persistentClass) {  
   //源代碼省略
  }

  /**
   * 斷言該bean 是否符合所有約束. 負責拋出異常
   * @param bean
   */
  public void assertValid(T bean) {
    InvalidValue[] values = getInvalidValues( bean );
    if ( values.length > 0 ) {
      throw new InvalidStateException( values );
    }
  }

  /**
   * 該方法應該是序列化ResourceBundle的 為private方法 但并沒有用到, 不知道為什么 可能以后會有用
   * @param oos
   * @throws IOException
   */
  private void writeObject(ObjectOutputStream oos) throws IOException {
    ResourceBundle rb = messageBundle;
    if ( rb != null && ! ( rb instanceof Serializable ) ) {
      messageBundle = null;
      if ( ! defaultResourceBundle )
        log.warn( "Serializing a ClassValidator with a not serializable ResourceBundle: ResourceBundle ignored" );
    }
    oos.defaultWriteObject();
    oos.writeObject( messageBundle );
    messageBundle = rb;
  }

  /**
   * 該方法應該是讀取序列化的ResourceBundle的 為private方法 但并沒有用到,不知道為什么 可能以后會有用
   * @param ois
   * @throws IOException
   * @throws ClassNotFoundException
   */
  private void readObject(ObjectInputStream ois) throws IOException, ClassNotFoundException {
    ois.defaultReadObject();
    ResourceBundle rb = (ResourceBundle) ois.readObject();
    if (rb == null) rb = getDefaultResourceBundle();
    initValidator( beanClass, new HashMap<Class, ClassValidator>(), rb );
  }
} 

 ClassValidator<Person> classValidator = new ClassValidator<Person> (Person.class);
 InvalidValue[] validMessages = classValidator.getInvalidValues(p);