HV-520: Adding some JavaDoc.

hibernate · Dec 8, 2011 · d14dcbc · d14dcbc
1 parent c113814
commit d14dcbc
Show file tree

Hide file tree

Showing 18 changed files with 160 additions and 37 deletions.
diff --git a/...lidator/src/main/java/org/hibernate/validator/metadata/descriptor/BeanDescriptorImpl.java b/...lidator/src/main/java/org/hibernate/validator/metadata/descriptor/BeanDescriptorImpl.java
@@ -35,6 +35,8 @@
 import static org.hibernate.validator.util.Contracts.assertNotNull;
 
 /**
+ * Describes a validated bean.
+ *
  * @author Emmanuel Bernard
  * @author Hardy Ferentschik
  * @author Gunnar Morling

diff --git a/...r/src/main/java/org/hibernate/validator/metadata/descriptor/ConstraintDescriptorImpl.java b/...r/src/main/java/org/hibernate/validator/metadata/descriptor/ConstraintDescriptorImpl.java
@@ -56,7 +56,7 @@
 import static org.hibernate.validator.constraints.CompositionType.AND;
 
 /**
- * Describe a single constraint (including it's composing constraints).
+ * Describes a single constraint (including it's composing constraints).
  *
  * @author Emmanuel Bernard
  * @author Hardy Ferentschik

diff --git a/...dator/src/main/java/org/hibernate/validator/metadata/descriptor/MethodDescriptorImpl.java b/...dator/src/main/java/org/hibernate/validator/metadata/descriptor/MethodDescriptorImpl.java
@@ -24,6 +24,8 @@
 import org.hibernate.validator.method.metadata.ParameterDescriptor;
 
 /**
+ * Describes a validated method.
+ *
  * @author Gunnar Morling
  */
 public class MethodDescriptorImpl extends ElementDescriptorImpl implements MethodDescriptor {

diff --git a/...or/src/main/java/org/hibernate/validator/metadata/descriptor/ParameterDescriptorImpl.java b/...or/src/main/java/org/hibernate/validator/metadata/descriptor/ParameterDescriptorImpl.java
@@ -22,6 +22,8 @@
 import org.hibernate.validator.method.metadata.ParameterDescriptor;
 
 /**
+ * Describes a validated method parameter.
+ *
  * @author Gunnar Morling
  */
 public class ParameterDescriptorImpl extends ElementDescriptorImpl implements ParameterDescriptor {

diff --git a/...tor/src/main/java/org/hibernate/validator/metadata/descriptor/PropertyDescriptorImpl.java b/...tor/src/main/java/org/hibernate/validator/metadata/descriptor/PropertyDescriptorImpl.java
@@ -21,7 +21,7 @@
 import javax.validation.metadata.PropertyDescriptor;
 
 /**
- * Describes a validated element (class, field or property).
+ * Describes a validated property.
  *
  * @author Emmanuel Bernard
  * @author Hardy Ferentschik

diff --git a/hibernate-validator/src/main/java/org/hibernate/validator/metadata/descriptor/package.html b/hibernate-validator/src/main/java/org/hibernate/validator/metadata/descriptor/package.html
@@ -0,0 +1,30 @@
+<!--
+  ~
+  ~ JBoss, Home of Professional Open Source
+  ~ Copyright 2011, Red Hat, Inc. and/or its affiliates, and individual contributors
+  ~ by the @authors tag. See the copyright.txt in the distribution for a
+  ~ full listing of individual contributors.
+  ~
+  ~ Licensed under the Apache License, Version 2.0 (the "License");
+  ~ you may not use this file except in compliance with the License.
+  ~ You may obtain a copy of the License at
+  ~ http://www.apache.org/licenses/LICENSE-2.0
+  ~ Unless required by applicable law or agreed to in writing, software
+  ~ distributed under the License is distributed on an "AS IS" BASIS,
+  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  ~ See the License for the specific language governing permissions and
+  ~ limitations under the License.
+-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<head/>
+<body>
+<p>Implementation of the Bean Validation meta data API and its Hibernate Validator specific extension for the
+    representation of method level constraints.
+</p>
+
+<p>The types in this package are generally immutable. Also any collections returned from methods in this package are
+    unmodifiable and an exception will be thrown when trying to alter them.
+</p>
+</body>
+</html>
diff --git a/...r/src/main/java/org/hibernate/validator/metadata/provider/AnnotationMetaDataProvider.java b/...r/src/main/java/org/hibernate/validator/metadata/provider/AnnotationMetaDataProvider.java
@@ -31,22 +31,22 @@
 import javax.validation.GroupSequence;
 import javax.validation.Valid;
 
-import org.hibernate.validator.metadata.core.MetaConstraint;
 import org.hibernate.validator.group.DefaultGroupSequenceProvider;
 import org.hibernate.validator.group.GroupSequenceProvider;
 import org.hibernate.validator.metadata.core.AnnotationIgnores;
+import org.hibernate.validator.metadata.core.ConstraintHelper;
 import org.hibernate.validator.metadata.core.ConstraintOrigin;
+import org.hibernate.validator.metadata.core.MetaConstraint;
 import org.hibernate.validator.metadata.descriptor.ConstraintDescriptorImpl;
-import org.hibernate.validator.metadata.core.ConstraintHelper;
+import org.hibernate.validator.metadata.location.BeanConstraintLocation;
+import org.hibernate.validator.metadata.location.MethodConstraintLocation;
 import org.hibernate.validator.metadata.raw.BeanConfiguration;
 import org.hibernate.validator.metadata.raw.ConfigurationSource;
 import org.hibernate.validator.metadata.raw.ConstrainedElement;
 import org.hibernate.validator.metadata.raw.ConstrainedField;
 import org.hibernate.validator.metadata.raw.ConstrainedMethod;
 import org.hibernate.validator.metadata.raw.ConstrainedParameter;
 import org.hibernate.validator.metadata.raw.ConstrainedType;
-import org.hibernate.validator.metadata.location.BeanConstraintLocation;
-import org.hibernate.validator.metadata.location.MethodConstraintLocation;
 import org.hibernate.validator.util.ReflectionHelper;
 
 import static org.hibernate.validator.util.CollectionHelper.newArrayList;
@@ -101,8 +101,8 @@ private BeanConfiguration<?> retrieveBeanConfiguration(Class<?> beanClass) {
 			ConstrainedType classLevelMetaData =
 					new ConstrainedType(
 							ConfigurationSource.ANNOTATION,
-							classLevelConstraints,
-							new BeanConstraintLocation( beanClass )
+							new BeanConstraintLocation( beanClass ),
+							classLevelConstraints
 					);
 			propertyMetaData.add( classLevelMetaData );
 		}

diff --git a/...e-validator/src/main/java/org/hibernate/validator/metadata/provider/MetaDataProvider.java b/...e-validator/src/main/java/org/hibernate/validator/metadata/provider/MetaDataProvider.java
@@ -36,9 +36,32 @@
  * @author Gunnar Morling
  */
 public interface MetaDataProvider {
+
+	/**
+	 * Returns a set with all bean configurations by this provider.
+	 *
+	 * @return a set with all bean configurations by this provider. May be
+	 *         empty, but never <code>null</code>.
+	 */
 	Set<BeanConfiguration<?>> getAllBeanConfigurations();
 
+	/**
+	 * Returns the annotation processing options as configured by this provider.
+	 *
+	 * @return The annotation processing options as configured by this provider.
+	 */
 	AnnotationIgnores getAnnotationIgnores();
 
+	/**
+	 * Returns a set with the configurations for all types contained in the
+	 * given type's hierarchy (including implemented interfaces) as configured
+	 * by this provider.
+	 *
+	 * @param beanClass The type of interest.
+	 *
+	 * @return A set with the configurations for the complete hierarchy of the
+	 *         given type. May be empty, but never <code>null</code>.
+	 */
 	Set<BeanConfiguration<?>> getBeanConfigurationForHierarchy(Class<?> beanClass);
+
 }
diff --git a/...tor/src/main/java/org/hibernate/validator/metadata/provider/MetaDataProviderImplBase.java b/...tor/src/main/java/org/hibernate/validator/metadata/provider/MetaDataProviderImplBase.java
@@ -24,17 +24,19 @@
 import org.hibernate.validator.cfg.context.impl.ConfiguredConstraint;
 import org.hibernate.validator.group.DefaultGroupSequenceProvider;
 import org.hibernate.validator.metadata.core.ConstraintHelper;
+import org.hibernate.validator.metadata.location.BeanConstraintLocation;
 import org.hibernate.validator.metadata.raw.BeanConfiguration;
 import org.hibernate.validator.metadata.raw.ConfigurationSource;
 import org.hibernate.validator.metadata.raw.ConstrainedElement;
-import org.hibernate.validator.metadata.location.BeanConstraintLocation;
 import org.hibernate.validator.util.CollectionHelper.Partitioner;
 import org.hibernate.validator.util.ReflectionHelper;
 
 import static org.hibernate.validator.util.CollectionHelper.newHashMap;
 import static org.hibernate.validator.util.CollectionHelper.newHashSet;
 
 /**
+ * Base implementation for all {@link MetaDataProvider}s.
+ *
  * @author Gunnar Morling
  */
 public abstract class MetaDataProviderImplBase implements MetaDataProvider {

diff --git a/...n/java/org/hibernate/validator/metadata/provider/ProgrammaticMappingMetaDataProvider.java b/...n/java/org/hibernate/validator/metadata/provider/ProgrammaticMappingMetaDataProvider.java
@@ -28,20 +28,20 @@
 import org.hibernate.validator.cfg.ConstraintMapping;
 import org.hibernate.validator.cfg.context.impl.ConfiguredConstraint;
 import org.hibernate.validator.cfg.context.impl.ConstraintMappingContext;
-import org.hibernate.validator.metadata.core.MetaConstraint;
 import org.hibernate.validator.metadata.core.AnnotationIgnores;
+import org.hibernate.validator.metadata.core.ConstraintHelper;
 import org.hibernate.validator.metadata.core.ConstraintOrigin;
+import org.hibernate.validator.metadata.core.MetaConstraint;
 import org.hibernate.validator.metadata.descriptor.ConstraintDescriptorImpl;
-import org.hibernate.validator.metadata.core.ConstraintHelper;
+import org.hibernate.validator.metadata.location.BeanConstraintLocation;
+import org.hibernate.validator.metadata.location.ConstraintLocation;
+import org.hibernate.validator.metadata.location.MethodConstraintLocation;
 import org.hibernate.validator.metadata.raw.ConfigurationSource;
 import org.hibernate.validator.metadata.raw.ConstrainedElement;
 import org.hibernate.validator.metadata.raw.ConstrainedField;
 import org.hibernate.validator.metadata.raw.ConstrainedMethod;
 import org.hibernate.validator.metadata.raw.ConstrainedParameter;
 import org.hibernate.validator.metadata.raw.ConstrainedType;
-import org.hibernate.validator.metadata.location.BeanConstraintLocation;
-import org.hibernate.validator.metadata.location.ConstraintLocation;
-import org.hibernate.validator.metadata.location.MethodConstraintLocation;
 import org.hibernate.validator.util.CollectionHelper.Partitioner;
 
 import static org.hibernate.validator.util.CollectionHelper.newArrayList;
@@ -136,8 +136,8 @@ private Set<ConstrainedElement> retrievePropertyMetaData(
 				allPropertyMetaData.add(
 						new ConstrainedType(
 								ConfigurationSource.API,
-								asMetaConstraints( constraintsByLocation.get( oneConfiguredProperty ) ),
-								oneConfiguredProperty
+								oneConfiguredProperty,
+								asMetaConstraints( constraintsByLocation.get( oneConfiguredProperty ) )
 						)
 				);
 			}

diff --git a/...main/java/org/hibernate/validator/metadata/provider/XmlConfigurationMetaDataProvider.java b/...main/java/org/hibernate/validator/metadata/provider/XmlConfigurationMetaDataProvider.java
@@ -27,14 +27,14 @@
 import org.hibernate.validator.metadata.core.AnnotationIgnores;
 import org.hibernate.validator.metadata.core.ConstraintHelper;
 import org.hibernate.validator.metadata.core.MetaConstraint;
+import org.hibernate.validator.metadata.location.BeanConstraintLocation;
+import org.hibernate.validator.metadata.location.ConstraintLocation;
+import org.hibernate.validator.metadata.location.MethodConstraintLocation;
 import org.hibernate.validator.metadata.raw.ConfigurationSource;
 import org.hibernate.validator.metadata.raw.ConstrainedElement;
 import org.hibernate.validator.metadata.raw.ConstrainedField;
 import org.hibernate.validator.metadata.raw.ConstrainedMethod;
 import org.hibernate.validator.metadata.raw.ConstrainedType;
-import org.hibernate.validator.metadata.location.BeanConstraintLocation;
-import org.hibernate.validator.metadata.location.ConstraintLocation;
-import org.hibernate.validator.metadata.location.MethodConstraintLocation;
 import org.hibernate.validator.util.CollectionHelper.Partitioner;
 import org.hibernate.validator.xml.XmlMappingParser;
 
@@ -117,8 +117,8 @@ else if ( oneConfiguredLocation.getElementType() == ElementType.TYPE ) {
 				propertyMetaData.add(
 						new ConstrainedType(
 								ConfigurationSource.XML,
-								constraintsByLocation.get( oneConfiguredLocation ),
-								(BeanConstraintLocation) oneConfiguredLocation
+								(BeanConstraintLocation) oneConfiguredLocation,
+								constraintsByLocation.get( oneConfiguredLocation )
 						)
 				);
 			}

diff --git a/...idator/src/main/java/org/hibernate/validator/metadata/raw/AbstractConstrainedElement.java b/...idator/src/main/java/org/hibernate/validator/metadata/raw/AbstractConstrainedElement.java
@@ -24,6 +24,8 @@
 import org.hibernate.validator.metadata.location.ConstraintLocation;
 
 /**
+ * Base implementation with functionality common to all {@link ConstrainedElement} implementations.
+ *
  * @author Gunnar Morling
  */
 public abstract class AbstractConstrainedElement implements ConstrainedElement {

diff --git a/...rnate-validator/src/main/java/org/hibernate/validator/metadata/raw/BeanConfiguration.java b/...rnate-validator/src/main/java/org/hibernate/validator/metadata/raw/BeanConfiguration.java
@@ -24,8 +24,10 @@
 import static org.hibernate.validator.util.CollectionHelper.newHashSet;
 
 /**
- * Represents the constraint related configuration of one Java type originating
- * from one {@link ConfigurationSource}.
+ * Represents the complete constraint related configuration of one Java type
+ * originating from one {@link ConfigurationSource}. Contains meta-data on
+ * constraints (field, method and class level) as well as meta data on default
+ * group sequences.
  *
  * @author Gunnar Morling
  */
@@ -42,11 +44,16 @@ public class BeanConfiguration<T> {
 	private final Class<? extends DefaultGroupSequenceProvider<?>> defaultGroupSequenceProvider;
 
 	/**
-	 * @param source
-	 * @param beanClass
-	 * @param constrainedElements
-	 * @param defaultGroupSequence
-	 * @param defaultGroupSequenceProvider
+	 * Creates a new bean configuration.
+	 *
+	 * @param source The source of this configuration.
+	 * @param beanClass The type represented by this configuration.
+	 * @param constrainedElements The constraint elements representing this type's fields,
+	 * methods etc.
+	 * @param defaultGroupSequence The default group sequence for the given type as configured by
+	 * the given configuration source.
+	 * @param defaultGroupSequenceProvider The default group sequence provider for the given type as
+	 * configured by the given configuration source.
 	 */
 	public BeanConfiguration(
 			ConfigurationSource source,

diff --git a/...nate-validator/src/main/java/org/hibernate/validator/metadata/raw/ConstrainedElement.java b/...nate-validator/src/main/java/org/hibernate/validator/metadata/raw/ConstrainedElement.java
@@ -59,10 +59,27 @@ public enum ConstrainedElementKind {
 		TYPE, FIELD, METHOD, PARAMETER;
 	}
 
+	/**
+	 * Returns the kind of this constrained element.
+	 *
+	 * @return The kind of this constrained element.
+	 */
 	ConstrainedElementKind getConstrainedElementKind();
 
+	/**
+	 * Returns the location of this constrained element.
+	 *
+	 * @return The location of this constrained element.
+	 */
 	ConstraintLocation getLocation();
 
+	/**
+	 * Returns a set containing the constraints specified for this constrained
+	 * element.
+	 *
+	 * @return A set with this constrained element's constraints. May be empty,
+	 *         but never <code>null</code>.
+	 */
 	Set<MetaConstraint<?>> getConstraints();
 
 	/**

diff --git a/hibernate-validator/src/main/java/org/hibernate/validator/metadata/raw/ConstrainedField.java b/hibernate-validator/src/main/java/org/hibernate/validator/metadata/raw/ConstrainedField.java
@@ -24,14 +24,21 @@
 import org.hibernate.validator.util.ReflectionHelper;
 
 /**
+ * Represents a field of a Java type and all its associated meta-data relevant
+ * in the context of bean validation, for instance its constraints.
+ *
  * @author Gunnar Morling
  */
 public class ConstrainedField extends AbstractConstrainedElement {
 
 	/**
-	 * @param location
-	 * @param constraints
-	 * @param isCascading
+	 * Creates a new field meta data object.
+	 *
+	 * @param source The source of meta data.
+	 * @param location The location of the represented field.
+	 * @param constraints The constraints of the represented field, if any.
+	 * @param isCascading Whether a cascaded validation of the represented field shall
+	 * be performed or not.
 	 */
 	public ConstrainedField(ConfigurationSource source, BeanConstraintLocation location, Set<MetaConstraint<?>> constraints,
 							boolean isCascading) {

diff --git a/...rnate-validator/src/main/java/org/hibernate/validator/metadata/raw/ConstrainedMethod.java b/...rnate-validator/src/main/java/org/hibernate/validator/metadata/raw/ConstrainedMethod.java
@@ -41,6 +41,16 @@ public class ConstrainedMethod extends AbstractConstrainedElement {
 
 	private final boolean hasParameterConstraints;
 
+	/**
+	 * Creates a new method meta data object for a parameter-less method.
+	 *
+	 * @param source The source of meta data.
+	 * @param location The location of the represented method.
+	 * @param returnValueConstraints The return value constraints of the represented method, if
+	 * any.
+	 * @param isCascading Whether a cascaded validation of the represented method's
+	 * return value shall be performed or not.
+	 */
 	public ConstrainedMethod(
 			ConfigurationSource source,
 			MethodConstraintLocation location,
@@ -59,11 +69,12 @@ public ConstrainedMethod(
 	/**
 	 * Creates a new method meta data object.
 	 *
-	 * @param method The method to represent.
+	 * @param source The source of meta data.
+	 * @param location The location of the represented method.
 	 * @param parameterMetaData A list with parameter meta data. The length must correspond
 	 * with the number of parameters of the represented method. So
-	 * this list may be empty returned (in case of a parameterless
-	 * method), but never <code>null</code>.
+	 * this list may be empty (in case of a parameterless method),
+	 * but never <code>null</code>.
 	 * @param returnValueConstraints The return value constraints of the represented method, if
 	 * any.
 	 * @param isCascading Whether a cascaded validation of the represented method's

diff --git a/...te-validator/src/main/java/org/hibernate/validator/metadata/raw/ConstrainedParameter.java b/...te-validator/src/main/java/org/hibernate/validator/metadata/raw/ConstrainedParameter.java
@@ -30,6 +30,17 @@ public class ConstrainedParameter extends AbstractConstrainedElement {
 
 	private final String name;
 
+	/**
+	 * Creates a new parameter meta data object.
+	 *
+	 * @param source The source of meta data.
+	 * @param location The location of the represented method parameter.
+	 * @param name The name of the represented parameter.
+	 * @param constraints The constraints of the represented method parameter, if
+	 * any.
+	 * @param isCascading Whether a cascaded validation of the represented method
+	 * parameter shall be performed or not.
+	 */
 	public ConstrainedParameter(ConfigurationSource source, MethodConstraintLocation location, String name, Set<MetaConstraint<?>> constraints, boolean isCascading) {
 
 		super( source, ConstrainedElementKind.PARAMETER, location, constraints, isCascading );