Author: hardy.ferentschik Date: 2010-03-10 17:13:09 -0500 (Wed, 10 Mar 2010) New Revision: 18980 Modified: validator/trunk/hibernate-validator/pom.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/bootstrapping.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/defineconstraints.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/integration.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/xmlconfiguration.xml validator/trunk/hibernate-validator/src/main/java/org/hibernate/validator/constraints/URL.java validator/trunk/hibernate-validator/src/main/java/org/hibernate/validator/constraints/impl/URLValidator.java validator/trunk/hibernate-validator/src/main/resources/org/hibernate/validator/ValidationMessages.properties validator/trunk/hibernate-validator/src/main/resources/org/hibernate/validator/ValidationMessages_de.properties validator/trunk/hibernate-validator/src/test/java/org/hibernate/validator/constraints/impl/URLValidatorTest.java Log: HV-229 - Added URL constraint and updated docs. Fixed some doc styles as well. Modified: validator/trunk/hibernate-validator/pom.xml =================================================================== --- validator/trunk/hibernate-validator/pom.xml 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/pom.xml 2010-03-10 22:13:09 UTC (rev 18980) @@ -176,7 +176,7 @@ <format> <formatName>pdf</formatName> <stylesheetResource>classpath:/xslt/org/hibernate/jdocbook/xslt/pdf.xsl</stylesheetResource> - <finalName>hibernate_reference.pdf</finalName> + <finalName>hibernate_validator_reference.pdf</finalName> </format> <format> <formatName>html_single</formatName> Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml =================================================================== --- validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/master.xml 2010-03-10 22:13:09 UTC (rev 18980) @@ -19,26 +19,32 @@ <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY version "WORKING"> +<!ENTITY today "TODAY"> <!ENTITY copyrightYear "2009"> <!ENTITY copyrightHolder "Red Hat, Inc. &amp; Gunnar Morling"> ]> <book lang="en"> <bookinfo> <title>Hibernate Validator</title> - <subtitle>JSR 303 Reference Implementation</subtitle> - <subtitle>Reference Guide</subtitle> - <releaseinfo>&version;</releaseinfo> - + <pubdate>&today;</pubdate> <productnumber>&version;</productnumber> - <copyright> <year>&copyrightYear;</year> - <holder>&copyrightHolder;</holder> </copyright> + <authorgroup> + <author> + <firstname>Hardy</firstname> + <surname>Ferentschik</surname> + </author> + <author> + <firstname>Gunnar</firstname> + <surname>Morling</surname> + </author> + </authorgroup> </bookinfo> <toc></toc> Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/bootstrapping.xml =================================================================== --- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/bootstrapping.xml 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/bootstrapping.xml 2010-03-10 22:13:09 UTC (rev 18980) @@ -40,14 +40,12 @@ implementation. In the case of Hibernate Validator this is <classname>org.hibernate.validator.HibernateValidator</classname>.</para> - <para><note> - <para>If there are more than one Bean Validation implementation - providers in the classpath and - <methodname>Validation.buildDefaultValidatorFactory()</methodname> is - used, there is no guarantee which provider will be chosen. To enforce - the provider <methodname>Validation.byProvider()</methodname> should be - used.</para> - </note></para> + <note> + <para>If there are more than one Bean Validation implementation providers in the classpath + and <methodname>Validation.buildDefaultValidatorFactory()</methodname> is used, there is + no guarantee which provider will be chosen. To enforce the provider + <methodname>Validation.byProvider()</methodname> should be used.</para> + </note> <section id="section-validator-instance"> <title><classname>Configuration</classname> and @@ -55,19 +53,20 @@ <para>There are three different methods in the Validation class to create a Validator instance. The easiest in shown in <xref - linkend="example-build-default-validator-factory" />.<example + linkend="example-build-default-validator-factory" />. + </para> + <example id="example-build-default-validator-factory"> <title>Validation.buildDefaultValidatorFactory()</title> - <programlisting>ValidatorFactory factory = <emphasis role="bold">Validation.buildDefaultValidatorFactory()</emphasis>; + <programlisting role="JAVA" language="JAVA">ValidatorFactory factory = Validation.buildDefaultValidatorFactory(); Validator validator = factory.getValidator();</programlisting> - </example>You can also use the method - <methodname>Validation.byDefaultProvider()</methodname> which will allow - you to configure several aspects of the created Validator - instance:<example> - <title>Validation.byDefaultProvider()</title> + </example> + <para> You can also use the method <methodname>Validation.byDefaultProvider()</methodname> + which will allow you to configure several aspects of the created Validator instance:</para><example> + <title>Validation.byDefaultProvider()</title> - <programlisting>Configuration&lt;?&gt; config = <emphasis role="bold">Validation.byDefaultProvider()</emphasis>.configure(); + <programlisting role="JAVA" language="JAVA">Configuration&lt;?&gt; config = Validation.byDefaultProvider().configure(); config.messageInterpolator(new MyMessageInterpolator()) .traversableResolver( new MyTraversableResolver()) .constraintValidatorFactory(new MyConstraintValidatorFactory()); @@ -75,29 +74,27 @@ ValidatorFactory factory = config.buildValidatorFactory(); Validator validator = factory.getValidator(); </programlisting> - </example>We will learn more about - <classname>MessageInterpolator</classname>, - <classname>TraversableResolver</classname> and - <classname>ConstraintValidatorFactory</classname> in the following - sections.</para> + </example><para>We will learn more about <classname>MessageInterpolator</classname>, + <classname>TraversableResolver</classname> and + <classname>ConstraintValidatorFactory</classname> in the following sections.</para> <para>Last but not least you can ask for a Configuration object of a specific Bean Validation provider. This is useful if you have more than one Bean Validation provider in your classpath. In this situation you can make an explicit choice about which implementation to use. In the case of Hibernate Validator the <classname>Validator</classname> creation looks - like:<example> + like:</para> + <example> <title>Validation.byProvider( HibernateValidator.class )</title> - <programlisting>ValidatorConfiguration config = <emphasis role="bold">Validation.byProvider( HibernateValidator.class )</emphasis>.configure(); + <programlisting role="JAVA" language="JAVA">ValidatorConfiguration config = Validation.byProvider( HibernateValidator.class ).configure(); config.messageInterpolator(new MyMessageInterpolator()) .traversableResolver( new MyTraversableResolver()) .constraintValidatorFactory(new MyConstraintValidatorFactory()); ValidatorFactory factory = config.buildValidatorFactory(); Validator validator = factory.getValidator();</programlisting> - </example></para> - + </example> <para><tip> <para>The generated <classname>Validator</classname> instance is thread safe and can be cached.</para> @@ -113,24 +110,24 @@ example in an OSGi environment you could plug your custom provider resolver like seen in <xref linkend="example-provider-resolver" />.</para> - <para><example id="example-provider-resolver"> + <example id="example-provider-resolver"> <title>Providing a custom ValidationProviderResolver</title> - <programlisting>Configuration&lt;?&gt; config = Validation.byDefaultProvider() - <emphasis role="bold">.providerResolver( new OSGiServiceDiscoverer() )</emphasis> + <programlisting role="JAVA" language="JAVA">Configuration&lt;?&gt; config = Validation.byDefaultProvider() + .providerResolver( new OSGiServiceDiscoverer() ) .configure(); ValidatorFactory factory = config.buildValidatorFactory(); Validator validator = factory.getValidator(); </programlisting> - </example>Your <classname>OSGiServiceDiscoverer</classname> must in this + </example><para>Your <classname>OSGiServiceDiscoverer</classname> must in this case implement the interface - <classname>ValidationProviderResolver</classname>:</para> - + <classname>ValidationProviderResolver</classname>: + </para> <example> <title>ValidationProviderResolver interface</title> - <programlisting>public interface ValidationProviderResolver { + <programlisting role="JAVA" language="JAVA">public interface ValidationProviderResolver { /** * Returns a list of ValidationProviders available in the runtime environment. * @@ -158,9 +155,9 @@ <example id="example-message-interpolator"> <title>Providing a custom MessageInterpolator</title> - <programlisting>Configuration&lt;?&gt; configuration = Validation.byDefaultProvider().configure(); + <programlisting role="JAVA" language="JAVA">Configuration&lt;?&gt; configuration = Validation.byDefaultProvider().configure(); ValidatorFactory factory = configuration - <emphasis role="bold">.messageInterpolator(new ContextualMessageInterpolator(configuration.getDefaultMessageInterpolator()))</emphasis> + .messageInterpolator(new ContextualMessageInterpolator(configuration.getDefaultMessageInterpolator())) .buildValidatorFactory(); Validator validator = factory.getValidator(); @@ -188,11 +185,11 @@ would have to be accessed triggering a load from the database. Bean Validation controls which property can and cannot be accessed via the <classname>TraversableResolver</classname> interface (see <xref - linkend="example-traversable-resolver" />).<example + linkend="example-traversable-resolver" />).</para><example id="example-traversable-resolver"> <title>TraversableResolver interface</title> - <programlisting>/** + <programlisting role="JAVA" language="JAVA">/** * 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. * @@ -247,7 +244,7 @@ ElementType elementType); } </programlisting> - </example>Hibernate Validator provides two + </example><para>Hibernate Validator provides two <classname>TraversableResolver</classname>s out of the box which will be enabled automatically depending on your environment. The first is the <classname>DefaultTraversableResolver</classname> which will always return @@ -257,18 +254,18 @@ Hibernate Validator gets used in combination with JPA 2. In case you have to provide your own resolver you can do so again using the <classname>Configuration</classname> object as seen in <xref - linkend="example-traversable-resolver-config" />.<example + linkend="example-traversable-resolver-config" />.</para><example id="example-traversable-resolver-config"> <title>Providing a custom TraversableResolver</title> - <programlisting>Configuration&lt;?&gt; configuration = Validation.byDefaultProvider().configure(); + <programlisting role="JAVA" language="JAVA">Configuration&lt;?&gt; configuration = Validation.byDefaultProvider().configure(); ValidatorFactory factory = configuration - <emphasis role="bold">.traversableResolver(new MyTraversableResolver())</emphasis> + .traversableResolver(new MyTraversableResolver()) .buildValidatorFactory(); Validator validator = factory.getValidator(); </programlisting> - </example></para> + </example> </section> <section> @@ -286,22 +283,22 @@ <classname>Configuration</classname> (<xref linkend="example-constraint-validator-factory" />).</para> - <para><example id="example-constraint-validator-factory"> + <example id="example-constraint-validator-factory"> <title>Providing a custom ConstraintValidatorFactory</title> - <programlisting>Configuration&lt;?&gt; configuration = Validation.byDefaultProvider().configure(); + <programlisting role="JAVA" language="JAVA">Configuration&lt;?&gt; configuration = Validation.byDefaultProvider().configure(); ValidatorFactory factory = configuration - <emphasis role="bold">.constraintValidatorFactory(new IOCConstraintValidatorFactory())</emphasis> + .constraintValidatorFactory(new IOCConstraintValidatorFactory()) .buildValidatorFactory(); Validator validator = factory.getValidator(); </programlisting> - </example>The interface you have to implement is:</para> + </example><para>The interface you have to implement is:</para> - <para><example> + <example> <title>ConstraintValidatorFactory interface</title> - <programlisting>public interface ConstraintValidatorFactory { + <programlisting role="JAVA" language="JAVA">public interface ConstraintValidatorFactory { /** * @param key The class of the constraint validator to instantiate. * @@ -318,6 +315,6 @@ </warning><note> <para>ConstraintValidatorFactory should not cache instances as the state of each instance can be altered in the initialize method.</para> - </note></para> + </note> </section> </chapter> Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml =================================================================== --- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/customconstraints.xml 2010-03-10 22:13:09 UTC (rev 18980) @@ -65,7 +65,7 @@ <title>Enum <classname>CaseMode</classname> to express upper vs. lower case</title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; public enum CaseMode { UPPER, @@ -80,7 +80,7 @@ <example> <title>Defining CheckCase constraint annotation</title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import static java.lang.annotation.ElementType.*; import static java.lang.annotation.RetentionPolicy.*; @@ -135,7 +135,7 @@ objects to a constraint. This attribute is not used by the API itself. <tip> <para>An examle for a custom payload could be the definition of - a severity. <programlisting>public class Severity { + a severity.</para> <programlisting>public class Severity { public static class Info extends ConstraintPayload {}; public static class Error extends ConstraintPayload {}; } @@ -148,7 +148,7 @@ private String phoneNumber; // ... -}</programlisting>Now a client can after the validation of a +}</programlisting><para>Now a client can after the validation of a <classname>ContactDetails</classname> instance access the severity of a constraint using <methodname>ConstraintViolation.getConstraintDescriptor().getPayload()</methodname> @@ -207,7 +207,7 @@ <title>Implementing a constraint validator for the constraint <classname>CheckCase</classname></title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import javax.validation.ConstraintValidator; import javax.validation.ConstraintValidatorContext; @@ -301,7 +301,7 @@ <title>Applying the <classname>CheckCase</classname> constraint</title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import javax.validation.constraints.Min; import javax.validation.constraints.NotNull; @@ -340,7 +340,7 @@ <title>Testcase demonstrating the <classname>CheckCase</classname> validation</title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import static org.junit.Assert.*; @@ -414,7 +414,7 @@ <title>Creating a composing constraint <classname>ValidLicensePlate</classname></title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import static java.lang.annotation.ElementType.*; import static java.lang.annotation.RetentionPolicy.*; @@ -463,7 +463,7 @@ <title>Application of composing constraint <classname>ValidLicensePlate</classname></title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; public class Car { @@ -487,7 +487,7 @@ <example> <title>Usage of <classname>@ReportAsSingleViolation</classname></title> - <programlisting>//... + <programlisting role="JAVA" language="JAVA">//... @ReportAsSingleViolation public @interface ValidLicensePlate { Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/defineconstraints.xml =================================================================== --- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/defineconstraints.xml 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/defineconstraints.xml 2010-03-10 22:13:09 UTC (rev 18980) @@ -281,7 +281,7 @@ <emphasis>validator</emphasis> (the implementation class). Here is a simple user-defined descriptor:</para> - <programlisting&gt;(a)ValidatorClass(CapitalizedValidator.class) + <programlisting role="JAVA" language=&quot;JAVA&quot;&gt;(a)ValidatorClass(CapitalizedValidator.class) @Target(METHOD) @Retention(RUNTIME) @Documented @@ -305,7 +305,7 @@ good practice. See <xref linkend="validator-defineconstraints-error" /> .</para> - <programlisting&gt;(a)ValidatorClass(CapitalizedValidator.class) + <programlisting role="JAVA" language=&quot;JAVA&quot;&gt;(a)ValidatorClass(CapitalizedValidator.class) @Target(METHOD) @Retention(RUNTIME) @Documented @@ -333,7 +333,7 @@ database level (by implementing <literal>PersistentClassConstraint</literal> )</para> - <programlisting>public class CapitalizedValidator + <programlisting role="JAVA" language="JAVA">public class CapitalizedValidator implements Validator&lt;Capitalized&gt;, PropertyConstraint { private CapitalizeType type; @@ -372,7 +372,7 @@ parameters) on the same property or type, you can use the following annotation form:</para> - <programlisting>@Target(METHOD) + <programlisting role="JAVA" language="JAVA">@Target(METHOD) @Retention(RUNTIME) @Documented <emphasis role="bold">public @interface Patterns {</emphasis> @@ -397,7 +397,7 @@ <para>Since you are already familiar with annotations now, the syntax should be very familiar</para> - <programlisting>public class Address { + <programlisting role="JAVA" language="JAVA">public class Address { private String line1; private String line2; private String zip; @@ -456,7 +456,7 @@ <para>While the example only shows public property validation, you can also annotate fields of any kind of visibility</para> - <programlisting>@MyBeanConstraint(max=45 + <programlisting role="JAVA" language="JAVA">@MyBeanConstraint(max=45 public class Dog { @AssertTrue private boolean isMale; @NotNull protected String getName() { ... }; @@ -467,7 +467,7 @@ superclasses and interfaces extended or implemented by a given bean to read the appropriate validator annotations.</para> - <programlisting>public interface Named { + <programlisting role="JAVA" language="JAVA">public interface Named { @NotNull String getName(); ... } Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml =================================================================== --- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/gettingstarted.xml 2010-03-10 22:13:09 UTC (rev 18980) @@ -101,10 +101,10 @@ <para>Open the project in the IDE of your choice and have a look at the class <classname>Car</classname>:</para> - <para><example id="example-class-car"> + <example id="example-class-car"> <title>Class Car annotated with constraints</title> - <programlisting language="Java">package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import javax.validation.constraints.Min; import javax.validation.constraints.NotNull; @@ -112,14 +112,14 @@ public class Car { - <emphasis role="bold">@NotNull</emphasis> + @NotNull private String manufacturer; - <emphasis role="bold">@NotNull</emphasis> - <emphasis role="bold">@Size(min = 2, max = 14)</emphasis> + @NotNull + @Size(min = 2, max = 14) private String licensePlate; - <emphasis role="bold">@Min(2)</emphasis> + @Min(2) private int seatCount; public Car(String manufacturer, String licencePlate, int seatCount) { @@ -130,7 +130,7 @@ //getters and setters ... }</programlisting> - </example><classname>@NotNull</classname>, <classname>@Size</classname> + </example><para><classname>@NotNull</classname>, <classname>@Size</classname> and <classname>@Min</classname> are so-called constraint annotations, that we use to declare constraints, which shall be applied to the fields of a <classname>Car</classname> instance:</para> @@ -161,7 +161,7 @@ <example> <title>Class CarTest showing validation examples</title> - <programlisting language="Java">package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import static org.junit.Assert.*; Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/integration.xml =================================================================== --- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/integration.xml 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/integration.xml 2010-03-10 22:13:09 UTC (rev 18980) @@ -102,7 +102,7 @@ <title>Manual configuration of <classname>BeanValidationEvenListener</classname></title> - <programlisting>&lt;hibernate-configuration&gt; + <programlisting role="XML" language="XML">&lt;hibernate-configuration&gt; &lt;session-factory&gt; ... &lt;property name="javax.persistence.validation.group.pre-persist"&gt;javax.validation.groups.Default&lt;/property&gt; @@ -110,13 +110,13 @@ &lt;property name="javax.persistence.validation.group.pre-remove"&gt;&lt;/property&gt; ... &lt;event type="pre-update"&gt; - &lt;listener class="<classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>"/&gt; + &lt;listener class="org.hibernate.cfg.beanvalidation.BeanValidationEventListener"/&gt; &lt;/event&gt; &lt;event type="pre-insert"&gt; - &lt;listener class="<classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>"/&gt; + &lt;listener class="org.hibernate.cfg.beanvalidation.BeanValidationEventListener"/&gt; &lt;/event&gt; &lt;event type="pre-delete"&gt; - &lt;listener class="<classname>org.hibernate.cfg.beanvalidation.BeanValidationEventListener</classname>"/&gt; + &lt;listener class="org.hibernate.cfg.beanvalidation.BeanValidationEventListener"/&gt; &lt;/event&gt; &lt;/session-factory&gt; &lt;/hibernate-configuration&gt;</programlisting> Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml =================================================================== --- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/usingvalidator.xml 2010-03-10 22:13:09 UTC (rev 18980) @@ -55,16 +55,16 @@ <example id="example-field-level"> <title>Field level constraint</title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import javax.validation.constraints.NotNull; public class Car { - <emphasis role="bold">@NotNull</emphasis> + @NotNull private String manufacturer; - <emphasis role="bold">@AssertTrue</emphasis> + @AssertTrue private boolean isRegistered; public Car(String manufacturer, boolean isRegistered) { @@ -105,7 +105,7 @@ <example id="example-property-level"> <title>Property level constraint</title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import javax.validation.constraints.AssertTrue; import javax.validation.constraints.NotNull; @@ -122,7 +122,7 @@ this.isRegistered = isRegistered; } - <emphasis role="bold">@NotNull</emphasis> + @NotNull public String getManufacturer() { return manufacturer; } @@ -131,7 +131,7 @@ this.manufacturer = manufacturer; } - <emphasis role="bold">@AssertTrue</emphasis> + @AssertTrue public boolean isRegistered() { return isRegistered; } @@ -174,16 +174,16 @@ know that <classname>PassengerCount</classname> will ensure that there cannot be more passengers in a car than there are seats.</para> - <para><example id="example-class-level"> + <example id="example-class-level"> <title>Class level constraint</title> - <programlisting language="Java">package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import javax.validation.constraints.Min; import javax.validation.constraints.NotNull; import javax.validation.constraints.Size; -<emphasis role="bold">@PassengerCount</emphasis> +@PassengerCount public class Car { @NotNull @@ -206,7 +206,7 @@ //getters and setters ... }</programlisting> - </example></para> + </example> </section> <section> @@ -221,7 +221,7 @@ <example> <title>Constraint inheritance using RentalCar</title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import javax.validation.constraints.NotNull; @@ -234,7 +234,7 @@ this.rentalStation = rentalStation; } - <emphasis role="bold">@NotNull</emphasis> + @NotNull public String getRentalStation() { return rentalStation; } @@ -246,7 +246,7 @@ </example> <para>Our well-known class <classname>Car</classname> from <xref - linkend="Car-example" /> is now extended by + linkend="example-class-car" /> is now extended by <classname>RentalCar</classname> with the additional property <property>rentalStation</property>. If an instance of <classname>RentalCar</classname> is validated, not only the @@ -279,13 +279,13 @@ <example> <title>Class Person</title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import javax.validation.constraints.NotNull; public class Person { - <emphasis role="bold">@NotNull</emphasis> + @NotNull private String name; public Person(String name) { @@ -306,15 +306,15 @@ <example id="example-car-with-driver"> <title>Adding a driver to the car</title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import javax.validation.Valid; import javax.validation.constraints.NotNull; public class Car { - <emphasis role="bold">@NotNull</emphasis> - <emphasis role="bold">@Valid</emphasis> + @NotNull + @Valid private Person driver; public Car(Person driver) { @@ -359,7 +359,7 @@ <example> <title>Car with a list of passengers</title> - <programlisting>package com.mycompany; + <programlisting role="JAVA" language="JAVA">package com.mycompany; import java.util.ArrayList; import java.util.List; @@ -370,8 +370,8 @@ public class Car { @NotNull - <emphasis role="bold">@Valid - private List&lt;Person&gt; passengers = new ArrayList&lt;Person&gt;();</emphasis> + @Valid + private List&lt;Person&gt; passengers = new ArrayList&lt;Person&gt;(); public Car(List&lt;Person&gt; passengers) { this.passengers = passengers; @@ -409,12 +409,12 @@ <classname>ValidatorFactory</classname>. The easiest way is to use the static <methodname>Validation.buildDefaultValidatorFactory()</methodname> - method:<example> + method:</para><example> <title>Validation.buildDefaultValidatorFactory()</title> - <programlisting>ValidatorFactory factory = <emphasis role="bold">Validation.buildDefaultValidatorFactory()</emphasis>; + <programlisting role="JAVA" language="JAVA">ValidatorFactory factory = Validation.buildDefaultValidatorFactory(); Validator validator = factory.getValidator();</programlisting> - </example>For other ways of obtaining a Validator instance see <xref + </example><para>For other ways of obtaining a Validator instance see <xref linkend="validator-bootstrapping" />. For now we just want to see how we can use the <classname>Validator</classname> instance to validate entity instances.</para> @@ -436,9 +436,10 @@ <para>All the validation methods have a var-args parameter which can be used to specify, which validation groups shall be considered when performing the validation. If the parameter is not specified the default - validation group (<classname>javax.validation.groups.Default</classname>) will - be used. We will go into more detail on the topic of validation groups - in <xref linkend="validator-usingvalidator-validationgroups" /></para> + validation group + (<classname>javax.validation.groups.Default</classname>) will be used. + We will go into more detail on the topic of validation groups in <xref + linkend="validator-usingvalidator-validationgroups" /></para> <section> <title><methodname>validate</methodname></title> @@ -451,13 +452,12 @@ <title>Usage of <methodname>Validator.validate()</methodname></title> - <programlisting>ValidatorFactory factory = Validation.buildDefaultValidatorFactory(); + <programlisting role="JAVA" language="JAVA">ValidatorFactory factory = Validation.buildDefaultValidatorFactory(); Validator validator = factory.getValidator(); Car car = new Car(null); -Set&lt;ConstraintViolation&lt;Car&gt;&gt; constraintViolations = <emphasis - role="bold">validator.validate(car)</emphasis>; +Set&lt;ConstraintViolation&lt;Car&gt;&gt; constraintViolations = validator.validate(car); assertEquals(1, constraintViolations.size()); assertEquals("may not be null", constraintViolations.iterator().next().getMessage());</programlisting> @@ -475,12 +475,11 @@ <title>Usage of <methodname>Validator.validateProperty()</methodname></title> - <programlisting>Validator validator = Validation.buildDefaultValidatorFactory().getValidator(); + <programlisting role="JAVA" language="JAVA">Validator validator = Validation.buildDefaultValidatorFactory().getValidator(); Car car = new Car(null); -Set&lt;ConstraintViolation&lt;Car&gt;&gt; constraintViolations = <emphasis - role="bold">validator.validateProperty(car, "manufacturer")</emphasis>; +Set&lt;ConstraintViolation&lt;Car&gt;&gt; constraintViolations = validator.validateProperty(car, "manufacturer"); assertEquals(1, constraintViolations.size()); assertEquals("may not be null", constraintViolations.iterator().next().getMessage());</programlisting> @@ -502,10 +501,9 @@ <title>Usage of <methodname>Validator.validateValue()</methodname></title> - <programlisting>Validator validator = Validation.buildDefaultValidatorFactory().getValidator(); + <programlisting role="JAVA" language="JAVA">Validator validator = Validation.buildDefaultValidatorFactory().getValidator(); -Set&lt;ConstraintViolation&lt;Car&gt;&gt; constraintViolations = <emphasis - role="bold">validator.validateValue(Car.class, "manufacturer", null)</emphasis>; +Set&lt;ConstraintViolation&lt;Car&gt;&gt; constraintViolations = validator.validateValue(Car.class, "manufacturer", null); assertEquals(1, constraintViolations.size()); assertEquals("may not be null", constraintViolations.iterator().next().getMessage());</programlisting> @@ -668,7 +666,6 @@ <section id="validator-usingvalidator-validationgroups"> <title>Validating groups</title> - <para>Groups allow you to restrict the set of constraints applied during validation. This makes for example wizard like validation possible where in each step only a specified subset of constraints get validated. The @@ -682,19 +679,16 @@ </classname>constraint on <property>name</property>. Since no group is specified for this annotation its default group is <classname>javax.validation.groups.Default</classname>.</para> - <note> <para>When more than one group is requested, the order in which the groups are evaluated is not deterministic. If no group is specified the default group <classname>javax.validation.groups.Default</classname> is assumed.</para> </note> - - <para><example id="example-person"> + <example id="example-person"> <title>Person</title> - - <programlisting>public class Person { - <emphasis role="bold">@NotNull</emphasis> + <programlisting role="JAVA" language="JAVA">public class Person { + @NotNull private String name; public Person(String name) { @@ -702,7 +696,9 @@ } // getters and setters ... }</programlisting> - </example>Next we have the class <classname>Driver</classname> (<xref + </example> + + <para>Next we have the class <classname>Driver</classname> (<xref linkend="example-driver" />) extending <classname>Person</classname>. Here we are adding the properties <property>age</property> and <property>hasDrivingLicense</property>. In order to drive you must be at @@ -713,18 +709,20 @@ <classname>DriverChecks</classname> is just a simple tagging interface. Using interfaces makes the usage of groups type safe and allows for easy refactoring. It also means that groups can inherit from each other via - class inheritance.<note> + class inheritance.</para> + <note> <para>The Bean Validation specification does not enforce that groups have to be interfaces. Non interface classes could be used as well, - but we recommend to stick to interfaces.</para> - </note><example id="example-driver"> + but we recommend to stick to interfaces. + </para> + </note> + <example id="example-driver"> <title>Driver</title> - - <programlisting>public class Driver extends Person { - <emphasis role="bold">@Min(value = 18, message = "You have to be 18 to drive a car", groups = DriverChecks.class)</emphasis> + <programlisting role="JAVA" language="JAVA">public class Driver extends Person { + @Min(value = 18, message = "You have to be 18 to drive a car", groups = DriverChecks.class) public int age; - <emphasis role="bold">@AssertTrue(message = "You first have to pass the driving test", groups = DriverChecks.class)</emphasis> + @AssertTrue(message = "You first have to pass the driving test", groups = DriverChecks.class) public boolean hasDrivingLicense; public Driver(String name) { @@ -743,22 +741,25 @@ this.age = age; } }</programlisting> - </example><example id="example-group-interfaces"> + </example> + <example id="example-group-interfaces"> <title>Group interfaces</title> - - <programlisting>public interface DriverChecks { + <programlisting role="JAVA" language="JAVA">public interface DriverChecks { } public interface CarChecks { }</programlisting> - </example>Last but not least we add the property + </example> + <para>Last but not least we add the property <property>passedVehicleInspection</property> to the <classname>Car</classname> class (<xref linkend="example-car" />) - indicating whether a car passed the road worthy tests.<example + indicating whether a car passed the road worthy tests. + </para> + <example id="example-car"> <title>Car</title> - <programlisting>public class Car { + <programlisting role="JAVA" language="JAVA">public class Car { @NotNull private String manufacturer; @@ -769,7 +770,7 @@ @Min(2) private int seatCount; - <emphasis role="bold">@AssertTrue(message = "The car has to pass the vehicle inspection first", groups = CarChecks.class)</emphasis> + @AssertTrue(message = "The car has to pass the vehicle inspection first", groups = CarChecks.class) private boolean passedVehicleInspection; @Valid @@ -781,7 +782,8 @@ this.seatCount = seatCount; } }</programlisting> - </example>Overall three different groups are used in our example. + </example> + <para>Overall three different groups are used in our example. <property>Person.name</property>, <property>Car.manufacturer</property>, <property>Car.licensePlate</property> and <property>Car.seatCount</property> all belong to the @@ -792,11 +794,12 @@ <classname>CarChecks</classname>. <xref linkend="example-drive-away" /> shows how passing different group combinations to the <methodname>Validator.validate</methodname> method result in different - validation results.<example id="example-drive-away"> + validation results. + </para> + <example id="example-drive-away"> <title>Drive away</title> + <programlisting role="JAVA" language="JAVA">public class GroupTest { - <programlisting>public class GroupTest { - private static Validator validator; @BeforeClass @@ -837,24 +840,26 @@ assertEquals( 0, validator.validate( car, Default.class, CarChecks.class, DriverChecks.class ).size() ); } }</programlisting> - </example>First we create a car and validate it using no explicit group. + </example> + <para>First we create a car and validate it using no explicit group. There are no validation errors, even though the property <property>passedVehicleInspection</property> is per default <constant>false</constant>. However, the constraint defined on this - property does not belong to the default group.</para> + property does not belong to the default group. - <para>Next we just validate the <classname>CarChecks</classname> group + Next we just validate the <classname>CarChecks</classname> group which will fail until we make sure that the car passes the vehicle - inspection.</para> + inspection. - <para>When we then add a driver to the car and validate against + When we then add a driver to the car and validate against <classname>DriverChecks</classname> we get again a constraint violation due to the fact that the driver has not yet passed the driving test. Only after setting <property>passedDrivingTest</property> to true the validation against <classname>DriverChecks</classname> will pass.</para> <para>Last but not least, we show that all constraints are passing by - validating against all defined groups.</para> + validating against all defined groups. + </para> <section> <title>Group sequences</title> @@ -877,13 +882,13 @@ validated.</para> </note> - <para><example> + <example> <title>Interface with @GroupSequence</title> - <programlisting><emphasis role=&quot;bold&quot;&gt;(a)GroupSequence({Default.class, CarChecks.class, DriverChecks.class})</emphasis> + <programlisting role="JAVA" language=&quot;JAVA&quot;&gt;(a)GroupSequence({Default.class, CarChecks.class, DriverChecks.class}) public interface OrderedChecks { }</programlisting> - </example></para> + </example> <para><warning> <para>Groups defining a sequence and groups composing a sequence @@ -897,7 +902,7 @@ <example id="example-group-sequence"> <title>Usage of a group sequence</title> - <programlisting>@Test + <programlisting role="JAVA" language="JAVA">@Test public void testOrderedChecks() { Car car = new Car( "Morris", "DD-AB-123", 2 ); car.setPassedVehicleInspection( true ); @@ -929,7 +934,7 @@ <example id="example-rental-car"> <title>RentalCar</title> - <programlisting>@GroupSequence({ RentalCar.class, CarChecks.class }) + <programlisting role="JAVA" language="JAVA">@GroupSequence({ RentalCar.class, CarChecks.class }) public class RentalCar extends Car { public RentalCar(String manufacturer, String licencePlate, int seatCount) { super( manufacturer, licencePlate, seatCount ); @@ -940,7 +945,7 @@ <example id="example-testOrderedChecksWithRedefinedDefault"> <title>testOrderedChecksWithRedefinedDefault</title> - <programlisting>@Test + <programlisting role="JAVA" language="JAVA">@Test public void testOrderedChecksWithRedefinedDefault() { RentalCar rentalCar = new RentalCar( "Morris", "DD-AB-123", 2 ); rentalCar.setPassedVehicleInspection( true ); @@ -1256,6 +1261,23 @@ </row> <row> + <entry>@URL(protocol=, host=, port=)</entry> + + <entry>yes</entry> + + <entry>field/property. Supported types are + <classname>String</classname>.</entry> + + <entry>Check if the annotated string is a valid URL. If any of + parameters <parameter>protocol</parameter>, + <parameter>host</parameter> or <parameter>port</parameter> is + specified the URL must match the specified values in the according + part.</entry> + + <entry>none</entry> + </row> + + <row> <entry>@Valid</entry> <entry>yes</entry> Modified: validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/xmlconfiguration.xml =================================================================== --- validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/xmlconfiguration.xml 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/docbook/en-US/modules/xmlconfiguration.xml 2010-03-10 22:13:09 UTC (rev 18980) @@ -52,7 +52,7 @@ <example id="example-validation-xml"> <title>validation.xml</title> - <programlisting>&lt;validation-config xmlns="http://jboss.org/xml/ns/javax/validation/configuration" + <programlisting role="XML" language="XML">&lt;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/configu... &lt;default-provider&gt;org.hibernate.validator.HibernateValidator&lt;/default-provider&gt; @@ -129,7 +129,7 @@ <example id="example-constraints-car"> <title>constraints-car.xml</title> - <programlisting>&lt;constraint-mappings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + <programlisting role="XML" language="XML">&lt;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"&gt; &lt;default-package&gt;org.hibernate.validator.quickstart&lt;/default-package&gt; Modified: validator/trunk/hibernate-validator/src/main/java/org/hibernate/validator/constraints/URL.java =================================================================== --- validator/trunk/hibernate-validator/src/main/java/org/hibernate/validator/constraints/URL.java 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/java/org/hibernate/validator/constraints/URL.java 2010-03-10 22:13:09 UTC (rev 18980) @@ -40,6 +40,12 @@ @Target({ METHOD, FIELD, TYPE }) @Retention(RUNTIME) public @interface URL { + public abstract String protocol() default ""; + + public abstract String host() default ""; + + public abstract int port() default -1; + public abstract String message() default "{org.hibernate.validator.constraints.URL.message}"; public abstract Class<?>[] groups() default { }; Modified: validator/trunk/hibernate-validator/src/main/java/org/hibernate/validator/constraints/impl/URLValidator.java =================================================================== --- validator/trunk/hibernate-validator/src/main/java/org/hibernate/validator/constraints/impl/URLValidator.java 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/java/org/hibernate/validator/constraints/impl/URLValidator.java 2010-03-10 22:13:09 UTC (rev 18980) @@ -29,19 +29,41 @@ * @author Hardy Ferentschik */ public class URLValidator implements ConstraintValidator<URL, String> { + private String protocol; + private String host; + private int port; + public void initialize(URL url) { + this.protocol = url.protocol(); + this.host = url.host(); + this.port = url.port(); } public boolean isValid(String value, ConstraintValidatorContext constraintValidatorContext) { if ( value == null ) { return true; } + + java.net.URL url; try { - new java.net.URL( value ); - return true; + url = new java.net.URL( value ); } catch ( MalformedURLException e ) { return false; } + + if ( protocol != null && protocol.length() > 0 && !url.getProtocol().equals( protocol ) ) { + return false; + } + + if ( host != null && host.length() > 0 && !url.getHost().equals( host ) ) { + return false; + } + + if ( port != -1 && url.getPort() != port ) { + return false; + } + + return true; } } \ No newline at end of file Modified: validator/trunk/hibernate-validator/src/main/resources/org/hibernate/validator/ValidationMessages.properties =================================================================== --- validator/trunk/hibernate-validator/src/main/resources/org/hibernate/validator/ValidationMessages.properties 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/resources/org/hibernate/validator/ValidationMessages.properties 2010-03-10 22:13:09 UTC (rev 18980) @@ -16,4 +16,5 @@ org.hibernate.validator.constraints.Length.message=length must be between {min} and {max} org.hibernate.validator.constraints.NotEmpty.message=may not be empty org.hibernate.validator.constraints.Range.message=must be between {min} and {max} +org.hibernate.validator.constraints.URL.message=must be a valid URL Modified: validator/trunk/hibernate-validator/src/main/resources/org/hibernate/validator/ValidationMessages_de.properties =================================================================== --- validator/trunk/hibernate-validator/src/main/resources/org/hibernate/validator/ValidationMessages_de.properties 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/main/resources/org/hibernate/validator/ValidationMessages_de.properties 2010-03-10 22:13:09 UTC (rev 18980) @@ -15,4 +15,5 @@ javax.validation.constraints.DecimalMin.message=muss gr\u00F6ssergleich {value} sein javax.validation.constraints.DecimalMax.message=muss kleinergleich {value} sein org.hibernate.validator.constraints.Email.message=keine g\u00FCltige E-Mail-Adresse -org.hibernate.validator.constraints.Range.message=muss zwischen {min} und {max} liegen \ No newline at end of file +org.hibernate.validator.constraints.Range.message=muss zwischen {min} und {max} liegen +org.hibernate.validator.constraints.URL.message=muss eine g\u00FCltige URL sein \ No newline at end of file Modified: validator/trunk/hibernate-validator/src/test/java/org/hibernate/validator/constraints/impl/URLValidatorTest.java =================================================================== --- validator/trunk/hibernate-validator/src/test/java/org/hibernate/validator/constraints/impl/URLValidatorTest.java 2010-03-10 18:59:19 UTC (rev 18979) +++ validator/trunk/hibernate-validator/src/test/java/org/hibernate/validator/constraints/impl/URLValidatorTest.java 2010-03-10 22:13:09 UTC (rev 18980) @@ -17,16 +17,17 @@ */ package org.hibernate.validator.constraints.impl; -import static org.testng.Assert.assertFalse; -import static org.testng.Assert.assertTrue; import org.testng.annotations.Test; import org.hibernate.validator.constraints.URL; import org.hibernate.validator.util.annotationfactory.AnnotationDescriptor; import org.hibernate.validator.util.annotationfactory.AnnotationFactory; +import static org.testng.Assert.assertFalse; +import static org.testng.Assert.assertTrue; + /** - * Tests the {@code Url} constraint. + * Tests the {@code URL} constraint. See HV-229 * * @author Hardy Ferentschik */ @@ -35,14 +36,73 @@ @Test public void testIsValidUrl() { AnnotationDescriptor<URL> descriptor = new AnnotationDescriptor<URL>( URL.class ); - descriptor.setValue( "message", "{org.hibernate.validator.constraints.URL.message}" ); URL url = AnnotationFactory.create( descriptor ); URLValidator validator = new URLValidator(); validator.initialize( url ); + assertTrue( validator.isValid( null, null ) ); assertFalse( validator.isValid( "", null ) ); assertFalse( validator.isValid( "http", null ) ); assertFalse( validator.isValid( "ftp//abc.de", null ) ); assertTrue( validator.isValid( "ftp://abc.de", null ) ); } + + + @Test + public void testIsValidUrlWithProtocolSpecified() { + AnnotationDescriptor<URL> descriptor = new AnnotationDescriptor<URL>( URL.class ); + descriptor.setValue( "protocol", "http" ); + URL url = AnnotationFactory.create( descriptor ); + URLValidator validator = new URLValidator(); + validator.initialize( url ); + + assertFalse( validator.isValid( "ftp://abc.de", null ) ); + assertTrue( validator.isValid( "http://abc.de", null ) ); + + descriptor = new AnnotationDescriptor<URL>( URL.class ); + descriptor.setValue( "protocol", "file" ); + url = AnnotationFactory.create( descriptor ); + validator = new URLValidator(); + validator.initialize( url ); + assertFalse( validator.isValid( "http://abc.de", null ) ); + assertTrue( validator.isValid( "file://Users/foobar/tmp", null ) ); + } + + @Test + public void testIsValidUrlWithPortSpecified() { + AnnotationDescriptor<URL> descriptor = new AnnotationDescriptor<URL>( URL.class ); + descriptor.setValue( "port", 21 ); + URL url = AnnotationFactory.create( descriptor ); + URLValidator validator = new URLValidator(); + validator.initialize( url ); + + assertFalse( validator.isValid( "ftp://abc.de", null ) ); + assertTrue( validator.isValid( "ftp://abc.de:21", null ) ); + } + + @Test + public void testIsValidUrlWithHostSpecified() { + AnnotationDescriptor<URL> descriptor = new AnnotationDescriptor<URL>( URL.class ); + descriptor.setValue( "host", "foobar.com" ); + URL url = AnnotationFactory.create( descriptor ); + URLValidator validator = new URLValidator(); + validator.initialize( url ); + + assertFalse( validator.isValid( "http://fubar.com/this/is/foobar.html", null ) ); + assertTrue( validator.isValid( "http://foobar.com/this/is/foobar.html", null ) ); + } + + @Test + public void testIsValidUrlWithProtocolHostAndPort() { + AnnotationDescriptor<URL> descriptor = new AnnotationDescriptor<URL>( URL.class ); + descriptor.setValue( "protocol", "http" ); + descriptor.setValue( "host", "www.hibernate.org" ); + descriptor.setValue( "port", 80 ); + URL url = AnnotationFactory.create( descriptor ); + URLValidator validator = new URLValidator(); + validator.initialize( url ); + + assertFalse( validator.isValid( "ftp://www#hibernate#org:80", null ) ); + assertTrue( validator.isValid( "http://www.hibernate.org:80", null ) ); + } } \ No newline at end of file