cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From build...@apache.org
Subject svn commit: r888854 - in /websites/production/cxf/content: cache/docs.pageCache docs/validationfeature.html
Date Mon, 02 Dec 2013 23:48:15 GMT
Author: buildbot
Date: Mon Dec  2 23:48:15 2013
New Revision: 888854

Log:
Production update by buildbot for cxf

Modified:
    websites/production/cxf/content/cache/docs.pageCache
    websites/production/cxf/content/docs/validationfeature.html

Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.

Modified: websites/production/cxf/content/docs/validationfeature.html
==============================================================================
--- websites/production/cxf/content/docs/validationfeature.html (original)
+++ websites/production/cxf/content/docs/validationfeature.html Mon Dec  2 23:48:15 2013
@@ -132,10 +132,30 @@ Apache CXF -- ValidationFeature
 <div id="ConfluenceContent"><p><span style="font-size:2em;font-weight:bold">
Bean Validation Feature </span></p>
 
 <div>
-<ul><li><a shape="rect" href="#ValidationFeature-Introduction">Introduction</a></li><li><a
shape="rect" href="#ValidationFeature-Dependencies">Dependencies</a></li><ul><li><a
shape="rect" href="#ValidationFeature-UsingHibernateValidatorasbeanvalidationprovider">Using
Hibernate Validator as bean validation provider</a></li><li><a shape="rect"
href="#ValidationFeature-UsingApacheBValasbeanvalidationprovider">Using Apache BVal as
bean validation provider</a></li></ul><li><a shape="rect" href="#ValidationFeature-BeanValidation1.1andJAXRS2.0integration">Bean
Validation 1.1 and JAX-RS 2.0 integration</a></li><ul><li><a shape="rect"
href="#ValidationFeature-ConfiguringBeanValidation1.1usingJAXRSServerFactoryBean">Configuring
Bean Validation 1.1 using JAXRSServerFactoryBean</a></li><li><a shape="rect"
href="#ValidationFeature-ConfiguringBeanValidation1.1usingSpringbeandefinitionsXML">Configuring
Bean Validation 1.1 using Spring bean definitions XML</a></li><li><a
shape="rect" href="#Validat
 ionFeature-ValidationExceptionsandHTTPstatuscodes">Validation Exceptions and HTTP status
codes</a></li></ul><li><a shape="rect" href="#ValidationFeature-Examples">Examples</a></li><ul><li><a
shape="rect" href="#ValidationFeature-Validatingsimpleinputparameters">Validating simple
input parameters</a></li><li><a shape="rect" href="#ValidationFeature-Validatingcomplexinputparameters">Validating
complex input parameters</a></li><li><a shape="rect" href="#ValidationFeature-Validatingreturnvalues%28nonResponse%29">Validating
return values (non-Response)</a></li><li><a shape="rect" href="#ValidationFeature-Validatingreturnvalues%28Response%29">Validating
return values (Response)</a></li></ul></ul></div>
+<ul><li><a shape="rect" href="#ValidationFeature-Introduction">Introduction</a></li><li><a
shape="rect" href="#ValidationFeature-Dependencies">Dependencies</a></li><ul><li><a
shape="rect" href="#ValidationFeature-UsingHibernateValidatorasbeanvalidationprovider">Using
Hibernate Validator as bean validation provider</a></li><li><a shape="rect"
href="#ValidationFeature-UsingApacheBValasbeanvalidationprovider">Using Apache BVal as
bean validation provider</a></li></ul><li><a shape="rect" href="#ValidationFeature-CommonBeanValidation1.1Interceptors">Common
Bean Validation 1.1 Interceptors</a></li><li><a shape="rect" href="#ValidationFeature-BeanValidation1.1andJAXRS2.0integration">Bean
Validation 1.1 and JAX-RS 2.0 integration</a></li><ul><li><a shape="rect"
href="#ValidationFeature-ConfiguringBeanValidation1.1usingJAXRSServerFactoryBean">Configuring
Bean Validation 1.1 using JAXRSServerFactoryBean</a></li><li><a shape="rect"
href="#ValidationFeature-ConfiguringBeanValidation1.1usingSpri
 ngbeandefinitionsXML">Configuring Bean Validation 1.1 using Spring bean definitions XML</a></li><li><a
