| [[bean-validator-component]] |
| = Bean Validator Component |
| :page-source: components/camel-bean-validator/src/main/docs/bean-validator-component.adoc |
| |
| *Since Camel 2.3* |
| |
| // HEADER START |
| *Only producer is supported* |
| // HEADER END |
| |
| The Validator component performs bean validation of the message body |
| using the Java Bean Validation API |
| (http://jcp.org/en/jsr/detail?id=303[JSR 303]). Camel uses the reference |
| implementation, which is |
| http://docs.jboss.org/hibernate/validator/4.3/reference/en-US/html_single/[Hibernate |
| Validator]. |
| |
| Maven users will need to add the following dependency to their `pom.xml` |
| for this component: |
| |
| [source,xml] |
| ------------------------------------------------------------ |
| <dependency> |
| <groupId>org.apache.camel</groupId> |
| <artifactId>camel-bean-validator</artifactId> |
| <version>x.y.z</version> |
| <!-- use the same version as your Camel core version --> |
| </dependency> |
| ------------------------------------------------------------ |
| |
| == URI format |
| |
| [source,java] |
| ------------------------------ |
| bean-validator:label[?options] |
| ------------------------------ |
| |
| or |
| |
| [source,java] |
| -------------------------------- |
| bean-validator://label[?options] |
| -------------------------------- |
| |
| Where *label* is an arbitrary text value describing the endpoint. + |
| You can append query options to the URI in the following format, |
| ?option=value&option=value&... |
| |
| == URI Options |
| |
| |
| // component options: START |
| The Bean Validator component supports 8 options, which are listed below. |
| |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *ignoreXmlConfiguration* (producer) | Whether to ignore data from the META-INF/validation.xml file. | false | boolean |
| | *validationProvider Resolver* (advanced) | To use a a custom ValidationProviderResolver | | ValidationProviderResolver |
| | *messageInterpolator* (advanced) | To use a custom MessageInterpolator | | MessageInterpolator |
| | *traversableResolver* (advanced) | To use a custom TraversableResolver | | TraversableResolver |
| | *constraintValidator Factory* (advanced) | To use a custom ConstraintValidatorFactory | | ConstraintValidatorFactory |
| | *basicPropertyBinding* (advanced) | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean |
| | *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean |
| | *bridgeErrorHandler* (consumer) | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | boolean |
| |=== |
| // component options: END |
| |
| |
| |
| // endpoint options: START |
| The Bean Validator endpoint is configured using URI syntax: |
| |
| ---- |
| bean-validator:label |
| ---- |
| |
| with the following path and query parameters: |
| |
| === Path Parameters (1 parameters): |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *label* | *Required* Where label is an arbitrary text value describing the endpoint | | String |
| |=== |
| |
| |
| === Query Parameters (9 parameters): |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *group* (producer) | To use a custom validation group | javax.validation.groups.Default | String |
| | *ignoreXmlConfiguration* (producer) | Whether to ignore data from the META-INF/validation.xml file. | false | boolean |
| | *lazyStartProducer* (producer) | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | boolean |
| | *basicPropertyBinding* (advanced) | Whether the endpoint should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | boolean |
| | *constraintValidatorFactory* (advanced) | To use a custom ConstraintValidatorFactory | | ConstraintValidatorFactory |
| | *messageInterpolator* (advanced) | To use a custom MessageInterpolator | | MessageInterpolator |
| | *synchronous* (advanced) | Sets whether synchronous processing should be strictly used, or Camel is allowed to use asynchronous processing (if supported). | false | boolean |
| | *traversableResolver* (advanced) | To use a custom TraversableResolver | | TraversableResolver |
| | *validationProviderResolver* (advanced) | To use a a custom ValidationProviderResolver | | ValidationProviderResolver |
| |=== |
| // endpoint options: END |
| // spring-boot-auto-configure options: START |
| == Spring Boot Auto-Configuration |
| |
| When using Spring Boot make sure to use the following Maven dependency to have support for auto configuration: |
| |
| [source,xml] |
| ---- |
| <dependency> |
| <groupId>org.apache.camel.springboot</groupId> |
| <artifactId>camel-bean-validator-starter</artifactId> |
| <version>x.x.x</version> |
| <!-- use the same version as your Camel core version --> |
| </dependency> |
| ---- |
| |
| |
| The component supports 9 options, which are listed below. |
| |
| |
| |
| [width="100%",cols="2,5,^1,2",options="header"] |
| |=== |
| | Name | Description | Default | Type |
| | *camel.component.bean-validator.basic-property-binding* | Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities | false | Boolean |
| | *camel.component.bean-validator.bridge-error-handler* | Allows for bridging the consumer to the Camel routing Error Handler, which mean any exceptions occurred while the consumer is trying to pickup incoming messages, or the likes, will now be processed as a message and handled by the routing Error Handler. By default the consumer will use the org.apache.camel.spi.ExceptionHandler to deal with exceptions, that will be logged at WARN or ERROR level and ignored. | false | Boolean |
| | *camel.component.bean-validator.constraint-validator-factory* | To use a custom ConstraintValidatorFactory. The option is a javax.validation.ConstraintValidatorFactory type. | | String |
| | *camel.component.bean-validator.enabled* | Enable bean-validator component | true | Boolean |
| | *camel.component.bean-validator.ignore-xml-configuration* | Whether to ignore data from the META-INF/validation.xml file. | false | Boolean |
| | *camel.component.bean-validator.lazy-start-producer* | Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel's routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing. | false | Boolean |
| | *camel.component.bean-validator.message-interpolator* | To use a custom MessageInterpolator. The option is a javax.validation.MessageInterpolator type. | | String |
| | *camel.component.bean-validator.traversable-resolver* | To use a custom TraversableResolver. The option is a javax.validation.TraversableResolver type. | | String |
| | *camel.component.bean-validator.validation-provider-resolver* | To use a a custom ValidationProviderResolver. The option is a javax.validation.ValidationProviderResolver type. | | String |
| |=== |
| // spring-boot-auto-configure options: END |
| |
| |
| |
| == OSGi deployment |
| |
| To use Hibernate Validator in the OSGi environment use dedicated |
| `ValidationProviderResolver` implementation, just as |
| `org.apache.camel.component.bean.validator.HibernateValidationProviderResolver`. |
| The snippet below demonstrates this approach. You can also |
| use `HibernateValidationProviderResolver`. |
| |
| *Using HibernateValidationProviderResolver* |
| |
| [source,java] |
| -------------------------------------------------------------------------------------------------------------------------------- |
| from("direct:test"). |
| to("bean-validator://ValidationProviderResolverTest?validationProviderResolver=#myValidationProviderResolver"); |
| |
| ... |
| |
| <bean id="myValidationProviderResolver" class="org.apache.camel.component.bean.validator.HibernateValidationProviderResolver"/> |
| -------------------------------------------------------------------------------------------------------------------------------- |
| |
| If no custom `ValidationProviderResolver` is defined and the validator |
| component has been deployed into the OSGi environment, |
| the `HibernateValidationProviderResolver` will be automatically used. |
| |
| == Example |
| |
| Assumed we have a java bean with the following annotations |
| |
| *Car.java* |
| |
| [source,java] |
| ----------------------------------------------------------- |
| public class Car { |
| |
| @NotNull |
| private String manufacturer; |
| |
| @NotNull |
| @Size(min = 5, max = 14, groups = OptionalChecks.class) |
| private String licensePlate; |
| |
| // getter and setter |
| } |
| ----------------------------------------------------------- |
| |
| and an interface definition for our custom validation group |
| |
| *OptionalChecks.java* |
| |
| [source,java] |
| --------------------------------- |
| public interface OptionalChecks { |
| } |
| --------------------------------- |
| |
| with the following Camel route, only the *@NotNull* constraints on the |
| attributes manufacturer and licensePlate will be validated (Camel uses |
| the default group `javax.validation.groups.Default`). |
| |
| [source,java] |
| ------------------------- |
| from("direct:start") |
| .to("bean-validator://x") |
| .to("mock:end") |
| ------------------------- |
| |
| If you want to check the constraints from the group `OptionalChecks`, |
| you have to define the route like this |
| |
| [source,java] |
| ---------------------------------------------- |
| from("direct:start") |
| .to("bean-validator://x?group=OptionalChecks") |
| .to("mock:end") |
| ---------------------------------------------- |
| |
| If you want to check the constraints from both groups, you have to |
| define a new interface first |
| |
| *AllChecks.java* |
| |
| [source,java] |
| ----------------------------------------------------- |
| @GroupSequence({Default.class, OptionalChecks.class}) |
| public interface AllChecks { |
| } |
| ----------------------------------------------------- |
| |
| and then your route definition should looks like this |
| |
| [source,java] |
| ----------------------------------------- |
| from("direct:start") |
| .to("bean-validator://x?group=AllChecks") |
| .to("mock:end") |
| ----------------------------------------- |
| |
| And if you have to provide your own message interpolator, traversable |
| resolver and constraint validator factory, you have to write a route |
| like this |
| |
| [source,java] |
| ------------------------------------------------------------------------------------------------------ |
| <bean id="myMessageInterpolator" class="my.ConstraintValidatorFactory" /> |
| <bean id="myTraversableResolver" class="my.TraversableResolver" /> |
| <bean id="myConstraintValidatorFactory" class="my.ConstraintValidatorFactory" /> |
| |
| from("direct:start") |
| .to("bean-validator://x?group=AllChecks&messageInterpolator=#myMessageInterpolator |
| &traversableResolver=#myTraversableResolver&constraintValidatorFactory=#myConstraintValidatorFactory") |
| .to("mock:end") |
| ------------------------------------------------------------------------------------------------------ |
| |
| It's also possible to describe your constraints as XML and not as Java |
| annotations. In this case, you have to provide the file |
| `META-INF/validation.xml` which could looks like this |
| |
| *validation.xml* |
| |
| [source,java] |
| ------------------------------------------------------------------------------------------------------------------------------ |
| <?xml version="1.0" encoding="UTF-8"?> |
| <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.engine.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> |
| </validation-config> |
| ------------------------------------------------------------------------------------------------------------------------------ |
| |
| and the `constraints-car.xml` file |
| |
| *constraints-car.xml* |
| |
| [source,java] |
| ---------------------------------------------------------------------------------------------------- |
| <?xml version="1.0" encoding="UTF-8"?> |
| <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.apache.camel.component.bean.validator</default-package> |
| |
| <bean class="CarWithoutAnnotations" ignore-annotations="true"> |
| <field name="manufacturer"> |
| <constraint annotation="javax.validation.constraints.NotNull" /> |
| </field> |
| |
| <field name="licensePlate"> |
| <constraint annotation="javax.validation.constraints.NotNull" /> |
| |
| <constraint annotation="javax.validation.constraints.Size"> |
| <groups> |
| <value>org.apache.camel.component.bean.validator.OptionalChecks</value> |
| </groups> |
| <element name="min">5</element> |
| <element name="max">14</element> |
| </constraint> |
| </field> |
| </bean> |
| </constraint-mappings> |
| ---------------------------------------------------------------------------------------------------- |
| |
| Here is the XML syntax for the example route definition where **OrderedChecks** can be https://github.com/apache/camel/blob/master/components/camel-bean-validator/src/test/java/org/apache/camel/component/bean/validator/OrderedChecks.java |
| |
| Note that the body should include an instance of a class to validate. |
| |
| [source,java] |
| ---------------------------------------------------------------------------------------------------- |
| |
| <beans xmlns="http://www.springframework.org/schema/beans" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xsi:schemaLocation=" |
| http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd |
| http://camel.apache.org/schema/spring http://camel.apache.org/schema/spring/camel-spring.xsd"> |
| |
| <camelContext id="camel" xmlns="http://camel.apache.org/schema/spring"> |
| <route> |
| <from uri="direct:start"/> |
| <to uri="bean-validator://x?group=org.apache.camel.component.bean.validator.OrderedChecks"/> |
| </route> |
| </camelContext> |
| </beans> |
| ---------------------------------------------------------------------------------------------------- |
| |
| |
| |