Improve javadoc for bean validation (#8093).

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