shape="rect" href="#ValidationFeature-ValidationExceptionsandHTTPstatuscodes">Validation
Exceptions and HTTP status codes</a></li><li><a shape="rect" href="#ValidationFeature-Examples">Examples</a></li><ul><li><a
shape="rect" href="#ValidationFeature-Validatingsimpleinputparameters">Validating simple
input parameters</a></li><li><a shape="rect" href="#ValidationFeature-Validatingcomplexinputparameters">Validating
complex input parameters</a></li><li><a shape="rect" href="#ValidationFeature-Validatingreturnvalues%28nonResponse%29">Validating
return values (non-Response)</a></li><li><a shape="rect" href="#ValidationFeature-Validatingreturnvalues%28Response%29">Validating
return values (Response)</a></li></ul></ul></ul></div>
 
 <h1><a shape="rect" name="ValidationFeature-Introduction"></a>Introduction</h1>
-<p>Among many other features, JAX-RS 2.0 specification introduces Bean Validation 1.1
support as a mandatory part of implementation. In an effort to fulfill this requirement, Apache
CXF provides full-fledge validation support for JAX-RS / JAX-WS endpoints, both for request
parameters and response values.</p>
+
+<p>Bean Validation 1.1 (JSR-349), an evolution of Bean Validation 1.0 (JSR-303), introduces
a very powerful concepts of declarative constraints (based on Java annotations) to define
the expectation for:</p>
+<ul class="alternate" type="square"><li>properties of JavaBeans</li><li>method
/ contructor parameters</li><li>method return values</li></ul>
+
+
+<p>Here are couple of typical examples:</p>
+<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
+<script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
+public class Person {
+    @NotNull private String firstName;
+    @NotNull private String lastName;
+    @Valid @NotNull private Person boss;
+
+    public @NotNull String saveItem( @Valid @NotNull Person person, @Max( 23 ) BigDecimal
age ) {
+        // ...
+    }
+}
+]]></script>
+</div></div>
+
+<p>Bean Validation API has been part of JPA 2.0 (JSR-317) and has proven to be successful
and very useful, helping developers to delegate routine validation tasks to solid, very extensible
framework. It is very easy to create own constraints, including complex cross-field ones.</p>
 
 <h1><a shape="rect" name="ValidationFeature-Dependencies"></a>Dependencies</h1>
 <p>Bean Validation support in Apache CXF is implementation-independent and is built
solely using API. As such, the only required dependency is:</p>
@@ -191,8 +211,18 @@ Apache CXF -- ValidationFeature
 </pre>
 </div></div>
 
+<h1><a shape="rect" name="ValidationFeature-CommonBeanValidation1.1Interceptors"></a>Common
Bean Validation 1.1 Interceptors</h1>
+
+<p>Generic Bean Validation 1.1 implementation is build around two interceptors and
validation provider:</p>
+<ul class="alternate" type="square"><li>org.apache.cxf.validation.BeanValidationInInterceptor:
validates every input message (request) arguments against validation constraints, raises org.apache.cxf.validation.ConstraintViolationException
if any violations are encountered</li><li>org.apache.cxf.validation.BeanValidationOutInterceptor:
validates every output message (response) arguments against validation constraints, raises
org.apache.cxf.validation.ResponseConstraintViolationException if any violations are encountered</li><li>org.apache.cxf.validation.BeanValidationProvider:
abstracts away Bean Validation 1.1 implementation and provides useful utility methods</li></ul>
+
+
+<p>Feature-specific implementation for JAX-RS / JAX-WS is built on top of these common
blocks.</p>
+
 <h1><a shape="rect" name="ValidationFeature-BeanValidation1.1andJAXRS2.0integration"></a>Bean
Validation 1.1 and JAX-RS 2.0 integration</h1>
 
+<p>Among many other features, JAX-RS 2.0 specification introduces Bean Validation 1.1
support as a mandatory part of implementation. In an effort to fulfill this requirement, Apache
CXF provides full-fledge validation support for JAX-RS / JAX-WS endpoints, both for request
parameters and response values.</p>
+
 <p>Bean Validation 1.1 support in JAX-RS 2.0 is built on top of three main components:</p>
 <ul class="alternate" type="square"><li>in-interceptor (org.apache.cxf.jaxrs.validation.JAXRSBeanValidationInInterceptor):
