From fbb55948e463270e2c78126cf8166c75170ac5b6 Mon Sep 17 00:00:00 2001 From: Gunnar Morling Date: Fri, 29 Jun 2012 20:09:40 +0200 Subject: [PATCH] HV-602: Clearifying documentation on "META-INF/services" and mapping file names, improving general wording --- .../en-US/modules/xmlconfiguration.xml | 105 ++++++++++-------- 1 file changed, 58 insertions(+), 47 deletions(-) diff --git a/documentation/src/main/docbook/en-US/modules/xmlconfiguration.xml b/documentation/src/main/docbook/en-US/modules/xmlconfiguration.xml index 00579de820..721014cc5c 100644 --- a/documentation/src/main/docbook/en-US/modules/xmlconfiguration.xml +++ b/documentation/src/main/docbook/en-US/modules/xmlconfiguration.xml @@ -27,11 +27,11 @@ <filename>validation.xml</filename> The key to enable XML configuration for Hibernate Validator is the - file validation.xml. If this file exists in the - classpath its configuration will be applied when the + file META-INF/validation.xml. If this file exists on + the classpath its configuration will be applied when the ValidationFactory gets created. shows a model view of the xsd - valiation.xml has to adhere to. shows a model view of the XML + schema to which validation.xml has to adhere. validation-configuration-1.0.xsd @@ -54,45 +54,52 @@ validation.xml - <validation-config xmlns="http://jboss.org/xml/ns/javax/validation/configuration" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/configuration"> + <validation-config + xmlns="http://jboss.org/xml/ns/javax/validation/configuration" + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/configuration"> + <default-provider>org.hibernate.validator.HibernateValidator</default-provider> <message-interpolator>org.hibernate.validator.messageinterpolation.ResourceBundleMessageInterpolator</message-interpolator> <traversable-resolver>org.hibernate.validator.engine.resolver.DefaultTraversableResolver</traversable-resolver> <constraint-validator-factory>org.hibernate.validator.engine.ConstraintValidatorFactoryImpl</constraint-validator-factory> - <constraint-mapping>/constraints-car.xml</constraint-mapping> + <constraint-mapping>META-INF/validation/constraints-car.xml</constraint-mapping> <property name="prop1">value1</property> <property name="prop2">value2</property> </validation-config> - There can only be one validation.xml in the - classpath. If more than one is found an exception is thrown. + There must only be one file named + META-INF/validation.xml on the classpath. If more + than one is found an exception is thrown. - All settings shown in the validation.xml are - optional and in the case of show - the defaults used within Hibernate Validator. The node - default-provider allows to choose the Bean Validation - provider. This is useful if there is more than one provider in the - classpath. message-interpolator, + The node default-provider allows to choose the + Bean Validation provider. This is useful if there is more than one + provider on the classpath. message-interpolator, traversable-resolver and constraint-validator-factory allow to customize the + used implementations for javax.validation.MessageInterpolator, javax.validation.TraversableResolver resp. - javax.validation.ConstraintValidatorFactory. The - same configuration options are also available programmatically through the + javax.validation.ConstraintValidatorFactory. + + All these settings are optional. shows the defaults used within + Hibernate Validator. The same configuration options are also available + programmatically through javax.validation.Configuration. In fact XML configuration will be overridden by values explicitly specified via the API. It is even possible to ignore the XML configuration completely via - Configuration.ignoreXmlConfiguration(). See also + Configuration.ignoreXmlConfiguration(). See also . - Via the constraint-mapping you can list an - arbitrary number of additional XML files containing the actual constraint - configuration. See . + Via the constraint-mapping element you can list + an arbitrary number of additional XML files containing the actual + constraint configuration. Mapping file names must be specified using their + fully-qualified name on the classpath. Details on writing mapping files + can be found in the next section. Last but not least, you can specify provider specific properties via the property nodes. @@ -102,8 +109,8 @@ Mapping constraints Expressing constraints in XML is possible via files adhering to the - xsd seen in . Note that these - mapping files are only processed if listed via + schema seen in . Note that + these mapping files are only processed if listed via constraint-mapping in your validation.xml. @@ -123,16 +130,19 @@ - shows how our classes Car - and RentalCar from resp. could be mapped in XML. + shows how our classes + Car and RentalCar from resp. could + be mapped in XML. constraints-car.xml - <constraint-mappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/mapping validation-mapping-1.0.xsd" - xmlns="http://jboss.org/xml/ns/javax/validation/mapping"> + <constraint-mappings + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/mapping validation-mapping-1.0.xsd" + xmlns="http://jboss.org/xml/ns/javax/validation/mapping"> + <default-package>org.hibernate.validator.quickstart</default-package> <bean class="Car" ignore-annotations="true"> <field name="manufacturer"> @@ -177,31 +187,32 @@ The XML configuration is closely mirroring the programmatic API. For this reason it should suffice to just add some comments. - default-package is used for all fields where a - classname is expected. If the specified class is not fully qualified the + default-package is used for all fields where a class + name is expected. If the specified class is not fully qualified the configured default package will be used. Every mapping file can then have several bean nodes, each describing the constraints on the entity with the specified class name. A given entity can only be configured once across all configuration files. If the same class is configured more than once an exception is thrown. - Settings ignore-annotations to true means - that constraint annotations placed on the configured bean are ignored. The - default for this value is true. ignore-annotations is - also available for the nodes class, - fields and getter. If not - explicitly specified on these levels the configured - bean value applies. Otherwise do the nodes - class, fields and + Setting ignore-annotations to + true means that constraint annotations placed on the + configured bean are ignored. The default for this value is + true. ignore-annotations is also available for the + nodes class, fields and + getter. If not explicitly specified on these levels + the configured bean value applies. Otherwise do the + nodes class, fields and getter determine on which level the constraints are placed (see ). The constraint node is then used to add a constraint on the corresponding level. Each constraint definition must define the class - via the annotation attribute. The constraint attributes required by the - Bean Validation specification (message, - groups and payload) have - dedicated nodes. All other constraint specific attributes are configured - using the the element node. + via the annotation attribute. The constraint + attributes required by the Bean Validation specification + (message, groups and + payload) have dedicated nodes. All other constraint + specific attributes are configured using the element + node. The class node also allows to reconfigure the default group sequence (see ) via the @@ -218,7 +229,7 @@ include-existing-validator is set to false, validators defined on the constraint annotation are ignored. If set to true, the list of - ConstraintValidators described in XML are concatenated to the list of - validators described on the annotation. + constraint validators described in XML is concatenated to the list of + validators specified on the annotation.