60.3. Configuring Bean Validation
60.3.1. JAX-WS Configuration
Overview
This section describes how to enable bean validation on a JAX-WS service endpoint, which is defined either in Blueprint XML or in Spring XML. The interceptors used to perform bean validation are common to both JAX-WS endpoints and JAX-RS 1.1 endpoints (JAX-RS 2.0 endpoints use different interceptor classes, however).
Namespaces
In the XML examples shown in this section, you must remember to map the
jaxws namespace prefix to the appropriate namespace, either for Blueprint or Spring, as shown in the following table:
| XML Language | Namespace |
|---|---|
| Blueprint | http://cxf.apache.org/blueprint/jaxws |
| Spring | http://cxf.apache.org/jaxws |
Bean validation feature
The simplest way to enable bean validation on a JAX-WS endpoint is to add the bean validation feature to the endpoint. The bean validation feature is implemented by the following class:
org.apache.cxf.validation.BeanValidationFeature- By adding an instance of this feature class to the JAX-WS endpoint (either through the Java API or through the
jaxws:featureschild element ofjaxws:endpointin XML), you can enable bean validation on the endpoint. This feature installs two interceptors: an In interceptor that validates incoming message data; and an Out interceptor that validates return values (where the interceptors are created with default configuration parameters).
Sample JAX-WS configuration with bean validation feature
The following XML example shows how to enable bean validation functionality in a JAX-WS endpoint, by adding the
commonValidationFeature bean to the endpoint as a JAX-WS feature:
<jaxws:endpoint xmlns:s="http://bookworld.com"
serviceName="s:BookWorld"
endpointName="s:BookWorldPort"
implementor="#bookWorldValidation"
address="/bwsoap">
<jaxws:features>
<ref bean="commonValidationFeature" />
</jaxws:features>
</jaxws:endpoint>
<bean id="bookWorldValidation" class="org.apache.cxf.systest.jaxrs.validation.spring.BookWorldImpl"/>
<bean id="commonValidationFeature" class="org.apache.cxf.validation.BeanValidationFeature">
<property name="provider" ref="beanValidationProvider"/>
</bean>
<bean id="beanValidationProvider" class="org.apache.cxf.validation.BeanValidationProvider">
<constructor-arg ref="validationProviderResolver"/>
</bean>
<bean id="validationProviderResolver" class="org.example.HibernateValidationProviderResolver"/>
For a sample implementation of the
HibernateValidationProviderResolver class, see the section called “Example HibernateValidationProviderResolver class”. It is only necessary to configure the beanValidationProvider in the context of an OSGi environment (Apache Karaf).
Note
Remember to map the
jaxws prefix to the appropriate XML namespace for either Blueprint or Spring, depending on the context.
Common bean validation 1.1 interceptors
If you want to have more fine-grained control over the configuration of the bean validation, you can install the interceptors individually, instead of using the bean validation feature. In place of the bean validation feature, you can configure one or both of the following interceptors:
org.apache.cxf.validation.BeanValidationInInterceptor- When installed in a JAX-WS (or JAX-RS 1.1) endpoint, validates resource method parameters against validation constraints. If validation fails, raises the
javax.validation.ConstraintViolationExceptionexception. To install this interceptor, add it to the endpoint through thejaxws:inInterceptorschild element in XML (or thejaxrs:inInterceptorschild element in XML). org.apache.cxf.validation.BeanValidationOutInterceptor- When installed in a JAX-WS (or JAX-RS 1.1) endpoint, validates response values against validation constraints. If validation fails, raises the
javax.validation.ConstraintViolationExceptionexception. To install this interceptor, add it to the endpoint through thejaxws:outInterceptorschild element in XML (or thejaxrs:outInterceptorschild element in XML).
Sample JAX-WS configuration with bean validation interceptors
The following XML example shows how to enable bean validation functionality in a JAX-WS endpoint, by explicitly adding the relevant In interceptor bean and Out interceptor bean to the endpoint:
<jaxws:endpoint xmlns:s="http://bookworld.com"
serviceName="s:BookWorld"
endpointName="s:BookWorldPort"
implementor="#bookWorldValidation"
address="/bwsoap">
<jaxws:inInterceptors>
<ref bean="validationInInterceptor" />
</jaxws:inInterceptors>
<jaxws:outInterceptors>
<ref bean="validationOutInterceptor" />
</jaxws:outInterceptors>
</jaxws:endpoint>
<bean id="bookWorldValidation" class="org.apache.cxf.systest.jaxrs.validation.spring.BookWorldImpl"/>
<bean id="validationInInterceptor" class="org.apache.cxf.validation.BeanValidationInInterceptor">
<property name="provider" ref="beanValidationProvider"/>
</bean>
<bean id="validationOutInterceptor" class="org.apache.cxf.validation.BeanValidationOutInterceptor">
<property name="provider" ref="beanValidationProvider"/>
</bean>
<bean id="beanValidationProvider" class="org.apache.cxf.validation.BeanValidationProvider">
<constructor-arg ref="validationProviderResolver"/>
</bean>
<bean id="validationProviderResolver" class="org.example.HibernateValidationProviderResolver"/>
For a sample implementation of the
HibernateValidationProviderResolver class, see the section called “Example HibernateValidationProviderResolver class”. It is only necessary to configure the beanValidationProvider in the context of an OSGi environment (Apache Karaf).
Configuring a BeanValidationProvider
The
org.apache.cxf.validation.BeanValidationProvider is a simple wrapper class that wraps the bean validation implementation (validation provider). By overriding the default BeanValidationProvider class, you can customize the implementation of bean validation. The BeanValidationProvider bean enables you to override one or more of the following provider classes:
javax.validation.ParameterNameProvider- Provides names for method and constructor parameters. Note that this class is needed, because the Java reflection API does not give you access to the names of method parameters or constructor parameters.
javax.validation.spi.ValidationProvider<T>- Provides an implementation of bean validation for the specified type,
T. By implementing your ownValidationProviderclass, you can define custom validation rules for your own classes. This mechanism effectively enables you to extend the bean validation framework. javax.validation.ValidationProviderResolver- Implements a mechanism for discovering
ValidationProviderclasses and returns a list of the discovered classes. The default resolver looks for aMETA-INF/services/javax.validation.spi.ValidationProviderfile on the classpath, which should contain a list ofValidationProviderclasses. javax.validation.ValidatorFactory- A factory that returns
javax.validation.Validatorinstances. org.apache.cxf.validation.ValidationConfiguration- A CXF wrapper class that enables you override more classes from the validation provider layer.
To customize the
BeanValidationProvider, pass a custom BeanValidationProvider instance to the constructor of the validation In interceptor and to the constructor of the validation Out interceptor. For example:
<bean id="validationProvider" class="org.apache.cxf.validation.BeanValidationProvider" />
<bean id="validationInInterceptor" class="org.apache.cxf.validation.BeanValidationInInterceptor">
<property name="provider" ref="validationProvider" />
</bean>
<bean id="validationOutInterceptor" class="org.apache.cxf.validation.BeanValidationOutInterceptor">
<property name="provider" ref="validationProvider" />
</bean>60.3.2. JAX-RS Configuration
Overview
This section describes how to enable bean validation on a JAX-RS service endpoint, which is defined either in Blueprint XML or in Spring XML. The interceptors used to perform bean validation are common to both JAX-WS endpoints and JAX-RS 1.1 endpoints (JAX-RS 2.0 endpoints use different interceptor classes, however).
Namespaces
In the XML examples shown in this section, you must remember to map the
jaxws namespace prefix to the appropriate namespace, either for Blueprint or Spring, as shown in the following table:
| XML Language | Namespace |
|---|---|
| Blueprint | http://cxf.apache.org/blueprint/jaxws |
| Spring | http://cxf.apache.org/jaxws |
Bean validation feature
The simplest way to enable bean validation on a JAX-RS endpoint is to add the bean validation feature to the endpoint. The bean validation feature is implemented by the following class:
org.apache.cxf.validation.BeanValidationFeature- By adding an instance of this feature class to the JAX-RS endpoint (either through the Java API or through the
jaxrs:featureschild element ofjaxrs:serverin XML), you can enable bean validation on the endpoint. This feature installs two interceptors: an In interceptor that validates incoming message data; and an Out interceptor that validates return values (where the interceptors are created with default configuration parameters).
Validation exception mapper
A JAX-RS endpoint also requires you to configure a validation exception mapper, which is responsible for mapping validation exceptions to HTTP error responses. The following class implements validation exception mapping for JAX-RS:
org.apache.cxf.jaxrs.validation.ValidationExceptionMapper- Implements validation exception mapping in accordance with the JAX-RS 2.0 specification: any input parameter validation violations are mapped to HTTP status code
400 Bad Request; and any return value validation violation (or internal validation violation) is mapped to HTTP status code500 Internal Server Error.
Sample JAX-RS configuration
The following XML example shows how to enable bean validation functionality in a JAX-RS endpoint, by adding the
commonValidationFeature bean as a JAX-RS feature and by adding the exceptionMapper bean as a JAX-RS provider:
<jaxrs:server address="/bwrest">
<jaxrs:serviceBeans>
<ref bean="bookWorldValidation"/>
</jaxrs:serviceBeans>
<jaxrs:providers>
<ref bean="exceptionMapper"/>
</jaxrs:providers>
<jaxrs:features>
<ref bean="commonValidationFeature" />
</jaxrs:features>
</jaxrs:server>
<bean id="bookWorldValidation" class="org.apache.cxf.systest.jaxrs.validation.spring.BookWorldImpl"/>
<beanid="exceptionMapper"class="org.apache.cxf.jaxrs.validation.ValidationExceptionMapper"/>
<bean id="commonValidationFeature" class="org.apache.cxf.validation.BeanValidationFeature">
<property name="provider" ref="beanValidationProvider"/>
</bean>
<bean id="beanValidationProvider" class="org.apache.cxf.validation.BeanValidationProvider">
<constructor-arg ref="validationProviderResolver"/>
</bean>
<bean id="validationProviderResolver" class="org.example.HibernateValidationProviderResolver"/>
For a sample implementation of the
HibernateValidationProviderResolver class, see the section called “Example HibernateValidationProviderResolver class”. It is only necessary to configure the beanValidationProvider in the context of an OSGi environment (Apache Karaf).
Note
Remember to map the
jaxrs prefix to the appropriate XML namespace for either Blueprint or Spring, depending on the context.
Common bean validation 1.1 interceptors
Instead of using the bean validation feature, you can optionally install bean validation interceptors to get more fine-grained control over the validation implementation. JAX-RS uses the same interceptors as JAX-WS for this purpose—see the section called “Common bean validation 1.1 interceptors”
Sample JAX-RS configuration with bean validation interceptors
The following XML example shows how to enable bean validation functionality in a JAX-RS endpoint, by explicitly adding the relevant In interceptor bean and Out interceptor bean to the server endpoint:
<jaxrs:server address="/">
<jaxrs:inInterceptors>
<ref bean="validationInInterceptor" />
</jaxrs:inInterceptors>
<jaxrs:outInterceptors>
<ref bean="validationOutInterceptor" />
</jaxrs:outInterceptors>
<jaxrs:serviceBeans>
...
</jaxrs:serviceBeans>
<jaxrs:providers>
<ref bean="exceptionMapper"/>
</jaxrs:providers>
</jaxrs:server>
<bean id="exceptionMapper" class="org.apache.cxf.jaxrs.validation.ValidationExceptionMapper"/>
<bean id="validationInInterceptor" class="org.apache.cxf.validation.BeanValidationInInterceptor">
<property name="provider" ref="beanValidationProvider" />
</bean>
<bean id="validationOutInterceptor" class="org.apache.cxf.validation.BeanValidationOutInterceptor">
<property name="provider" ref="beanValidationProvider" />
</bean>
<bean id="beanValidationProvider" class="org.apache.cxf.validation.BeanValidationProvider">
<constructor-arg ref="validationProviderResolver"/>
</bean>
<bean id="validationProviderResolver" class="org.example.HibernateValidationProviderResolver"/>
For a sample implementation of the
HibernateValidationProviderResolver class, see the section called “Example HibernateValidationProviderResolver class”. It is only necessary to configure the beanValidationProvider in the context of an OSGi environment (Apache Karaf).
Configuring a BeanValidationProvider
You can inject a custom
BeanValidationProvider instance into the validation interceptors, as described in the section called “Configuring a BeanValidationProvider”.
60.3.3. JAX-RS 2.0 Configuration
Overview
Unlike JAX-RS 1.1 (which shares common validation interceptors with JAX-WS), the JAX-RS 2.0 configuration relies on dedicated validation interceptor classes that are specific to JAX-RS 2.0.
Bean validation feature
For JAX-RS 2.0, there is a dedicated bean validation feature, which is implemented by the following class:
org.apache.cxf.validation.JAXRSBeanValidationFeature- By adding an instance of this feature class to the JAX-RS endpoint (either through the Java API or through the
jaxrs:featureschild element ofjaxrs:serverin XML), you can enable bean validation on a JAX-RS 2.0 server endpoint. This feature installs two interceptors: an In interceptor that validates incoming message data; and an Out interceptor that validates return values (where the interceptors are created with default configuration parameters).
Validation exception mapper
JAX-RS 2.0 uses the same validation exception mapper class as JAX-RS 1.x:
org.apache.cxf.jaxrs.validation.ValidationExceptionMapper- Implements validation exception mapping in accordance with the JAX-RS 2.0 specification: any input parameter validation violations are mapped to HTTP status code
400 Bad Request; and any return value validation violation (or internal validation violation) is mapped to HTTP status code500 Internal Server Error.
Bean validation invoker
If you configure the JAX-RS service with a non-default lifecycle policy (for example, using Spring lifecycle management), you should also register a
org.apache.cxf.jaxrs.validation.JAXRSBeanValidationInvoker instance—using the jaxrs:invoker element in the endpoint configuration—with the service endpoint, to ensure that bean validation is invoked correctly.
For more details about JAX-RS service lifecycle management, see the section called “Lifecycle management in Spring XML”.
Sample JAX-RS 2.0 configuration with bean validation feature
The following XML example shows how to enable bean validation functionality in a JAX-RS 2.0 endpoint, by adding the
jaxrsValidationFeature bean as a JAX-RS feature and by adding the exceptionMapper bean as a JAX-RS provider:
<jaxrs:server address="/">
<jaxrs:serviceBeans>
...
</jaxrs:serviceBeans>
<jaxrs:providers>
<ref bean="exceptionMapper"/>
</jaxrs:providers>
<jaxrs:features>
<ref bean="jaxrsValidationFeature" />
</jaxrs:features>
</jaxrs:server>
<bean id="exceptionMapper" class="org.apache.cxf.jaxrs.validation.ValidationExceptionMapper"/>
<bean id="jaxrsValidationFeature" class="org.apache.cxf.validation.JAXRSBeanValidationFeature">
<property name="provider" ref="beanValidationProvider"/>
</bean>
<bean id="beanValidationProvider" class="org.apache.cxf.validation.BeanValidationProvider">
<constructor-arg ref="validationProviderResolver"/>
</bean>
<bean id="validationProviderResolver" class="org.example.HibernateValidationProviderResolver"/>
For a sample implementation of the
HibernateValidationProviderResolver class, see the section called “Example HibernateValidationProviderResolver class”. It is only necessary to configure the beanValidationProvider in the context of an OSGi environment (Apache Karaf).
Note
Remember to map the
jaxrs prefix to the appropriate XML namespace for either Blueprint or Spring, depending on the context.
Common bean validation 1.1 interceptors
If you want to have more fine-grained control over the configuration of the bean validation, you can install the JAX-RS interceptors individually, instead of using the bean validation feature. Configure one or both of the following JAX-RS interceptors:
org.apache.cxf.validation.JAXRSBeanValidationInInterceptor- When installed in a JAX-RS 2.0 server endpoint, validates resource method parameters against validation constraints. If validation fails, raises the
javax.validation.ConstraintViolationExceptionexception. To install this interceptor, add it to the endpoint through thejaxrs:inInterceptorschild element in XML. org.apache.cxf.validation.JAXRSBeanValidationOutInterceptor- When installed in a JAX-RS 2.0 endpoint, validates response values against validation constraints. If validation fails, raises the
javax.validation.ConstraintViolationExceptionexception. To install this interceptor, add it to the endpoint through thejaxrs:inInterceptorschild element in XML.
Sample JAX-RS 2.0 configuration with bean validation interceptors
The following XML example shows how to enable bean validation functionality in a JAX-RS 2.0 endpoint, by explicitly adding the relevant In interceptor bean and Out interceptor bean to the server endpoint:
<jaxrs:server address="/">
<jaxrs:inInterceptors>
<ref bean="validationInInterceptor" />
</jaxrs:inInterceptors>
<jaxrs:outInterceptors>
<ref bean="validationOutInterceptor" />
</jaxrs:outInterceptors>
<jaxrs:serviceBeans>
...
</jaxrs:serviceBeans>
<jaxrs:providers>
<ref bean="exceptionMapper"/>
</jaxrs:providers>
</jaxrs:server>
<bean id="exceptionMapper" class="org.apache.cxf.jaxrs.validation.ValidationExceptionMapper"/>
<bean id="validationInInterceptor" class="org.apache.cxf.jaxrs.validation.JAXRSBeanValidationInInterceptor">
<property name="provider" ref="beanValidationProvider" />
</bean>
<bean id="validationOutInterceptor" class="org.apache.cxf.jaxrs.validation.JAXRSBeanValidationOutInterceptor">
<property name="provider" ref="beanValidationProvider" />
</bean>
<bean id="beanValidationProvider" class="org.apache.cxf.validation.BeanValidationProvider">
<constructor-arg ref="validationProviderResolver"/>
</bean>
<bean id="validationProviderResolver" class="org.example.HibernateValidationProviderResolver"/>
For a sample implementation of the
HibernateValidationProviderResolver class, see the section called “Example HibernateValidationProviderResolver class”. It is only necessary to configure the beanValidationProvider in the context of an OSGi environment (Apache Karaf).
Configuring a BeanValidationProvider
You can inject a custom
BeanValidationProvider instance into the validation interceptors, as described in the section called “Configuring a BeanValidationProvider”.
Configuring a JAXRSParameterNameProvider
The
org.apache.cxf.jaxrs.validation.JAXRSParameterNameProvider class is an implementation of the javax.validation.ParameterNameProvider interface, which can be used to provide the names for method and constructor parameters in the context of JAX-RS 2.0 endpoints.
