[hibernate-commits] Hibernate SVN: r17583 - beanvalidation/api/trunk/src/main/java/javax/validation.
hibernate-commits at lists.jboss.org
hibernate-commits at lists.jboss.org
Wed Sep 30 11:18:46 EDT 2009
Author: epbernard
Date: 2009-09-30 11:18:46 -0400 (Wed, 30 Sep 2009)
New Revision: 17583
Modified:
beanvalidation/api/trunk/src/main/java/javax/validation/ConstraintViolation.java
beanvalidation/api/trunk/src/main/java/javax/validation/GroupSequence.java
beanvalidation/api/trunk/src/main/java/javax/validation/MessageInterpolator.java
beanvalidation/api/trunk/src/main/java/javax/validation/Path.java
beanvalidation/api/trunk/src/main/java/javax/validation/TraversableResolver.java
beanvalidation/api/trunk/src/main/java/javax/validation/Validator.java
Log:
Enhance JavaDoc
Modified: beanvalidation/api/trunk/src/main/java/javax/validation/ConstraintViolation.java
===================================================================
--- beanvalidation/api/trunk/src/main/java/javax/validation/ConstraintViolation.java 2009-09-30 13:09:40 UTC (rev 17582)
+++ beanvalidation/api/trunk/src/main/java/javax/validation/ConstraintViolation.java 2009-09-30 15:18:46 UTC (rev 17583)
@@ -20,8 +20,8 @@
import javax.validation.metadata.ConstraintDescriptor;
/**
- * Describe a constraint violation. This object describe the error context as
- * well as the message describing the violation.
+ * Describe a constraint violation. This object exposes the constraint
+ * violation context as well as the message describing the violation.
*
* @author Emmanuel Bernard
*/
Modified: beanvalidation/api/trunk/src/main/java/javax/validation/GroupSequence.java
===================================================================
--- beanvalidation/api/trunk/src/main/java/javax/validation/GroupSequence.java 2009-09-30 13:09:40 UTC (rev 17582)
+++ beanvalidation/api/trunk/src/main/java/javax/validation/GroupSequence.java 2009-09-30 15:18:46 UTC (rev 17583)
@@ -24,7 +24,8 @@
/**
* Define a group sequence
- * The interface hosting @GroupSequence is representing the group sequence.
+ * The interface hosting <code>@GroupSequence</code> is representing
+ * the group sequence.
* When hosted on a class, represents the <code>Default</code> group
* for that class.
*
Modified: beanvalidation/api/trunk/src/main/java/javax/validation/MessageInterpolator.java
===================================================================
--- beanvalidation/api/trunk/src/main/java/javax/validation/MessageInterpolator.java 2009-09-30 13:09:40 UTC (rev 17582)
+++ beanvalidation/api/trunk/src/main/java/javax/validation/MessageInterpolator.java 2009-09-30 15:18:46 UTC (rev 17583)
@@ -21,7 +21,7 @@
import javax.validation.metadata.ConstraintDescriptor;
/**
- * Interpolate a given constraint error message.
+ * Interpolate a given constraint violation message.
* Implementations should be as tolerant as possible on syntax errors.
*
* @author Emmanuel Bernard
@@ -29,8 +29,7 @@
*/
public interface MessageInterpolator {
/**
- * Interpolate the message from the constraint parameters and the actual validated
- * object.
+ * Interpolate the message template based on the contraint validation context.
* The locale is defaulted according to the <code>MessageInterpolator</code>
* implementation. See the implementation documentation for more detail.
*
@@ -42,9 +41,8 @@
String interpolate(String messageTemplate, Context context);
/**
- * Interpolate the message from the constraint parameters and the actual validated
- * object.
- * The Locale used is provided as a parameter.
+ * Interpolate the message template based on the contraint validation context.
+ * The <code>Locale</code> used is provided as a parameter.
*
* @param messageTemplate The message to interpolate.
* @param context contextual information related to the interpolation
Modified: beanvalidation/api/trunk/src/main/java/javax/validation/Path.java
===================================================================
--- beanvalidation/api/trunk/src/main/java/javax/validation/Path.java 2009-09-30 13:09:40 UTC (rev 17582)
+++ beanvalidation/api/trunk/src/main/java/javax/validation/Path.java 2009-09-30 15:18:46 UTC (rev 17583)
@@ -18,11 +18,12 @@
package javax.validation;
/**
- * Represent a navigation path from an object to another.
- * Each path element is represented by a Node.
+ * Represent the navigation path from an object to another
+ * in an object graph.
+ * Each path element is represented by a <code>Node</code>.
*
* The path corresponds to the succession of nodes
- * in the order they are returned by the Iterator
+ * in the order they are returned by the <code>Iterator</code>
*
* @author Emmanuel Bernard
*/
@@ -33,15 +34,17 @@
*/
interface Node {
/**
- * @return Property name the node represents
- * or null if the leaf node and representing an entity
- * (in particular the node representing the root object
- * has its name null)
+ * Property name the node represents
+ * or null if representing an entity on the leaf node
+ * (in particular the node in a <code>Path</code> representing
+ * the root object has its name null).
+ *
+ * @return property name the node represents
*/
String getName();
/**
- * @return True if the node represents an object contained in an Iterable
+ * @return true if the node represents an object contained in an Iterable
* or in a Map.
*/
boolean isInIterable();
Modified: beanvalidation/api/trunk/src/main/java/javax/validation/TraversableResolver.java
===================================================================
--- beanvalidation/api/trunk/src/main/java/javax/validation/TraversableResolver.java 2009-09-30 13:09:40 UTC (rev 17582)
+++ beanvalidation/api/trunk/src/main/java/javax/validation/TraversableResolver.java 2009-09-30 15:18:46 UTC (rev 17583)
@@ -18,10 +18,9 @@
package javax.validation;
import java.lang.annotation.ElementType;
-import javax.validation.Path;
/**
- * Contract determining if a property can be accessed by the Bean Validation provider
+ * Contract determining if a property can be accessed by the Bean Validation provider.
* This contract is called for each property that is being either validated or cascaded.
*
* A traversable resolver implementation must be thread-safe.
@@ -33,7 +32,7 @@
* Determine if the Bean Validation provider is allowed to reach the property state
*
* @param traversableObject object hosting <code>traversableProperty</code> or null
- * if validateValue is called
+ * if <code>validateValue</code> is called
* @param traversableProperty the traversable property.
* @param rootBeanType type of the root object passed to the Validator.
* @param pathToTraversableObject path from the root object to
@@ -45,20 +44,20 @@
* reach the property state, <code>false</code> otherwise.
*/
boolean isReachable(Object traversableObject,
- Path.Node traversableProperty,
- Class<?> rootBeanType,
- Path pathToTraversableObject,
- ElementType elementType);
+ Path.Node traversableProperty,
+ Class<?> rootBeanType,
+ Path pathToTraversableObject,
+ ElementType elementType);
/**
* Determine if the Bean Validation provider is allowed to cascade validation on
* the bean instance returned by the property value
* marked as <code>@Valid</code>.
- * Note that this method is called only if isReachable returns true for the same set of
- * arguments and if the property is marked as <code>@Valid</code>
+ * Note that this method is called only if <code>isReachable</code> returns true
+ * for the same set of arguments and if the property is marked as <code>@Valid</code>
*
* @param traversableObject object hosting <code>traversableProperty</code> or null
- * if validateValue is called
+ * if <code>validateValue</code> is called
* @param traversableProperty the traversable property.
* @param rootBeanType type of the root object passed to the Validator.
* @param pathToTraversableObject path from the root object to
@@ -70,8 +69,8 @@
* cascade validation, <code>false</code> otherwise.
*/
boolean isCascadable(Object traversableObject,
- Path.Node traversableProperty,
- Class<?> rootBeanType,
- Path pathToTraversableObject,
- ElementType elementType);
+ Path.Node traversableProperty,
+ Class<?> rootBeanType,
+ Path pathToTraversableObject,
+ ElementType elementType);
}
Modified: beanvalidation/api/trunk/src/main/java/javax/validation/Validator.java
===================================================================
--- beanvalidation/api/trunk/src/main/java/javax/validation/Validator.java 2009-09-30 13:09:40 UTC (rev 17582)
+++ beanvalidation/api/trunk/src/main/java/javax/validation/Validator.java 2009-09-30 15:18:46 UTC (rev 17583)
@@ -28,11 +28,11 @@
*/
public interface Validator {
/**
- * Validates all constraints on object.
+ * Validates all constraints on <code>object</code>.
*
* @param object object to validate
- * @param groups groups targeted for validation
- * (default to {@link javax.validation.groups.Default})
+ * @param groups group or list of groups targeted for validation
+ * (default to {@link javax.validation.groups.Default})
*
* @return constraint violations or an empty Set if none
*
@@ -44,19 +44,19 @@
<T> Set<ConstraintViolation<T>> validate(T object, Class<?>... groups);
/**
- * Validates all constraints placed on the property named <code>propertyName</code>
- * of <code>object</code>
+ * Validates all constraints placed on the property of <code>object</code>
+ * named <code>propertyName</code>.
*
* @param object object to validate
* @param propertyName property to validate (ie field and getter constraints)
- * @param groups groups targeted for validation
- * (default to {@link javax.validation.groups.Default})
+ * @param groups group or list of groups targeted for validation
+ * (default to {@link javax.validation.groups.Default})
*
* @return constraint violations or an empty Set if none
*
- * @throws IllegalArgumentException if object is null, if propertyName null, empty
- * or not a valid object property
- * or if null is passed to the varargs groups
+ * @throws IllegalArgumentException if <code>object</code> is null,
+ * if <code>propertyName</code> null, empty or not a valid object property
+ * or if null is passed to the varargs groups
* @throws ValidationException if a non recoverable error happens
* during the validation process
*/
@@ -66,7 +66,7 @@
/**
* Validates all constraints placed on the property named <code>propertyName</code>
- * would the property value be <code>value</code>
+ * of the class <code>beanType</code> would the property value be <code>value</code>
* <p/>
* <code>ConstraintViolation</code> objects return null for
* {@link ConstraintViolation#getRootBean()} and {@link ConstraintViolation#getLeafBean()}
@@ -74,14 +74,14 @@
* @param beanType the bean type
* @param propertyName property to validate
* @param value property value to validate
- * @param groups groups targeted for validation
- * (default to {@link javax.validation.groups.Default})
+ * @param groups group or list of groups targeted for validation
+ * (default to {@link javax.validation.groups.Default})
*
* @return constraint violations or an empty Set if none
*
- * @throws IllegalArgumentException if beanType is null, if propertyName null, empty
- * or not a valid object property
- * or if null is passed to the varargs groups
+ * @throws IllegalArgumentException if <code>beanType</code> is null,
+ * if <code>propertyName</code> null, empty or not a valid object property
+ * or if null is passed to the varargs groups
* @throws ValidationException if a non recoverable error happens
* during the validation process
*/
@@ -91,9 +91,9 @@
Class<?>... groups);
/**
- * Return the descriptor object describing bean constraints
- * The returned object (and associated objects including ConstraintDescriptors)
- * are immutable.
+ * Return the descriptor object describing bean constraints.
+ * The returned object (and associated objects including
+ * <code>ConstraintDescriptor<code>s) are immutable.
*
* @param clazz class type evaluated
*
@@ -107,17 +107,16 @@
BeanDescriptor getConstraintsForClass(Class<?> clazz);
/**
- * Return an object of the specified type to allow access to the
- * provider-specific API. If the Bean Validation provider
- * implementation does not support the specified class, the
- * ValidationException is thrown.
+ * Return an instance of the specified type allowing access to
+ * provider-specific APIs. If the Bean Validation provider
+ * implementation does not support the specified class,
+ * <code>ValidationException</code> is thrown.
*
* @param type the class of the object to be returned.
*
* @return an instance of the specified class
*
- * @throws ValidationException if the provider does not
- * support the call.
+ * @throws ValidationException if the provider does not support the call.
*/
public <T> T unwrap(Class<T> type);
}
More information about the hibernate-commits
mailing list