From 72df6d954affaa8cdf270f1f757d70995d916c5a Mon Sep 17 00:00:00 2001 From: Gunnar Morling Date: Sat, 18 Jun 2011 00:09:36 +0200 Subject: [PATCH 1/7] HV-372: Adding documentation for method validation to reference guide (work in progress) --- .../docbook/en-US/modules/customoptions.xml | 218 +++++++++++++++++- 1 file changed, 217 insertions(+), 1 deletion(-) diff --git a/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml b/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml index a26970d858..35dc4bb6e3 100644 --- a/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml +++ b/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml @@ -43,7 +43,7 @@ In the following table, when a package is public its not - necessarily true for its nested packages. + necessarily true for its nested packages. @@ -201,6 +201,222 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) +
+ Method validation + + The Bean Validation API allows to specify constraints for fields, + properties and types. Hibernate Validator goes one step further and allows + to place contraint annotations also on method parameters and method return + values, thus enabling a programming style known as "Programming by + Contract". + + More specifically this means that any Bean Validation constraints + can be used to specify + + + + any preconditions that must be met before a method invocation + (by annotating method parameters with constraints) + + + + and any postconditions that are guaranteed after a method + invocation (by annotating methods) + + + + + Method validation was also considered to be included in the Bean + Validation API as defined by JSR 303, but it didn't become part of the + 1.0 version. A basic draft is outlined in appendix C of the + specifcation, and the implementation in Hibernate Validator is largely + influenced by this draft. The feature is considered again for inclusion + in BV 1.1 + + + This approach has several advantages over traditional ways of + parameter or return value checking: + + + + The checks don't have to be performed manually (e.g. by throwing + IllegalArgumentExceptions or similar), + resulting in less code to write and maintain. + + + + A method's pre- and postconditions don't have to be expressed + again in the method's JavaDoc, since the annotations will + automatically be included in the generated JavaDoc. This avoids + redundancy and reduces the chance of inconsistencies between + implementation and documentation. + + + +
+ Defining method-level constraints + + Listing + demonstrates the definition of method level constraints. + Using method-level constraints + + public class RentalStation { + + @NotNull + public Car rentCar(@NotNull Customer customer, @NotNull @Future Date startDate, @Min(1) int durationInDays) { + //... + } +} + + + Here the following pre- and postconditions for the + rentCar() method are declared: + + + + The renting customer may not be null + + + + The rental's start date must not be null and must be in the + future + + + + The rental duration must be at least one day + + + + The returned Car instance may not be null + + + + Using the @Valid annotation it's also possible to define that a + cascaded validation of parameter or return value objects shall be + performed. An example can be found in . Here all the + constraints declared at the Customer type will be + evaluated when validating the method parameter and all constraints + declared at the returned Rental objects will be + evaluated when validating the method's return value. + + + Cascaded validation of method-level constraints + + public class RentalStation { + + @Valid + public Set<Rental> getRentalsByCustomer(@Valid Customer customer) { + //... + } +} + +
+ +
+ Evaluating method-level constraints + + To validate method-level constraints Hibernate Validator provides + the interface + org.hibernate.validator.method.MethodValidator. + As shown in this + interface defines methods for the evaluation of parameter as well as + return value constraints and for retrieving an extended type descriptor + providing method constraint related meta-data. + + + The <classname>MethodValidator</classname> interface + + public interface MethodValidator { + + <T> Set<MethodConstraintViolation<T>> validateParameter(T object, Method method, Object parameterValue, int parameterIndex, Class<?>... groups); + + <T> Set<MethodConstraintViolation<T>> validateAllParameters(T object, Method method, Object[] parameterValues, Class<?>... groups); + + <T> Set<MethodConstraintViolation<T>> validateReturnValue(T object, Method method, Object returnValue, Class<?>... groups); + + TypeDescriptor getConstraintsForType(Class<?> clazz); +} + + + To retrieve a method validator get hold of an instance of HV's + javax.validation.Validator implementation and + unwrap it to MethodValidator as shown in . + + + Retrieving a <classname>MethodValidator</classname> + instance + + MethodValidator methodValidator = Validation.byProvider( HibernateValidator.class ) + .configure() + .buildValidatorFactory() + .getValidator() + .unwrap( MethodValidator.class ); + + + The validation methods defined on MethodValidator each return a + Set<MethodConstraintViolation>. The type + MethodConstraintViolation (see ) extends + javax.validation.ConstraintViolation and + describes in detail the occurred method validation error. + + + The <classname>MethodConstraintViolation</classname> + type + + public interface MethodConstraintViolation<T> extends ConstraintViolation<T> { + + public static enum Kind { PARAMETER, RETURN_VALUE } + + Method getMethod(); + + Integer getParameterIndex(); + + String getParameterName(); + + Kind getKind(); +} + + + + The method getParameterName() currently + returns synthetic parameter identifiers such as "arg0", "arg1" etc. In + a future version of Hibernate Validator support for specifying + parameter identifiers might be added. + + + Typically the validation of method-level constraints is not + invoked manually but automatically upon method invocation by an + integration layer using AOP (aspect-oriented programming) or similar + method interception facilities such as the JDK's + java.lang.reflect.Proxy API or CDI ( "JSR 299: + Contexts and Dependency Injection for the + JavaTM EE platform" ). If a parameter or + return value constraint can't be validated sucessfully such an + integration layer typically will throw a + MethodConstraintViolationException which similar + to javax.validation.ConstraintViolationException + describes the occurred constraint violations. + + + If you are using CDI you might be interested in the Seam + Validation project. This Seam module provides an interceptor + which integrates Hibernate Validator's method validation functionality + with CDI. + +
+ +
+ Extensions to the meta-data API + + +
+
+
Programmatic constraint definition From 24d1b61306e6b9ce3f09d56ac0b43a445b9fe1a8 Mon Sep 17 00:00:00 2001 From: Gunnar Morling Date: Sat, 18 Jun 2011 01:36:48 +0200 Subject: [PATCH 2/7] HV-372: Adding note on precondition strengthening, adding section for method-level meta-data API (work in progress) --- .../docbook/en-US/modules/customoptions.xml | 142 +++++++++++++++--- 1 file changed, 120 insertions(+), 22 deletions(-) diff --git a/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml b/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml index 35dc4bb6e3..ae729230ff 100644 --- a/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml +++ b/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml @@ -225,15 +225,6 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) - - Method validation was also considered to be included in the Bean - Validation API as defined by JSR 303, but it didn't become part of the - 1.0 version. A basic draft is outlined in appendix C of the - specifcation, and the implementation in Hibernate Validator is largely - influenced by this draft. The feature is considered again for inclusion - in BV 1.1 - - This approach has several advantages over traditional ways of parameter or return value checking: @@ -253,6 +244,15 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) + + Method validation was also considered to be included in the Bean + Validation API as defined by JSR 303, but it didn't become part of the + 1.0 version. A basic draft is outlined in appendix C of the + specifcation, and the implementation in Hibernate Validator is largely + influenced by this draft. The feature is considered again for inclusion + in BV 1.1 + +
Defining method-level constraints @@ -271,7 +271,7 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) Here the following pre- and postconditions for the - rentCar() method are declared: + rentCar() method are declared: @@ -295,13 +295,9 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) Using the @Valid annotation it's also possible to define that a cascaded validation of parameter or return value objects shall be performed. An example can be found in . Here all the - constraints declared at the Customer type will be - evaluated when validating the method parameter and all constraints - declared at the returned Rental objects will be - evaluated when validating the method's return value. + linkend="example-cascaded-method-constraints" />. - + Cascaded validation of method-level constraints public class RentalStation { @@ -312,6 +308,66 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) } } + + Here all the constraints declared at the + Customer type will be evaluated when validating + the method parameter and all constraints declared at the returned + Rental objects will be evaluated when validating + the method's return value. + + Special care must be taken when defining parameter constraints in + inheritance hierarchies. When a method is overridden in sub-types only + at the base method parameter constraints may be declared. The reason for + this restriction is that the preconditions to be fulfilled by a type's + client must not be strengthened in sub-types (which maybe are not even + known to the base type's client). + + Note that also if the base method doesn't declare any parameter + constraints at all, no parameter constraints may be added in overriding + methods. The same applies to interface methods: no parameter constraints + may be defined at the implementing method (or the same method declared + in sub-interfaces). + + If a violation of this rule is detected by the validation engine a + javax.validation.ConstraintDeclarationException + will be thrown. In some examples for + illegal parameter constraints declarations are shown. + + + Illegal parameter constraint declarations + + public class Car { + + void drive(Person driver) { ... } + +} + +public class RentalCar { + + //not allowed, parameter constraint added in overriding method + void drive(@NotNull Person driver) { ... } + +} + +public interface Car { + + void drive(Person driver); + +} + +public class CarImpl { + + //not allowed, parameter constraint added in implementation of interface method + void drive(@NotNull Person driver) { ... } + +} + + + This rule only applies to parameter constraints, return value + constraints may be added in sub-types without any restrictions as it is + alright to strengthen the postconditions guaranteed to a type's + client.
@@ -345,7 +401,7 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) unwrap it to MethodValidator as shown in . - + Retrieving a <classname>MethodValidator</classname> instance @@ -360,8 +416,10 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) Set<MethodConstraintViolation>. The type MethodConstraintViolation (see ) extends - javax.validation.ConstraintViolation and - describes in detail the occurred method validation error. + javax.validation.ConstraintViolation and provides + additional method level validation specific information such as the + method and index of the parameter which caused the constraint violation. + The <classname>MethodConstraintViolation</classname> @@ -399,7 +457,7 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) integration layer typically will throw a <classname>MethodConstraintViolationException</classname> which similar to <classname>javax.validation.ConstraintViolationException</classname> - describes the occurred constraint violations.</para> + wraps the occurred constraint violations.</para> <tip> <para>If you are using CDI you might be interested in the <ulink @@ -411,9 +469,49 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) </section> <section> - <title>Extensions to the meta-data API + Retrieving meta-data for method-level constraints + + The Bean Validation API provides rich capabilities for retrieving + constraint related meta data. Hibernate Validator extends this API and + allows to retrieve constraint meta-data also for method-level + constraints. + + shows + how to use this extended PI to retrieve constraint meta-data for the + rentCar() method from the + RentalStation type. + + + Retrieving meta-data for method-level constraints + + TypeDescriptor typeDescriptor = methodValidator.getConstraintsForType(RentalStation.class) + +//retrieve a descriptor for the rentCar() method +MethodDescriptor rentCarMethod = typeDescriptor.getConstraintsForMethod("rentCar", Customer.class, Date.class, int.class); +assertEquals(rentCarMethod.getMethodName(), "rentCar"); +assertTrue(rentCarMethod.hasConstraints()); +assertFalse(rentCarMethod.isCascaded()); + +//retrieve constraints from the return value +Set<ConstraintDescriptor<?>> returnValueConstraints = rentCarMethod.findConstraints().getConstraintDescriptors(); +assertEquals(returnValueConstraints.size(), 1); +assertEquals(returnValueConstraints.iterator().next().getAnnotation().annotationType(), NotNull.class); + +List<ParameterDescriptor> allParameters = rentCarMethod.getParameterDescriptors(); +assertEquals(allParameters.size(), 3); + +//retrieve a descriptor for the startDate parameter +ParameterDescriptor startDateParameter = allParameters.get(1); +assertEquals(startDateParameter.getIndex(), 1); +assertFalse(startDateParameter.isCascaded()); +assertEquals(startDateParameter.findConstraints().getConstraintDescriptors().size(), 2); + - + Refer to the JavaDoc + of the package + org.hibernate.validator.method.metadata for more + details on the extended meta-data API.
From 6cf11f8f2746374ad4ef9721520ea9c0786d5844 Mon Sep 17 00:00:00 2001 From: Gunnar Morling Date: Sat, 18 Jun 2011 11:13:51 +0200 Subject: [PATCH 3/7] HV-372: Fixing typos, improving wording/formatting --- .../docbook/en-US/modules/customoptions.xml | 131 ++++++++++-------- 1 file changed, 70 insertions(+), 61 deletions(-) diff --git a/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml b/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml index ae729230ff..0e6a411c7b 100644 --- a/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml +++ b/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml @@ -210,23 +210,23 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) values, thus enabling a programming style known as "Programming by Contract". - More specifically this means that any Bean Validation constraints - can be used to specify + More specifically this means that Bean Validation constraints can be + used to specify - any preconditions that must be met before a method invocation - (by annotating method parameters with constraints) + the preconditions that must be met before a method invocation + (by annotating method parameters with constraints) and - and any postconditions that are guaranteed after a method - invocation (by annotating methods) + the postconditions that are guaranteed after a method invocation + (by annotating methods) This approach has several advantages over traditional ways of - parameter or return value checking: + parameter and return value checking: @@ -237,7 +237,7 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) A method's pre- and postconditions don't have to be expressed - again in the method's JavaDoc, since the annotations will + again in the method's JavaDoc, since the constraint annotations will automatically be included in the generated JavaDoc. This avoids redundancy and reduces the chance of inconsistencies between implementation and documentation. @@ -248,16 +248,16 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) Method validation was also considered to be included in the Bean Validation API as defined by JSR 303, but it didn't become part of the 1.0 version. A basic draft is outlined in appendix C of the - specifcation, and the implementation in Hibernate Validator is largely + specification, and the implementation in Hibernate Validator is largely influenced by this draft. The feature is considered again for inclusion - in BV 1.1 + in BV 1.1.
Defining method-level constraints Listing - demonstrates the definition of method level constraints. Using method-level constraints @@ -288,7 +288,8 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) - The returned Car instance may not be null + The returned Car instance may not be + null @@ -315,59 +316,64 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) Rental objects will be evaluated when validating the method's return value. - Special care must be taken when defining parameter constraints in - inheritance hierarchies. When a method is overridden in sub-types only - at the base method parameter constraints may be declared. The reason for - this restriction is that the preconditions to be fulfilled by a type's - client must not be strengthened in sub-types (which maybe are not even - known to the base type's client). +
+ Using method constraints in type hierarchies - Note that also if the base method doesn't declare any parameter - constraints at all, no parameter constraints may be added in overriding - methods. The same applies to interface methods: no parameter constraints - may be defined at the implementing method (or the same method declared - in sub-interfaces). + Special care must be taken when defining parameter constraints + in inheritance hierarchies. When a method is overridden in sub-types + only at the base method parameter constraints may be declared. The + reason for this restriction is that the preconditions to be fulfilled + by a type's client must not be strengthened in sub-types (which maybe + are not even known to the base type's client). - If a violation of this rule is detected by the validation engine a - javax.validation.ConstraintDeclarationException - will be thrown. In some examples for - illegal parameter constraints declarations are shown. + Note that also if the base method doesn't declare any parameter + constraints at all, no parameter constraints may be added in + overriding methods. The same applies to interface methods: no + parameter constraints may be defined at the implementing method (or + the same method declared in sub-interfaces). - - Illegal parameter constraint declarations + If a violation of this rule is detected by the validation engine + a + javax.validation.ConstraintDeclarationException + will be thrown. In some examples for + illegal parameter constraints declarations are shown. - public class Car { + + Illegal parameter constraint declarations - void drive(Person driver) { ... } + public class Car { + + public void drive(Person driver) { ... } } -public class RentalCar { +public class RentalCar extends Car { //not allowed, parameter constraint added in overriding method - void drive(@NotNull Person driver) { ... } + public void drive(@NotNull Person driver) { ... } } -public interface Car { +public interface ICar { void drive(Person driver); } -public class CarImpl { +public class CarImpl implements ICar { //not allowed, parameter constraint added in implementation of interface method - void drive(@NotNull Person driver) { ... } + public void drive(@NotNull Person driver) { ... } } - + - This rule only applies to parameter constraints, return value - constraints may be added in sub-types without any restrictions as it is - alright to strengthen the postconditions guaranteed to a type's - client. + This rule only applies to parameter constraints, return value + constraints may be added in sub-types without any restrictions as it + is alright to strengthen the postconditions guaranteed to a type's + client. +
@@ -376,10 +382,12 @@ public class CarImpl { To validate method-level constraints Hibernate Validator provides the interface org.hibernate.validator.method.MethodValidator. - As shown in this - interface defines methods for the evaluation of parameter as well as - return value constraints and for retrieving an extended type descriptor - providing method constraint related meta-data. + + + As shown in + this interface defines methods for the evaluation of parameter as well + as return value constraints and for retrieving an extended type + descriptor providing method constraint related meta-data. The <classname>MethodValidator</classname> interface @@ -418,8 +426,8 @@ public class CarImpl { linkend="example-methodconstraintviolation" />) extends javax.validation.ConstraintViolation and provides additional method level validation specific information such as the - method and index of the parameter which caused the constraint violation. - + method and index of the parameter which caused the constraint + violation. The <classname>MethodConstraintViolation</classname> @@ -452,37 +460,38 @@ public class CarImpl { method interception facilities such as the JDK's <classname>java.lang.reflect.Proxy</classname> API or CDI ( "JSR 299: Contexts and Dependency Injection for the - Java<superscript>TM</superscript> EE platform" ). If a parameter or - return value constraint can't be validated sucessfully such an - integration layer typically will throw a + Java<superscript>TM</superscript> EE platform" ). </para> + + <para>If a parameter or return value constraint can't be validated + sucessfully such an integration layer typically will throw a <classname>MethodConstraintViolationException</classname> which similar to <classname>javax.validation.ConstraintViolationException</classname> - wraps the occurred constraint violations.</para> + contains a set with the occurred constraint violations.</para> <tip> <para>If you are using CDI you might be interested in the <ulink url="http://seamframework.org/Seam3/ValidationModule">Seam Validation</ulink> project. This Seam module provides an interceptor - which integrates Hibernate Validator's method validation functionality - with CDI.</para> + which integrates the method validation functionality with CDI.</para> </tip> </section> <section> - <title>Retrieving meta-data for method-level constraints + Retrieving method-level constraint meta data - The Bean Validation API provides rich capabilities for retrieving + As outlined in + the Bean Validation API provides rich capabilities for retrieving constraint related meta data. Hibernate Validator extends this API and - allows to retrieve constraint meta-data also for method-level - constraints. + allows to retrieve constraint meta data also for method-level + constraints. shows - how to use this extended PI to retrieve constraint meta-data for the + how to use this extended API to retrieve constraint meta data for the rentCar() method from the RentalStation type. - Retrieving meta-data for method-level constraints + Retrieving meta data for method-level constraints TypeDescriptor typeDescriptor = methodValidator.getConstraintsForType(RentalStation.class) @@ -511,7 +520,7 @@ assertEquals(startDateParameter.findConstraints().getConstraintDescriptors().siz url="http://docs.jboss.org/hibernate/validator/4.2/api/index.html?org/hibernate/validator/method/metadata/package-summary.html">JavaDoc of the package org.hibernate.validator.method.metadata for more - details on the extended meta-data API. + details on the extended meta data API.
From f3a88fca0f0ab3d9b21acddd5ac192b6a39e278c Mon Sep 17 00:00:00 2001 From: Gunnar Morling Date: Sat, 18 Jun 2011 11:37:03 +0200 Subject: [PATCH 4/7] HV-372: Improving wording/formatting --- .../docbook/en-US/modules/customoptions.xml | 41 ++++++++++--------- 1 file changed, 22 insertions(+), 19 deletions(-) diff --git a/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml b/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml index 0e6a411c7b..32bdb84bf1 100644 --- a/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml +++ b/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml @@ -293,10 +293,10 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) - Using the @Valid annotation it's also possible to define that a - cascaded validation of parameter or return value objects shall be - performed. An example can be found in . + Using the @Valid annotation it's also + possible to define that a cascaded validation of parameter or return + value objects shall be performed. An example can be found in . Cascaded validation of method-level constraints @@ -320,17 +320,19 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) Using method constraints in type hierarchies Special care must be taken when defining parameter constraints - in inheritance hierarchies. When a method is overridden in sub-types - only at the base method parameter constraints may be declared. The - reason for this restriction is that the preconditions to be fulfilled - by a type's client must not be strengthened in sub-types (which maybe - are not even known to the base type's client). - - Note that also if the base method doesn't declare any parameter - constraints at all, no parameter constraints may be added in - overriding methods. The same applies to interface methods: no - parameter constraints may be defined at the implementing method (or - the same method declared in sub-interfaces). + in inheritance hierarchies. + + When a method is overridden in sub-types only at the base method + parameter constraints may be declared. The reason for this restriction + is that the preconditions to be fulfilled by a type's client must not + be strengthened in sub-types (which may not even be known to the base + type's client). Note that also if the base method doesn't declare any + parameter constraints at all, no parameter constraints may be added in + overriding methods. + + The same restriction applies to interface methods: no parameter + constraints may be defined at the implementing method (or the same + method declared in sub-interfaces). If a violation of this rule is detected by the validation engine a @@ -387,7 +389,7 @@ public class CarImpl implements ICar { As shown in this interface defines methods for the evaluation of parameter as well as return value constraints and for retrieving an extended type - descriptor providing method constraint related meta-data. + descriptor providing method constraint related meta data. The <classname>MethodValidator</classname> interface @@ -420,7 +422,8 @@ public class CarImpl implements ICar { .unwrap( MethodValidator.class ); - The validation methods defined on MethodValidator each return a + The validation methods defined on + MethodValidator each return a Set<MethodConstraintViolation>. The type MethodConstraintViolation (see ) extends @@ -458,9 +461,9 @@ public class CarImpl implements ICar { invoked manually but automatically upon method invocation by an integration layer using AOP (aspect-oriented programming) or similar method interception facilities such as the JDK's - java.lang.reflect.Proxy API or CDI ( "JSR 299: + java.lang.reflect.Proxy API or CDI ("JSR 299: Contexts and Dependency Injection for the - JavaTM EE platform" ). + JavaTM EE platform"). If a parameter or return value constraint can't be validated sucessfully such an integration layer typically will throw a From 22c5e3d3a984ae1bdaf979e100c6e2ba3f764ff0 Mon Sep 17 00:00:00 2001 From: Gunnar Morling Date: Sat, 18 Jun 2011 11:37:50 +0200 Subject: [PATCH 5/7] HV-372: Fixing typos in other parts of the documentation --- .../src/main/docbook/en-US/modules/gettingstarted.xml | 2 +- .../src/main/docbook/en-US/modules/usingvalidator.xml | 10 +++++++--- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml b/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml index a89400cb51..758299ce58 100644 --- a/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml +++ b/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml @@ -69,7 +69,7 @@ Hibernate Validator uses JAXB for XML parsing. JAXB is part of the Java Class Library since Java 6 which means that if you run Hibernate Validator with Java 5 you will have to add additional JAXB dependencies. - Using maven you have to add the following dependencies:<dependency> + Using Maven you have to add the following dependencies:<dependency> <groupId>javax.xml.bind</groupId> <artifactId>jaxb-api</artifactId> <version>2.2</version> diff --git a/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml b/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml index 8c55d07d1f..f9fa2fa2b5 100644 --- a/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml +++ b/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml @@ -147,11 +147,15 @@ public class Car { When using property level constraints property access strategy is used to access the value to be validated. This means the bean validation - provider accesses the state via the property accessor method. + provider accesses the state via the property accessor method. One + advantage of annotating properties instead of fields is that the + constraints become part of the constrained type's API that way and users + are aware of the existing constraints without having to examine the + type's implementation. It is recommended to stick either to field - or property annotation within one class. It is + or property annotations within one class. It is not recommended to annotate a field and the accompanying getter method as this would cause the field to be validated twice. @@ -938,7 +942,7 @@ public void testOrderedChecks() { defined groups in the annotation express the sequence of groups that substitute Default for this class. introduces a new class - RentalCar with a redfined default group. With + RentalCar with a redefined default group. With this definition the check for all three groups can be rewritten as seen in . From 84c853e56196289674474953ac195e05660ba584 Mon Sep 17 00:00:00 2001 From: Gunnar Morling Date: Sat, 18 Jun 2011 12:53:00 +0200 Subject: [PATCH 6/7] HV-372: Adding note on ElementType.PARAMETER to chapter on custom constraints --- .../docbook/en-US/modules/customconstraints.xml | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml b/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml index 4fd328c871..75dcf2848e 100644 --- a/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml +++ b/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml @@ -199,6 +199,18 @@ public class ContactDetails { annotated with it + + + Hibernate Validator provides support for the validation of + method parameters using constraint annotations (see ). + + In order to use a custom constraint for parameter validation the + ElementType.PARAMETER must be specified within + the @Target annotation. This is already the + case for all constraints defined by the Bean Validation API and also + the custom constraints provided by Hibernate Validator. +
@@ -207,8 +219,8 @@ public class ContactDetails { Next, we need to implement a constraint validator, that's able to validate elements with a @CheckCase annotation. - To do so, we implement the interface ConstraintValidator as shown - below: + To do so, we implement the interface + ConstraintValidator as shown below: Implementing a constraint validator for the constraint From 573edf64cc499bc379e8d284dc720be0e85c31f1 Mon Sep 17 00:00:00 2001 From: Gunnar Morling <gunnar.morling@googlemail.com> Date: Sat, 18 Jun 2011 12:53:37 +0200 Subject: [PATCH 7/7] HV-372: Adding note on not using HV internal packages --- .../docbook/en-US/modules/customoptions.xml | 33 +++++++++++-------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml b/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml index 32bdb84bf1..d214edf0ea 100644 --- a/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml +++ b/hibernate-validator/src/main/docbook/en-US/modules/customoptions.xml @@ -39,7 +39,13 @@ <para>Let's start, however, with a look at the public API of Hibernate Validator. <xref linkend="validator-public-api" /> lists all packages - belonging to this API and describes their purpose.</para> + belonging to this API and describes their purpose. </para> + + <para>Any packages not listed in that table are internal packages of + Hibernate Validator and are not intended to be accessed by clients. The + contents of these internal packages can change from release to release + without notice, thus possibly breaking any client code relying on + it.</para> <note> <para>In the following table, when a package is public its not @@ -65,7 +71,7 @@ <entry>This package contains the classes used by the Bean Validation bootstrap mechanism (eg. validation provider, configuration class). For more details see <xref - linkend="validator-bootstrapping" /></entry> + linkend="validator-bootstrapping" />.</entry> </row> <row> @@ -130,12 +136,13 @@ <entry><package>org.hibernate.validator.method</package>, <package>org.hibernate.validator.method.metadata</package></entry> - <entry>Hibernate Validator implements the appendix C of Bean - Validation specification (method level validation). The first - package contains the <classname>MethodValidator</classname> - implementation allowing you to validate method return value and - parameters. The second package contains metadata for constraints - hosted on parameters and methods which can be retrieved via the + <entry>Hibernate Validator provides support for method-level + constraints based on appendix C of the Bean Validation + specification. The first package contains the + <classname>MethodValidator</classname> interface allowing you to + validate method return values and parameters. The second package + contains metavdata for constraints hosted on parameters and + methods which can be retrieved via the <classname>MethodValidator</classname>.</entry> </row> </tbody> @@ -201,7 +208,7 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) </example> </section> - <section> + <section id="validator-customoptions-methodvalidation"> <title>Method validation The Bean Validation API allows to specify constraints for fields, @@ -256,8 +263,8 @@ validator = factory.unwrap( HibernateValidatorFactory.class )
Defining method-level constraints - Listing - demonstrates the definition of method-level constraints. demonstrates + the definition of method-level constraints. Using method-level constraints @@ -334,8 +341,8 @@ validator = factory.unwrap( HibernateValidatorFactory.class ) constraints may be defined at the implementing method (or the same method declared in sub-interfaces). - If a violation of this rule is detected by the validation engine - a + If a violation of this rule is detected by the validation + engine, a javax.validation.ConstraintDeclarationException will be thrown. In some examples for