59.3. Configuring Bean Validation

59.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 LanguageNamespace
Blueprinthttp://cxf.apache.org/blueprint/jaxws
Springhttp://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:features child element of jaxws:endpoint in 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.ConstraintViolationException exception. To install this interceptor, add it to the endpoint through the jaxws:inInterceptors child element in XML (or the jaxrs:inInterceptors child 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.ConstraintViolationException exception. To install this interceptor, add it to the endpoint through the jaxws:outInterceptors child element in XML (or the jaxrs:outInterceptors child 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 own ValidationProvider class, 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 ValidationProvider classes and returns a list of the discovered classes. The default resolver looks for a META-INF/services/javax.validation.spi.ValidationProvider file on the classpath, which should contain a list of ValidationProvider classes.
javax.validation.ValidatorFactory
A factory that returns javax.validation.Validator instances.
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>

59.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 LanguageNamespace
Blueprinthttp://cxf.apache.org/blueprint/jaxws
Springhttp://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:features child element of jaxrs:server in 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 code 500 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”.

59.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:features child element of jaxrs:server in 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 code 500 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.ConstraintViolationException exception. To install this interceptor, add it to the endpoint through the jaxrs:inInterceptors child 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.ConstraintViolationException exception. To install this interceptor, add it to the endpoint through the jaxrs:inInterceptors child 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.