From 315398b7e8094c8bc9c310b5dd4f350647651954 Mon Sep 17 00:00:00 2001
From: Henri Sara <hesara@vaadin.com>
Date: Wed, 21 Dec 2011 10:37:21 +0200
Subject: [PATCH] Improve javadoc for bean validation (#8093).

---
 .../validator/BeanValidationValidator.java    | 56 ++++++++++++++++---
 1 file changed, 49 insertions(+), 7 deletions(-)

diff --git a/src/com/vaadin/data/validator/BeanValidationValidator.java b/src/com/vaadin/data/validator/BeanValidationValidator.java
index 37ad67886c..c23655e5c5 100644
--- a/src/com/vaadin/data/validator/BeanValidationValidator.java
+++ b/src/com/vaadin/data/validator/BeanValidationValidator.java
@@ -32,9 +32,9 @@ import com.vaadin.ui.Field;
  * The annotations of the fields of the beans are used to determine the
  * validation to perform.
  * 
- * Note that a JSR-303 implementation (e.g. Hibernate Validator or agimatec
- * validation) must be present on the project classpath when using bean
- * validation.
+ * Note that a JSR-303 implementation (e.g. Hibernate Validator or Apache Bean
+ * Validation - formerly agimatec validation) must be present on the project
+ * classpath when using bean validation.
  * 
  * @since 7.0
  * 
@@ -61,6 +61,15 @@ public class BeanValidationValidator implements Validator {
         private final Object value;
         private final ConstraintDescriptor<?> descriptor;
 
+        /**
+         * Create a simple immutable message interpolator context.
+         * 
+         * @param value
+         *            value being validated
+         * @param descriptor
+         *            ConstraintDescriptor corresponding to the constraint being
+         *            validated
+         */
         public SimpleContext(Object value, ConstraintDescriptor<?> descriptor) {
             this.value = value;
             this.descriptor = descriptor;
@@ -100,17 +109,18 @@ public class BeanValidationValidator implements Validator {
      * 
      * @param field
      *            the {@link Field} component to which to add a validator
-     * @param propertyId
+     * @param objectPropertyId
      *            the property ID of the field of the bean that this field
      *            displays
      * @param beanClass
      *            the class of the bean with the bean validation annotations
      * @return the created validator
      */
-    public static BeanValidationValidator addValidator(Field field,
+    public static BeanValidationValidator addValidator(Field<?> field,
             Object objectPropertyId, Class<?> beanClass) {
         if (objectPropertyId == null || !(objectPropertyId instanceof String)) {
-            throw new IllegalArgumentException("Property id must be a non-null String");
+            throw new IllegalArgumentException(
+                    "Property id must be a non-null String");
         }
 
         String propertyId = (String) objectPropertyId;
@@ -134,6 +144,13 @@ public class BeanValidationValidator implements Validator {
         return validator;
     }
 
+    /**
+     * Check the validity of a value. Normally, {@link #validate(Object)} should
+     * be used instead of this method to also get the validation error message.
+     * 
+     * @param value
+     * @return true if the value is valid
+     */
     public boolean isValid(Object value) {
         try {
             validate(value);
@@ -167,6 +184,12 @@ public class BeanValidationValidator implements Validator {
         return false;
     }
 
+    /**
+     * Returns the message to show if a value is required but missing. The
+     * message that of the {@link NotNull} annotation.
+     * 
+     * @return error message to show for missing required value
+     */
     @SuppressWarnings("unchecked")
     public String getRequiredMessage() {
         return getErrorMessage(null, NotNull.class);
@@ -265,12 +288,18 @@ public class BeanValidationValidator implements Validator {
     /**
      * Gets the locale used for validation error messages.
      * 
-     * @return
+     * @return locale used for validation
      */
     public Locale getLocale() {
         return locale;
     }
 
+    /**
+     * Returns the underlying JSR-303 bean validator factory used. A factory is
+     * created using {@link Validation} if necessary.
+     * 
+     * @return {@link ValidatorFactory} to use
+     */
     protected static ValidatorFactory getJavaxBeanValidatorFactory() {
         if (factory == null) {
             factory = Validation.buildDefaultValidatorFactory();
@@ -279,6 +308,13 @@ public class BeanValidationValidator implements Validator {
         return factory;
     }
 
+    /**
+     * Returns a shared Validator instance to use. An instance is created using
+     * the validator factory if necessary and thereafter reused by the
+     * {@link BeanValidationValidator} instance.
+     * 
+     * @return the JSR-303 {@link javax.validation.Validator} to use
+     */
     protected javax.validation.Validator getJavaxBeanValidator() {
         if (javaxBeanValidator == null) {
             javaxBeanValidator = getJavaxBeanValidatorFactory().getValidator();
@@ -287,6 +323,12 @@ public class BeanValidationValidator implements Validator {
         return javaxBeanValidator;
     }
 
+    /**
+     * Checks whether a bean validation implementation (e.g. Hibernate Validator
+     * or Apache Bean Validation) is available.
+     * 
+     * @return true if a JSR-303 bean validation implementation is available
+     */
     public static boolean isImplementationAvailable() {
         if (implementationAvailable == null) {
             try {
-- 
2.39.5