Repository: camel Updated Branches: refs/heads/master ab7aca061 -> 1d20e3314
Added camel-bean-validator docs to gitbook Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/1d20e331 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/1d20e331 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/1d20e331 Branch: refs/heads/master Commit: 1d20e33140826f1945ab579095635110b62ef95d Parents: ab7aca0 Author: Andrea Cosentino <[email protected]> Authored: Wed Jan 27 13:54:53 2016 +0100 Committer: Andrea Cosentino <[email protected]> Committed: Wed Jan 27 13:54:53 2016 +0100 ---------------------------------------------------------------------- .../src/main/docs/bean-validator.adoc | 250 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 251 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/1d20e331/components/camel-bean-validator/src/main/docs/bean-validator.adoc ---------------------------------------------------------------------- diff --git a/components/camel-bean-validator/src/main/docs/bean-validator.adoc b/components/camel-bean-validator/src/main/docs/bean-validator.adoc new file mode 100644 index 0000000..bd19b79 --- /dev/null +++ b/components/camel-bean-validator/src/main/docs/bean-validator.adoc @@ -0,0 +1,250 @@ +[[BeanValidator-BeanValidatorComponent]] +Bean Validator Component +~~~~~~~~~~~~~~~~~~~~~~~~ + +*Available as of Camel 2.3* + +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> +------------------------------------------------------------ + +[[BeanValidator-URIformat]] +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&... + +[[BeanValidator-URIOptions]] +URI Options +^^^^^^^^^^^ +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Option |Default |Description + +|`group` |`javax.validation.groups.Default` |The custom validation group to use. + +|`validationProviderResolver` |Depends on JSR303 jar provided. |Camel *2.13.0*: Reference to a custom +`javax.validation.ValidationProviderResolver` in the +link:registry.html[Registry]. + +|`messageInterpolator` |`org.hibernate.validator.engine.ResourceBundleMessageInterpolator` |Reference to a custom `javax.validation.MessageInterpolator` in the +link:registry.html[Registry]. + +|`traversableResolver` |`org.hibernate.validator.engine.resolver.DefaultTraversableResolver` |Reference to a custom `javax.validation.TraversableResolver` in the +link:registry.html[Registry]. + +|`constraintValidatorFactory` |`org.hibernate.validator.engine.ConstraintValidatorFactoryImpl` |Reference to a custom `javax.validation.ConstraintValidatorFactory` in +the link:registry.html[Registry]. +|======================================================================= + +[[BeanValidator-OSGideployment]] +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. Keep in mind that you can +use `HibernateValidationProviderResolver` starting from the Camel +2.13.0. + +*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. + +[[BeanValidator-Example]] +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> +---------------------------------------------------------------------------------------------------- + +[[BeanValidator-SeeAlso]] +See Also +^^^^^^^^ + +* link:configuring-camel.html[Configuring Camel] +* link:component.html[Component] +* link:endpoint.html[Endpoint] +* link:getting-started.html[Getting Started] + http://git-wip-us.apache.org/repos/asf/camel/blob/1d20e331/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 8f0cef5..7fced91 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -93,6 +93,7 @@ * [Base64](base64.adoc) * [BeanIO](beanio.adoc) * [Beanstalk](beanstalk.adoc) + * [Bean-validator](bean-validator.adoc) * [CDI](cdi.adoc) * [JMS](jms.adoc) * [Metrics](metrics.adoc)