validates REST/WS endpoint parameters before invoking the method</li><li>out-interceptor
(org.apache.cxf.jaxrs.validation.JAXRSBeanValidationOutInterceptor): validates REST/WS endpoint
return value after the method invocation</li><li>exception mapper (org.apache.cxf.jaxrs.validation.ValidationExceptionMapper):
transforms any ValidationException to corresponding HTTP status code</li></ul>
 
@@ -255,11 +285,11 @@ sf.create();
 <p>As per JAX-RS 2.0 specification, any input parameter validation violation is 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. This is essentially
what org.apache.cxf.jaxrs.validation.ValidationExceptionMapper does.</p>
 <div class="panelMacro"><table class="noteMacro"><colgroup span="1"><col
span="1" width="24"><col span="1"></colgroup><tr><td colspan="1" rowspan="1"
valign="top"><img align="middle" src="https://cwiki.apache.org/confluence/images/icons/emoticons/warning.gif"
width="16" height="16" alt="" border="0"></td><td colspan="1" rowspan="1">At
the moment, the details of validation exceptions are not included into the response. The reason
why is that error reporting logic is application-specific and may vary from application to
application (f.e. it could be simple 'text/html' with error message, or 'application/json',
or HTTP custom headers, ...). Application developers are encouraged to provide own implementation
of this particular functionality.</td></tr></table></div>
 
-<h1><a shape="rect" name="ValidationFeature-Examples"></a>Examples</h1>
+<h2><a shape="rect" name="ValidationFeature-Examples"></a>Examples</h2>
 
 <p>You can use any predefined validation annotation as well as define your own as far
as it follows Bean Validation 1.1 specification. This section includes couple of typical scenarios.</p>
 
-<h2><a shape="rect" name="ValidationFeature-Validatingsimpleinputparameters"></a>Validating
simple input parameters</h2>
+<h3><a shape="rect" name="ValidationFeature-Validatingsimpleinputparameters"></a>Validating
simple input parameters</h3>
 
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
 <script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
@@ -273,7 +303,7 @@ public Response addBook(
 ]]></script>
 </div></div>
 
-<h2><a shape="rect" name="ValidationFeature-Validatingcomplexinputparameters"></a>Validating
complex input parameters</h2>
+<h3><a shape="rect" name="ValidationFeature-Validatingcomplexinputparameters"></a>Validating
complex input parameters</h3>
 
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
 <script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
@@ -297,7 +327,7 @@ public class Book {
 ]]></script>
 </div></div>
 
-<h2><a shape="rect" name="ValidationFeature-Validatingreturnvalues%28nonResponse%29"></a>Validating
return values (non-Response)</h2>
+<h3><a shape="rect" name="ValidationFeature-Validatingreturnvalues%28nonResponse%29"></a>Validating
return values (non-Response)</h3>
 
 <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
 <script class="theme: Default; brush: java; gutter: false" type="syntaxhighlighter"><![CDATA[
@@ -313,7 +343,7 @@ public Book getBook(@PathParam("bookId")
 
 <p>This example assumes that class Book has validation constraints defined (as in example
above).</p>
 
-<h2><a shape="rect" name="ValidationFeature-Validatingreturnvalues%28Response%29"></a>Validating
return values (Response)</h2>
+<h3><a shape="rect" name="ValidationFeature-Validatingreturnvalues%28Response%29"></a>Validating
return values (Response)</h3>
 
 <p>Returning Response object stands aside from all other usage scenarios. Usually,
Response is a holder for another object (entity) but because Response has no validation constraints
defined, the inner object (entity) is not validatable even if it has full set of validation
constraints . Unfortunately, this particular use case is not described in JAX-RS 2.0 specification.
Nevertheless, Apache CXF team thinks that such a validation would be beneficial and performs
a simple trick: whenever Response is being returned, all defined for it validation constraints
will be applied not to Response instance itself but to the entity it holds.</p>
 



Mime
View raw message