Author: buildbot
Date: Tue Nov 8 16:47:37 2016
New Revision: 1000755
Log:
Production update by buildbot for cxf
Modified:
websites/production/cxf/content/cache/docs.pageCache
websites/production/cxf/content/docs/jaxrs-services-description.html
Modified: websites/production/cxf/content/cache/docs.pageCache
==============================================================================
Binary files - no diff available.
Modified: websites/production/cxf/content/docs/jaxrs-services-description.html
==============================================================================
--- websites/production/cxf/content/docs/jaxrs-services-description.html
(original)
+++ websites/production/cxf/content/docs/jaxrs-services-description.html Tue
Nov 8 16:47:37 2016
@@ -118,12 +118,15 @@ Apache CXF -- JAXRS Services Description
<!-- Content -->
<div class="wiki-content">
<div
id="ConfluenceContent"><p> </p><p> </p><p> </p><p> <span
class="inline-first-p" style="font-size:2em;font-weight:bold">JAX-RS Services
Description</span> </p><p> </p><p> </p><p> </p><p><style
type="text/css">/*<![CDATA[*/
-div.rbtoc1444312020284 {padding: 0px;}
-div.rbtoc1444312020284 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1444312020284 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1478623622087 {padding: 0px;}
+div.rbtoc1478623622087 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1478623622087 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1444312020284">
-<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSServicesDescription-WADLoverview">WADL overview</a>
+/*]]>*/</style></p><div class="toc-macro rbtoc1478623622087">
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSServicesDescription-Swagger">Swagger</a>
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSServicesDescription-Swagger-FirstDevelopment">Swagger-First
Development</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-SwaggerAutoGeneration">Swagger Auto
Generation</a></li></ul>
+</li><li><a shape="rect" href="#JAXRSServicesDescription-WADL">WADL</a>
+<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSServicesDescription-Overview">Overview</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSServicesDescription-Basicexample">Basic example</a></li><li><a
shape="rect" href="#JAXRSServicesDescription-WADLwithreferences">WADL with
references</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-SharingdeclarationsbetweenmultipleWADLs">Sharing
declarations between multiple WADLs</a></li></ul>
</li><li><a shape="rect"
href="#JAXRSServicesDescription-WADL-firstDevelopment">WADL-first
Development</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSServicesDescription-wadl2javacommandlinetool">wadl2java command
line tool</a>
@@ -135,8 +138,9 @@ div.rbtoc1444312020284 li {margin-left:
</li><li><a shape="rect"
href="#JAXRSServicesDescription-CustomizingWADLGeneration">Customizing WADL
Generation</a>
<ul class="toc-indentation"><li><a shape="rect"
href="#JAXRSServicesDescription-RepresentingexplicitJAXBcollections">Representing
explicit JAXB collections</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-RepresentingexternalschemasandnonJAXBtypes">Representing
external schemas and non JAXB types</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-Changingthebaseaddress">Changing the base
address</a></li></ul>
</li></ul>
-</li><li><a shape="rect"
href="#JAXRSServicesDescription-java2wadlMavenplugin">java2wadl Maven
plugin</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-WADLTransformations">WADL
Transformations</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-ServicelistingsandWADLqueries">Service listings
and WADL queries</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-WADLinJSONformat">WADL in JSON
format</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-HidinglinkstoJAXRSendpointsfromtheservicespage">Hiding
links to JAXRS endpoints from the services page</a></li></ul>
-</div><p>CXF JAX-RS supports (Web Application Description
Language|http://www.w3.org/Submission/wadl] (WADL). <br clear="none"> Users can
use WADL documents to generate the initial code and have WADL auto-generated on
demand.</p><h1 id="JAXRSServicesDescription-WADLoverview">WADL
overview</h1><p>WADL is a resource-centric description language which has been
designed to facilitate the modeling, description and testing of<br
clear="none"> RESTful Web applications. Please check the official <a
shape="rect" class="external-link" href="http://www.w3.org/Submission/wadl/";
rel="nofollow">page</a> for more information, this section provides a brief
overview of main WADL constructs.</p><h2
id="JAXRSServicesDescription-Basicexample">Basic example</h2><p>A top level
WADL document element is called "application". Usually it may contain a
"grammars" section and "resources" element with one or more top-level
"resource" elements, with each one representing a specific root resource, for
example:</p
><div class="code panel pdl" style="border-width: 1px;"><div
>class="codeContent panelContent pdl">
+</li><li><a shape="rect"
href="#JAXRSServicesDescription-java2wadlMavenplugin">java2wadl Maven
plugin</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-WADLTransformations">WADL
Transformations</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-ServicelistingsandWADLqueries">Service listings
and WADL queries</a></li><li><a shape="rect"
href="#JAXRSServicesDescription-WADLinJSONformat">WADL in JSON
format</a></li></ul>
+</li><li><a shape="rect"
href="#JAXRSServicesDescription-HidinglinkstoJAXRSendpointsfromtheservicespage">Hiding
links to JAXRS endpoints from the services page</a></li></ul>
+</div><h1 id="JAXRSServicesDescription-Swagger">Swagger</h1><h2
id="JAXRSServicesDescription-Swagger-FirstDevelopment">Swagger-First
Development</h2><h2 id="JAXRSServicesDescription-SwaggerAutoGeneration">Swagger
Auto Generation</h2><p>Please see the <a shape="rect"
href="http://cxf.apache.org/docs/swagger2feature.html";>Swagger2Feature page</a>
for more information</p><h1
id="JAXRSServicesDescription-WADL">WADL</h1><p> </p><p>CXF JAX-RS supports
(Web Application Description Language|http://www.w3.org/Submission/wadl]
(WADL). <br clear="none"> Users can use WADL documents to generate the initial
code and have WADL auto-generated on demand.</p><h2
id="JAXRSServicesDescription-Overview">Overview</h2><p>WADL is a
resource-centric description language which has been designed to facilitate the
modeling, description and testing of<br clear="none"> RESTful Web applications.
Please check the official <a shape="rect" class="external-link"
href="http://www.w3.org/Submission/wadl/"; rel="no
follow">page</a> for more information, this section provides a brief overview
of main WADL constructs.</p><h3
id="JAXRSServicesDescription-Basicexample">Basic example</h3><p>A top level
WADL document element is called "application". Usually it may contain a
"grammars" section and "resources" element with one or more top-level
"resource" elements, with each one representing a specific root resource, for
example:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><application
xmlns="http://wadl.dev.java.net/2009/02"; xmlns:ns="http://superbooks">
<grammars>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema";
@@ -173,7 +177,7 @@ div.rbtoc1444312020284 li {margin-left:
</resources>
</application>
</pre>
-</div></div><p>This document describes an application that has
"http://localhost:8080/"; base URI. It can handle GET requests such as<br
clear="none"> "http://localhost:8080/bookstore/1";,
"http://localhost:8080/bookstore/123";, etc. Additionally it can handle similar
GET requests at<br clear="none"> "http://localhost:8080/books/bookstore/1";,
"http://localhost:8080/books/bookstore/123";, etc, note an extra "books" path
segment.</p><p>"application/xml" media type is supported and response
representation elements link to "{<a shape="rect" class="external-link"
href="http://superbooks"; rel="nofollow">http://superbooks</a>}thebook" element
declared in a schema inlined in the grammars section.</p><p>Note that
"resources" element has two child "resource" elements, one with
"/bookstore/{id}" path, another one with "/books" path.</p><p>These 2 resources
can be represented as JAX-RS root resources. For example, these resources can
be mapped to concrete Java classes such as BookStoreRootResource
with @Path("/bookstore/{id}") and BooksResource with @Path("/books").
BookStoreRootResource root resource will have a single @GET resource method
with no @Path, presumably returning Book (JAXB) bean. The second BooksResource
root resource will have a single subresource locator with
@Path("/bookstore/{id}") which will return a subresource with a single @GET
resource method.</p><p>This is just one possible interpretation of how the
above WADL description can be mapped to JAX-RS resources and
methods.</p><p>Also note that the resource with the "/books" path has another
child resource with the "/bookstore/{id}" path, but it could've had a
"/books/bookstore/{id}" path instead and no child resource.</p><h2
id="JAXRSServicesDescription-WADLwithreferences">WADL with
references</h2><p>Basic WADL example in the previous section shows a "grammars"
section with the inlined schema, as well as a "resource" description with the
"/bookstore/{id}" path listed twice, as an immediate child of the "res
ources" and as a child of the "resource" element with the "/books"
path.</p><p>Note that inlined schemas can be included instead by referencing
external schemas. Likewise, most of WADL element declarations such as
"resource", "method", "representation", etc can be shared by using the same
document or external references. Here is how the basic example can be
simplified with the help of references:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>This document describes an application that has
"http://localhost:8080/"; base URI. It can handle GET requests such as<br
clear="none"> "http://localhost:8080/bookstore/1";,
"http://localhost:8080/bookstore/123";, etc. Additionally it can handle similar
GET requests at<br clear="none"> "http://localhost:8080/books/bookstore/1";,
"http://localhost:8080/books/bookstore/123";, etc, note an extra "books" path
segment.</p><p>"application/xml" media type is supported and response
representation elements link to "{<a shape="rect" class="external-link"
href="http://superbooks"; rel="nofollow">http://superbooks</a>}thebook" element
declared in a schema inlined in the grammars section.</p><p>Note that
"resources" element has two child "resource" elements, one with
"/bookstore/{id}" path, another one with "/books" path.</p><p>These 2 resources
can be represented as JAX-RS root resources. For example, these resources can
be mapped to concrete Java classes such as BookStoreRootResource
with @Path("/bookstore/{id}") and BooksResource with @Path("/books").
BookStoreRootResource root resource will have a single @GET resource method
with no @Path, presumably returning Book (JAXB) bean. The second BooksResource
root resource will have a single subresource locator with
@Path("/bookstore/{id}") which will return a subresource with a single @GET
resource method.</p><p>This is just one possible interpretation of how the
above WADL description can be mapped to JAX-RS resources and
methods.</p><p>Also note that the resource with the "/books" path has another
child resource with the "/bookstore/{id}" path, but it could've had a
"/books/bookstore/{id}" path instead and no child resource.</p><h3
id="JAXRSServicesDescription-WADLwithreferences">WADL with
references</h3><p>Basic WADL example in the previous section shows a "grammars"
section with the inlined schema, as well as a "resource" description with the
"/bookstore/{id}" path listed twice, as an immediate child of the "res
ources" and as a child of the "resource" element with the "/books"
path.</p><p>Note that inlined schemas can be included instead by referencing
external schemas. Likewise, most of WADL element declarations such as
"resource", "method", "representation", etc can be shared by using the same
document or external references. Here is how the basic example can be
simplified with the help of references:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><application
xmlns="http://wadl.dev.java.net/2009/02"; xmlns:ns="http://superbooks">
<grammars>
<include href="schemas/book.xsd"/>
@@ -201,7 +205,7 @@ div.rbtoc1444312020284 li {margin-left:
</resources>
</application>
</pre>
-</div></div><p>Note that a book.xsd schema resource located in the 'schemas'
path relative to the location of this WADL document is referenced using
wadl:include element. Abstract resource type "bookResource" is declared as an
immediate child of wadl:application and is linked to concrete resource elements
using a "#bookResource" reference.</p><h2
id="JAXRSServicesDescription-SharingdeclarationsbetweenmultipleWADLs">Sharing
declarations between multiple WADLs</h2><p>WADL references allow for having
WADL documents with abstract declarations only and concrete WADLs referencing
them, thus making it possible to reuse resource declarations in different web
application descriptions.</p><p>For example, the following baseApplication.wadl
documents describes an abstract "bookResource" resource:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Note that a book.xsd schema resource located in the 'schemas'
path relative to the location of this WADL document is referenced using
wadl:include element. Abstract resource type "bookResource" is declared as an
immediate child of wadl:application and is linked to concrete resource elements
using a "#bookResource" reference.</p><h3
id="JAXRSServicesDescription-SharingdeclarationsbetweenmultipleWADLs">Sharing
declarations between multiple WADLs</h3><p>WADL references allow for having
WADL documents with abstract declarations only and concrete WADLs referencing
them, thus making it possible to reuse resource declarations in different web
application descriptions.</p><p>For example, the following baseApplication.wadl
documents describes an abstract "bookResource" resource:</p><div class="code
panel pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><application
xmlns="http://wadl.dev.java.net/2009/02"; xmlns:ns="http://superbooks">
<grammars>
<include href="schemas/book.xsd"/>
@@ -228,7 +232,7 @@ div.rbtoc1444312020284 li {margin-left:
</resources>
</application>
</pre>
-</div></div><p><strong>New</strong>: Starting from CXF 2.5.0 and 2.4.4 all
WADL elements may link to top-level local declarations, see this <a
shape="rect" class="external-link"
href="http://www.w3.org/Submission/wadl/#x3-36000A.2";
rel="nofollow">example</a>.</p><h1
id="JAXRSServicesDescription-WADL-firstDevelopment">WADL-first
Development</h1><p>CXF 2.4.1 introduces a wadl2java code generator and
cxf-wadl2java-plugin Maven plugin which can be used to generate server and
client JAX-RS code and speed up the transition between modeling and
implementation stages.</p><p><strong>Note</strong> If you are looking for a
wadl2java code generator from a Java.net project started by Marc Hadley then
please follow this <a shape="rect" class="external-link"
href="http://wadl.java.net/wadl2java.html"; rel="nofollow">link</a>.</p><p>Code
generator expects WADL resource and method elements to have "id" attributes set
which can provide hints on how to name generated classes and methods. For
example:</
p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div></div><p><strong>New</strong>: Starting from CXF 2.5.0 and 2.4.4 all
WADL elements may link to top-level local declarations, see this <a
shape="rect" class="external-link"
href="http://www.w3.org/Submission/wadl/#x3-36000A.2";
rel="nofollow">example</a>.</p><h2
id="JAXRSServicesDescription-WADL-firstDevelopment">WADL-first
Development</h2><p>CXF 2.4.1 introduces a wadl2java code generator and
cxf-wadl2java-plugin Maven plugin which can be used to generate server and
client JAX-RS code and speed up the transition between modeling and
implementation stages.</p><p><strong>Note</strong> If you are looking for a
wadl2java code generator from a Java.net project started by Marc Hadley then
please follow this <a shape="rect" class="external-link"
href="http://wadl.java.net/wadl2java.html"; rel="nofollow">link</a>.</p><p>Code
generator expects WADL resource and method elements to have "id" attributes set
which can provide hints on how to name generated classes and methods. For
example:</
p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><application
xmlns="http://wadl.dev.java.net/2009/02"; xmlns:ns="http://superbooks">
<grammars>
<include href="schemas/book.xsd"/>
@@ -245,7 +249,7 @@ div.rbtoc1444312020284 li {margin-left:
</resources>
</application>
</pre>
-</div></div><p>Note that resource id is
"org.apache.cxf.jaxrs.systest.BookStore". Alternatively, expanded QName can be
used as "id":<br clear="none"> "{<a shape="rect" class="external-link"
href="http://systest.jaxrs.cxf.apache.org";>http://systest.jaxrs.cxf.apache.org</a>}BookStore".</p><p>Simple
WADL documents containing a single resource only do not have to have "id"
attributes set. In such cases a wadltojava "resource" and "-p" options can be
used to specify a full root resource class name corresponding to a single WADL
resource element, and if neither of these options is set then this single WADL
resource will get an "application.Resource" root resource class
generated.</p><p>Note that the code generation from the WADL documents
containing multiple root resources with no "id" attributes is supported
starting from CXF 2.5.0.</p><p>If WADL "method" element has no "id" attribute
set then a combination of the element's "name" attribute and the current path
will be used to name gener
ated class methods, example: "getbookid", where the method name is "GET", and
the path is "/book/{id}".</p><p>Classes generated from schemas will have a
package name derived from a given schema target namespace by default.
wadltojava tool lets customize it as well.</p><h2
id="JAXRSServicesDescription-wadl2javacommandlinetool">wadl2java command line
tool</h2><p>Running wadltojava from the command line will produce:</p><div
class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
+</div></div><p>Note that resource id is
"org.apache.cxf.jaxrs.systest.BookStore". Alternatively, expanded QName can be
used as "id":<br clear="none"> "{<a shape="rect" class="external-link"
href="http://systest.jaxrs.cxf.apache.org";>http://systest.jaxrs.cxf.apache.org</a>}BookStore".</p><p>Simple
WADL documents containing a single resource only do not have to have "id"
attributes set. In such cases a wadltojava "resource" and "-p" options can be
used to specify a full root resource class name corresponding to a single WADL
resource element, and if neither of these options is set then this single WADL
resource will get an "application.Resource" root resource class
generated.</p><p>Note that the code generation from the WADL documents
containing multiple root resources with no "id" attributes is supported
starting from CXF 2.5.0.</p><p>If WADL "method" element has no "id" attribute
set then a combination of the element's "name" attribute and the current path
will be used to name gener
ated class methods, example: "getbookid", where the method name is "GET", and
the path is "/book/{id}".</p><p>Classes generated from schemas will have a
package name derived from a given schema target namespace by default.
wadltojava tool lets customize it as well.</p><h3
id="JAXRSServicesDescription-wadl2javacommandlinetool">wadl2java command line
tool</h3><p>Running wadltojava from the command line will produce:</p><div
class="preformatted panel" style="border-width: 1px;"><div
class="preformattedContent panelContent">
<pre>wadl2java -p <package-name> -sp <[schema-namespace
=]package-name>*
-tMap <schema-type = java-type>* -repMap <media-type =
java-type>*
-resource <resource-name> -b <binding-file-name>*
-catalog <catalog-file-name>
@@ -254,7 +258,7 @@ div.rbtoc1444312020284 li {margin-left:
-generateResponseIfHeadersSet
-generateResponseForMethods<methodNames>* -async<methodNames>*
-xjc<xjc-arguments>*
-validate -h -v -verbose -quiet <wadl>
</pre>
-</div></div><p>Note 'tMap', 'repMap', 'noTypes' and 'inheritResourceParams'
options are supported starting from CXF 2.6.3, 'noVoidForEmptyResponses' - from
2.6.4, '-async' - from 2.7.1, '-xjc' - from
2.7.4,</p><p>'generateResponseForMethods' and 'generateResponseIfHeadersSet' -
from 2.7.12/3.0.0, 'validate' - from 2.7.13/3.2.0/3.1.0, 'javaDocs' - from
3.1.4</p><p>The options are reviewed in the following table.</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Interpretation</p></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>-?</code>,<code>-h</code>,<code>-help</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Displays the online help for
this utility and exits.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-p PackageName</code></p></td><td colspan="1"
rowspan="1" class="conflu
enceTd"><p>Specifies the package name of root resource
classes</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-sp [ schema-namespace= ]
PackageName</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Specifies one or more package names corresponding to
individual schema namespaces</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-resource RootResourceName</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Specifies a full name of root
resource class if WADL contains a single resource</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>-interface</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Default option unless -impl option is used
- Java interfaces with JAX-RS annotations are generated</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>-impl</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Generates starting impl
ementation code. Can also be used with -interface option</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>-noTypes</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Requests that no schema generation is
needed. Can also be used with -tMap option</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>-tMap
schema-type=java-type</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Provides mapping between schema elements and java
types</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-repMap media-type=java-type</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Provides mapping between media
types and java types</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-b binding-name</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Specifies JAXB binding files. Use multiple
-b flags to specify multiple entries.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>-catalog
catalog-file-name</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Specifies catalog file to map referenced
wadl/schemas</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-d output-directory</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Specifies the directory into
which the generated code files are written.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>-compile</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Compiles generated Java
files.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-classdir compile-class-dir</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Specifies the directory into
which the compiled class files are written.</p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>-noVoidForEmptyResponses</code></p></td><td
colspan="1" row
span="1" class="confluenceTd"><p>Generate JAX-RS Response instead of 'void'
for methods with no response representations.</p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>-inheritResourceParams</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Get current resource-level path
or matrix parameters added to generated methods for all descendant
resources.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-generateEnums</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Generates Java enums for parameters with
options.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-supportMultipleXmlReps</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Generates separate method for
every XML representation in a single WADL request element.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">-javaDocs</td><td colspan="1"
rowspan="1" class="confluenceTd">Converts
WADL doc elements into JavaDocs</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">-generateResponseIfHeadersSet</td><td colspan="1"
rowspan="1" class="confluenceTd">Generates JAX-RS Response method response type
if  WADL response element for a given method has 'header'
parameters</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">-generateResponseForMethods methodNames</td><td
colspan="1" rowspan="1" class="confluenceTd">Generates JAX-RS Response method
response type, methodNames is a comma-separated list of WADL method name or id
attributes</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-async methodNames</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Adds JAX-RS 2.0 AsyncResponse parameter to
generated methods, methodNames is a comma-separated list of WADL method name or
id attributes</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-xjc<xjc args></code></p></td><td
colspan="1"
rowspan="1" class="confluenceTd"><p>Specifies a comma separated list of
arguments that are passed directly to the XJC processor, example
-xjc-Xts.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">-validate</td><td colspan="1" rowspan="1"
class="confluenceTd">Validate a WADL document against the WADL
schema</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><em>wadlurl</em></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The path and name of the WADL file to use in generating
the code.</p></td></tr></tbody></table></div><p>You must specify the absolute
or relative path to the WADL document as the last argument.<br clear="none">
OASIS catalog files can be used to help the tool resolve referenced WADL and
schema documents.</p><p>Note 'tMap' option can be used to map between schema
element references and java types and can be used to customize the default
schema to Java type mapping. For example, in order to override a default
parameter 'xs:dat
e' to java.util.Date mapping one can do '-tMap {<a shape="rect"
class="external-link" href="http://www.w3.org/2001/XMLSchema";
rel="nofollow">http://www.w3.org/2001/XMLSchema</a>}date=javax.xml.datatype.XMLGregorianCalendar'
- this can affect the "<wadl:param type='xs:date'>" declarations.<br
clear="none"> Alternatively, in combination with a '-noTypes' switch, this
option can be used to request that a custom Java type reference should be
generated. For example, if one prefers to use 'javax.xml.transform.Source' for
handling a given XML payload, one can do <br clear="none"> '-tMap {<a
shape="rect" class="external-link" href="http://book";
rel="nofollow">http://book</a>}Book=javax.xml.transform.Source', this will
affect "<wadl:representation element='ns:Book'>" declarations where 'ns'
prefix is bound to the 'http://book' namespace. Similarly, a schema reference
to Atom Feed element can be mapped to say Abdera Feed class.</p><p>The 'repMap'
option is similar and provides a m
apping between the representations of a given media type and Java type. For
example, if one has to process different XML representations in one method, a
mapping like '-repMap application/xml=javax.xml.transform.Source' will work,
affecting declarations like "<wadl:representation
mediaTpe='application/xml'". Similarly CXF
org.apache.cxf.jaxrs.ext.multipart.MultipartBody class can be linked to
'multipart/form-data' representations, etc.</p><p>The
'generateResponseForMethods' and 'async' options accept a comma separated list
of method names, providing a single '*' (no quotes) as a method name will get
these options affecting all of the generated methods.</p><p>In some cases,
example when describing JSON arrays, you may want to have an explicit
collection of types defined in schema generated. In this case use -tMap or
-repMap option with a value such as "List..MyType".</p><p> </p><h3
id="JAXRSServicesDescription-JAXBcustomizations">JAXB customizations</h3><p>At
the moment it is
possible to apply external JAXB customizations to WADL grammars however it is
not possible yet to restrict a given customization to a specific WADL document
or explicitly inlined schema. Linking binding to external schemas works, for
example, the following bindings file can be used:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Note 'tMap', 'repMap', 'noTypes' and 'inheritResourceParams'
options are supported starting from CXF 2.6.3, 'noVoidForEmptyResponses' - from
2.6.4, '-async' - from 2.7.1, '-xjc' - from
2.7.4,</p><p>'generateResponseForMethods' and 'generateResponseIfHeadersSet' -
from 2.7.12/3.0.0, 'validate' - from 2.7.13/3.2.0/3.1.0, 'javaDocs' - from
3.1.4</p><p>The options are reviewed in the following table.</p><div
class="table-wrap"><table class="confluenceTable"><tbody><tr><th colspan="1"
rowspan="1" class="confluenceTh"><p>Option</p></th><th colspan="1" rowspan="1"
class="confluenceTh"><p>Interpretation</p></th></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>-?</code>,<code>-h</code>,<code>-help</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Displays the online help for
this utility and exits.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-p PackageName</code></p></td><td colspan="1"
rowspan="1" class="conflu
enceTd"><p>Specifies the package name of root resource
classes</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-sp [ schema-namespace= ]
PackageName</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Specifies one or more package names corresponding to
individual schema namespaces</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-resource RootResourceName</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Specifies a full name of root
resource class if WADL contains a single resource</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>-interface</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Default option unless -impl option is used
- Java interfaces with JAX-RS annotations are generated</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>-impl</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Generates starting impl
ementation code. Can also be used with -interface option</p></td></tr><tr><td
colspan="1" rowspan="1"
class="confluenceTd"><p><code>-noTypes</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Requests that no schema generation is
needed. Can also be used with -tMap option</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>-tMap
schema-type=java-type</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Provides mapping between schema elements and java
types</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-repMap media-type=java-type</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Provides mapping between media
types and java types</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-b binding-name</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Specifies JAXB binding files. Use multiple
-b flags to specify multiple entries.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p><code>-catalog
catalog-file-name</code></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>Specifies catalog file to map referenced
wadl/schemas</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-d output-directory</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Specifies the directory into
which the generated code files are written.</p></td></tr><tr><td colspan="1"
rowspan="1" class="confluenceTd"><p><code>-compile</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Compiles generated Java
files.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-classdir compile-class-dir</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Specifies the directory into
which the compiled class files are written.</p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>-noVoidForEmptyResponses</code></p></td><td
colspan="1" row
span="1" class="confluenceTd"><p>Generate JAX-RS Response instead of 'void'
for methods with no response representations.</p></td></tr><tr><td colspan="1"
rowspan="1"
class="confluenceTd"><p><code>-inheritResourceParams</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Get current resource-level path
or matrix parameters added to generated methods for all descendant
resources.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-generateEnums</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Generates Java enums for parameters with
options.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-supportMultipleXmlReps</code></p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>Generates separate method for
every XML representation in a single WADL request element.</p></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd">-javaDocs</td><td colspan="1"
rowspan="1" class="confluenceTd">Converts
WADL doc elements into JavaDocs</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">-generateResponseIfHeadersSet</td><td colspan="1"
rowspan="1" class="confluenceTd">Generates JAX-RS Response method response type
if  WADL response element for a given method has 'header'
parameters</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">-generateResponseForMethods methodNames</td><td
colspan="1" rowspan="1" class="confluenceTd">Generates JAX-RS Response method
response type, methodNames is a comma-separated list of WADL method name or id
attributes</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-async methodNames</code></p></td><td colspan="1"
rowspan="1" class="confluenceTd"><p>Adds JAX-RS 2.0 AsyncResponse parameter to
generated methods, methodNames is a comma-separated list of WADL method name or
id attributes</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><code>-xjc<xjc args></code></p></td><td
colspan="1"
rowspan="1" class="confluenceTd"><p>Specifies a comma separated list of
arguments that are passed directly to the XJC processor, example
-xjc-Xts.</p></td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd">-validate</td><td colspan="1" rowspan="1"
class="confluenceTd">Validate a WADL document against the WADL
schema</td></tr><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p><em>wadlurl</em></p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>The path and name of the WADL file to use in generating
the code.</p></td></tr></tbody></table></div><p>You must specify the absolute
or relative path to the WADL document as the last argument.<br clear="none">
OASIS catalog files can be used to help the tool resolve referenced WADL and
schema documents.</p><p>Note 'tMap' option can be used to map between schema
element references and java types and can be used to customize the default
schema to Java type mapping. For example, in order to override a default
parameter 'xs:dat
e' to java.util.Date mapping one can do '-tMap {<a shape="rect"
class="external-link" href="http://www.w3.org/2001/XMLSchema";
rel="nofollow">http://www.w3.org/2001/XMLSchema</a>}date=javax.xml.datatype.XMLGregorianCalendar'
- this can affect the "<wadl:param type='xs:date'>" declarations.<br
clear="none"> Alternatively, in combination with a '-noTypes' switch, this
option can be used to request that a custom Java type reference should be
generated. For example, if one prefers to use 'javax.xml.transform.Source' for
handling a given XML payload, one can do <br clear="none"> '-tMap {<a
shape="rect" class="external-link" href="http://book";
rel="nofollow">http://book</a>}Book=javax.xml.transform.Source', this will
affect "<wadl:representation element='ns:Book'>" declarations where 'ns'
prefix is bound to the 'http://book' namespace. Similarly, a schema reference
to Atom Feed element can be mapped to say Abdera Feed class.</p><p>The 'repMap'
option is similar and provides a m
apping between the representations of a given media type and Java type. For
example, if one has to process different XML representations in one method, a
mapping like '-repMap application/xml=javax.xml.transform.Source' will work,
affecting declarations like "<wadl:representation
mediaTpe='application/xml'". Similarly CXF
org.apache.cxf.jaxrs.ext.multipart.MultipartBody class can be linked to
'multipart/form-data' representations, etc.</p><p>The
'generateResponseForMethods' and 'async' options accept a comma separated list
of method names, providing a single '*' (no quotes) as a method name will get
these options affecting all of the generated methods.</p><p>In some cases,
example when describing JSON arrays, you may want to have an explicit
collection of types defined in schema generated. In this case use -tMap or
-repMap option with a value such as "List..MyType".</p><p> </p><h4
id="JAXRSServicesDescription-JAXBcustomizations">JAXB customizations</h4><p>At
the moment it is
possible to apply external JAXB customizations to WADL grammars however it is
not possible yet to restrict a given customization to a specific WADL document
or explicitly inlined schema. Linking binding to external schemas works, for
example, the following bindings file can be used:</p><div class="code panel
pdl" style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><jaxb:bindings version="2.0"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb";
xmlns:xs="http://www.w3.org/2001/XMLSchema";
@@ -263,7 +267,7 @@ div.rbtoc1444312020284 li {margin-left:
<jaxb:property name="book2Id"/>
</jaxb:bindings>
</pre>
-</div></div><h2 id="JAXRSServicesDescription-wadl2javaMavenplugin">wadl2java
Maven plugin</h2><p>If you need the code generated during Maven build then the
following plugin can be used:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h3 id="JAXRSServicesDescription-wadl2javaMavenplugin">wadl2java
Maven plugin</h3><p>If you need the code generated during Maven build then the
following plugin can be used:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><groupId>org.apache.cxf</groupId>
<artifactId>cxf-wadl2java-plugin</artifactId>
<version>2.4.1</version>
@@ -314,26 +318,26 @@ div.rbtoc1444312020284 li {margin-left:
</wadlOption>
</wadlOptions>
</pre>
-</div></div><h2
id="JAXRSServicesDescription-Integration">Integration</h2><p>Two options are
available to developers who wish to integrate CXF JAX-RS WADLToJava code
generator.<br clear="none"> First option is to pass the collected options
directly to a wadltojava process.</p><p>Another approach is to use
org.apache.cxf.tools.wadlto.jaxrs.JAXRSContainer class shipped with the
cxf-tools-wadlto-jaxrs module:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><h3
id="JAXRSServicesDescription-Integration">Integration</h3><p>Two options are
available to developers who wish to integrate CXF JAX-RS WADLToJava code
generator.<br clear="none"> First option is to pass the collected options
directly to a wadltojava process.</p><p>Another approach is to use
org.apache.cxf.tools.wadlto.jaxrs.JAXRSContainer class shipped with the
cxf-tools-wadlto-jaxrs module:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><groupId>org.apache.cxf</groupId>
<artifactId>cxf-tools-wadlto-jaxrs</artifactId>
<version>2.4.1</version>
</pre>
-</div></div><p>Please see CXF source for more details and
org.apache.cxf.tools.wadlto.jaxrs.JAXRSContainerTest in particular.</p><h2
id="JAXRSServicesDescription-ExternalWADLdocumentsandJAXRSendpoints.">External
WADL documents and JAXRS endpoints.</h2><p>External WADL documents can be
linked to from jaxrs:server endpoints using newly introduced "docLocation"
attribute, for example:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Please see CXF source for more details and
org.apache.cxf.tools.wadlto.jaxrs.JAXRSContainerTest in particular.</p><h3
id="JAXRSServicesDescription-ExternalWADLdocumentsandJAXRSendpoints.">External
WADL documents and JAXRS endpoints.</h3><p>External WADL documents can be
linked to from jaxrs:server endpoints using newly introduced "docLocation"
attribute, for example:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><jaxrs:server address="/rest"
docLocation="wadl/bookStore.wadl">
<jaxrs:serviceBeans>
<bean class="org.bar.generated.BookStore"/>
</jaxrs:serviceBeans>
</jaxrs:server>
</pre>
-</div></div><p>If external WADL documents include external schemas and jaxrs
endpoints need to have the schema validation enabled, then those schemas can be
referenced in the jaxrs:schemaLocations section as well.</p><h1
id="JAXRSServicesDescription-WADLAutoGenerationatRuntime">WADL Auto Generation
at Runtime</h1><p>Note that in CXF 3.0.0 WADL Generator code has been moved
to</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div></div><p>If external WADL documents include external schemas and jaxrs
endpoints need to have the schema validation enabled, then those schemas can be
referenced in the jaxrs:schemaLocations section as well.</p><h2
id="JAXRSServicesDescription-WADLAutoGenerationatRuntime">WADL Auto Generation
at Runtime</h2><p>Note that in CXF 3.0.0 WADL Generator code has been moved
to</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><dependency>
<groupId>org.apache.cxf</groupId>
<artifactId>cxf-rt-rs-service-description</artifactId>
<version>3.0.0-milestone1</version>
</dependency>
</pre>
-</div></div><p>CXF JAX-RS supports the auto-generation of WADL for JAX-RS
endpoints. <br clear="none"> Note that JAX-RS subresources are late-resolved by
default, so using annotated interfaces for subresources and a
staticSubresourceResolution=true property will let the whole resource
tree/graph be described in a generated instance. Schemas will be generated for
JAXB-annotated types. See below for the information on how to get
auto-generated WADL instances reference existing schemas.</p><p><strong>CXF
2.4.0</strong>: org.apache.cxf.jaxrs.ext.Description and
org.apache.cxf.jaxrs.ext.xml.XMLName have been moved to
org.apache.cxf.jaxrs.model.wadl package given that their purpose is to improve
the WADL generation. Also, org.apache.cxf.jaxrs.model.wadl.WadlElement has been
renamed to 'ElementClass'.</p><h2
id="JAXRSServicesDescription-DocumentingresourceclassesandmethodsingeneratedWADL">Documenting
resource classes and methods in generated WADL</h2><p>WADL documents can
include <a shape=
"rect" class="external-link"
href="http://www.w3.org/Submission/wadl/#x3-80002.3"; rel="nofollow">doc</a>
fragments.</p><p>Users may want to use <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/Description.java";>Description</a>
annotations which can be attached to resource classes and methods.</p><p>Note
that starting from CXF 2.4.0, Description annotations can be applied to input
parameters. Additionally, a method-level <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/Descriptions.java";>Descriptions</a>
annotation can have a collection of categorized Description annotations, with
each Description targeting a specific WADL element by setting its 'target'
property to one of the <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/ma
in/java/org/apache/cxf/jaxrs/model/wadl/DocTarget.java">DocTarget</a> values.
For example, one can use a Descriptions annotation to document the response
representation of a particular resource method, as well as add documentation
fragments to WADL wadl:method/wadl:request and wadl:method/wadl:response
elements:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
+</div></div><p>CXF JAX-RS supports the auto-generation of WADL for JAX-RS
endpoints. <br clear="none"> Note that JAX-RS subresources are late-resolved by
default, so using annotated interfaces for subresources and a
staticSubresourceResolution=true property will let the whole resource
tree/graph be described in a generated instance. Schemas will be generated for
JAXB-annotated types. See below for the information on how to get
auto-generated WADL instances reference existing schemas.</p><p><strong>CXF
2.4.0</strong>: org.apache.cxf.jaxrs.ext.Description and
org.apache.cxf.jaxrs.ext.xml.XMLName have been moved to
org.apache.cxf.jaxrs.model.wadl package given that their purpose is to improve
the WADL generation. Also, org.apache.cxf.jaxrs.model.wadl.WadlElement has been
renamed to 'ElementClass'.</p><h3
id="JAXRSServicesDescription-DocumentingresourceclassesandmethodsingeneratedWADL">Documenting
resource classes and methods in generated WADL</h3><p>WADL documents can
include <a shape=
"rect" class="external-link"
href="http://www.w3.org/Submission/wadl/#x3-80002.3"; rel="nofollow">doc</a>
fragments.</p><p>Users may want to use <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/Description.java";>Description</a>
annotations which can be attached to resource classes and methods.</p><p>Note
that starting from CXF 2.4.0, Description annotations can be applied to input
parameters. Additionally, a method-level <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/Descriptions.java";>Descriptions</a>
annotation can have a collection of categorized Description annotations, with
each Description targeting a specific WADL element by setting its 'target'
property to one of the <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/ma
in/java/org/apache/cxf/jaxrs/model/wadl/DocTarget.java">DocTarget</a> values.
For example, one can use a Descriptions annotation to document the response
representation of a particular resource method, as well as add documentation
fragments to WADL wadl:method/wadl:request and wadl:method/wadl:response
elements:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@POST
@Path("books/{bookid}")
@Descriptions({
@@ -355,13 +359,13 @@ public Book addBook(@Description("book i
@Path("books/{bookid}")
public Book addBook(@Description("book id") @PathParam("id") Long id) {...}
</pre>
-</div></div><h3 id="JAXRSServicesDescription-SupportforJavadoc">Support for
Javadoc</h3><p>In CXF 3.0.0 one can get the Javadoc documentation copied to
WADL being auto-generated at
runtime.</p><p>org.apache.cxf.jaxrs.model.wadl.JavaDocProvider implements
org.apache.cxf.jaxrs.model.wadl.DocumentationProvider and can be set as
WADLGenerator "documentationProvider" property.</p><p>JavaDocProvider can be
customized with URL or relative String path pointing to the generated Javadoc
jar, so this jar can be shipped in the application war or located
elsewhere.</p><p>JavaDocProvider parses the generated Javadoc HTML pages and
scrapes the documentation. See Java to Wadl section on the alternative approach
for supporting Javadoc.</p><h2
id="JAXRSServicesDescription-CustomizingWADLGeneration">Customizing WADL
Generation</h2><p>One can register a custom WadlGenerator as a jaxrs:provider.
The custom generator can extend the default <br clear="none">
org.apache.cxf.jaxrs.model.wadl.WadlGenerator o
r register a default one with one of the following properties set.</p><ul
class="alternate"><li>wadlNamespace: default is
"http://wadl.dev.java.net/2009/02";, the earlier one is
"http://research.sun.com/wadl/2006/10";.</li><li>singleResourceMultipleMethods:
default is 'true', for example, if a resource class has multiple methods
supported at the same path such as "/" (GET, POST, etc) then WADL will list
them all as the child nodes of a single resource
element.</li><li>useSingleSlashResource: default is false, for example, if you
have a root resource class with a path "root" and a resource method with a path
"" or "/" then a WADL resource representing the root will not have a child
resource representing this resource method (it would do if a resource method
had a more specific path such as "bar").</li></ul><p>Starting from CXF 2.4.1
and 2.3.5 the following properties are also supported:</p><ul
class="alternate"><li>applicationTitle: can be used to create an application
title.</li><li>n
amespacePrefix: defaut is 'prefix', it can be set to other value such as
'ns'.</li><li>ignoreForwardSlash: can be used to enforce that resource path
values do not start from '/'</li><li>addResourceAndMethodIds: WadlGenerator
will add "id" attributes to wadl:resource and wadl:method
elements</li></ul><p>An <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementClass.java";>ElementClass</a>
annotation can help with representing JAX-RS Response elements in the
generated WADL.</p><h3
id="JAXRSServicesDescription-RepresentingexplicitJAXBcollections">Representing
explicit JAXB collections</h3><p>Starting from CXF 2.5.5 and 2.6.2 it is
possible to get explicit collections represented in generated WADL grammar
sections and have WADL representations linking to these schema elements. Note
it is only possible for JAXB collections, for example:</p><div class="code
panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><h4 id="JAXRSServicesDescription-SupportforJavadoc">Support for
Javadoc</h4><p>In CXF 3.0.0 one can get the Javadoc documentation copied to
WADL being auto-generated at
runtime.</p><p>org.apache.cxf.jaxrs.model.wadl.JavaDocProvider implements
org.apache.cxf.jaxrs.model.wadl.DocumentationProvider and can be set as
WADLGenerator "documentationProvider" property.</p><p>JavaDocProvider can be
customized with URL or relative String path pointing to the generated Javadoc
jar, so this jar can be shipped in the application war or located
elsewhere.</p><p>JavaDocProvider parses the generated Javadoc HTML pages and
scrapes the documentation. See Java to Wadl section on the alternative approach
for supporting Javadoc.</p><h3
id="JAXRSServicesDescription-CustomizingWADLGeneration">Customizing WADL
Generation</h3><p>One can register a custom WadlGenerator as a jaxrs:provider.
The custom generator can extend the default <br clear="none">
org.apache.cxf.jaxrs.model.wadl.WadlGenerator o
r register a default one with one of the following properties set.</p><ul
class="alternate"><li>wadlNamespace: default is
"http://wadl.dev.java.net/2009/02";, the earlier one is
"http://research.sun.com/wadl/2006/10";.</li><li>singleResourceMultipleMethods:
default is 'true', for example, if a resource class has multiple methods
supported at the same path such as "/" (GET, POST, etc) then WADL will list
them all as the child nodes of a single resource
element.</li><li>useSingleSlashResource: default is false, for example, if you
have a root resource class with a path "root" and a resource method with a path
"" or "/" then a WADL resource representing the root will not have a child
resource representing this resource method (it would do if a resource method
had a more specific path such as "bar").</li></ul><p>Starting from CXF 2.4.1
and 2.3.5 the following properties are also supported:</p><ul
class="alternate"><li>applicationTitle: can be used to create an application
title.</li><li>n
amespacePrefix: defaut is 'prefix', it can be set to other value such as
'ns'.</li><li>ignoreForwardSlash: can be used to enforce that resource path
values do not start from '/'</li><li>addResourceAndMethodIds: WadlGenerator
will add "id" attributes to wadl:resource and wadl:method
elements</li></ul><p>An <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementClass.java";>ElementClass</a>
annotation can help with representing JAX-RS Response elements in the
generated WADL.</p><h4
id="JAXRSServicesDescription-RepresentingexplicitJAXBcollections">Representing
explicit JAXB collections</h4><p>Starting from CXF 2.5.5 and 2.6.2 it is
possible to get explicit collections represented in generated WADL grammar
sections and have WADL representations linking to these schema elements. Note
it is only possible for JAXB collections, for example:</p><div class="code
panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">@GET
@Path("books")
@org.apache.cxf.jaxrs.model.wadl.XMLName("{http://books}books";)
public List<Book> getBooks() {...}
</pre>
-</div></div><p>Given the above example, WADLGenerator will attempt to add a
'books' element to the generated schema with the targetNamespace set to
"http://books";. This 'books' element will have a sequence of elements linking
to a type representing the "Book" class.</p><h3
id="JAXRSServicesDescription-RepresentingexternalschemasandnonJAXBtypes">Representing
external schemas and non JAXB types</h3><p>By default, the WADL grammar
section will be properly generated if resource methods accept or return JAXB
types.</p><p>Even when you do use JAXB, the JAXB types may have been generated
from the external schema so having WadlGenerator attempting to recreate the
original schema may not work well. To have a generated WADL referencing the
original schema(s) please set a 'schemaLocations' list property
(programmatically or from Spring) :</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Given the above example, WADLGenerator will attempt to add a
'books' element to the generated schema with the targetNamespace set to
"http://books";. This 'books' element will have a sequence of elements linking
to a type representing the "Book" class.</p><h4
id="JAXRSServicesDescription-RepresentingexternalschemasandnonJAXBtypes">Representing
external schemas and non JAXB types</h4><p>By default, the WADL grammar
section will be properly generated if resource methods accept or return JAXB
types.</p><p>Even when you do use JAXB, the JAXB types may have been generated
from the external schema so having WadlGenerator attempting to recreate the
original schema may not work well. To have a generated WADL referencing the
original schema(s) please set a 'schemaLocations' list property
(programmatically or from Spring) :</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">WadlGenerator wg = new WadlGenerator();
wg.setSchemaLocations(Collections.singletonList("classpath:/book.xsd"));
</pre>
@@ -377,7 +381,7 @@ wg.setSchemaLocations(Collections.single
-->
<representation mediaType="application/xml" element="prefix1:thebook2"/>
</pre>
-</div></div><p>If no JAXB is used then you can attach an <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/XMLName.java";>XMLName</a>
annotation to method input or output types. Alternatively, you can register an
instance of <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementQNameResolver.java";>ElementQNameResolver</a>
with the WadlGenerator which will be used for creating
wadl:representation/@element values.</p><h3
id="JAXRSServicesDescription-Changingthebaseaddress">Changing the base
address</h3><p>Starting from CXF 2.6.2 it is possible to affect the base
address specified in the auto-generated WADL (in wadl:resources/@base
attribute).<br clear="none"> WADLGenerator can be indirectly configured by
setting a jaxrs:server/@publishedEndpointUrl attribute, similarly to the way
CXF WS
DL generator can be configured by setting a
jaxws:endpoint/@publishedEndpointUrl attribute.</p><p> </p><h1
id="JAXRSServicesDescription-java2wadlMavenplugin">java2wadl Maven
plugin</h1><p>CXF 3.0.0 and 2.7.11 introduce java2wadl plugin for generating
WADL at the build time:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
+</div></div><p>If no JAXB is used then you can attach an <a shape="rect"
class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/XMLName.java";>XMLName</a>
annotation to method input or output types. Alternatively, you can register an
instance of <a shape="rect" class="external-link"
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementQNameResolver.java";>ElementQNameResolver</a>
with the WadlGenerator which will be used for creating
wadl:representation/@element values.</p><h4
id="JAXRSServicesDescription-Changingthebaseaddress">Changing the base
address</h4><p>Starting from CXF 2.6.2 it is possible to affect the base
address specified in the auto-generated WADL (in wadl:resources/@base
attribute).<br clear="none"> WADLGenerator can be indirectly configured by
setting a jaxrs:server/@publishedEndpointUrl attribute, similarly to the way
CXF WS
DL generator can be configured by setting a
jaxws:endpoint/@publishedEndpointUrl attribute.</p><p> </p><h2
id="JAXRSServicesDescription-java2wadlMavenplugin">java2wadl Maven
plugin</h2><p>CXF 3.0.0 and 2.7.11 introduce java2wadl plugin for generating
WADL at the build time:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;"><groupId>org.apache.cxf</groupId>
<artifactId>cxf-java2wadl-plugin</artifactId>
<version>3.0.0</version>
@@ -423,7 +427,7 @@ wg.setSchemaLocations(Collections.single
</plugins>
</build>
</pre>
-</div></div><p>Note that Javadoc can be properly supported by enabling the
"parsejavadoc" execution and a docProvider property.</p><h1
id="JAXRSServicesDescription-WADLTransformations">WADL
Transformations</h1><p>Starting from CXF 3.0.4 it is possible to configure
WADLGenerator with a 'stylesheetReference' property pointing to a local XSLT
template. </p><p>If an 'applyStylesheetLocally' property is disabled
(default) then a generated WADL XML representation will include an XML XSLT
processing instruction pointing to a template with the browser downloading it
in the next step and doing the transformation itself. Otherwise WADLGenerator
will attempt to do a local transformation before returning a response to the
browser.</p><p>This feature can help with further enhancing the generated WADL
XML with some simple transformations (example, adding some information to WADL
XML that is not possible to get from the annotated JAX-RS resources) or convert
it to HTML.</p><h1 id="JAXRSServic
esDescription-ServicelistingsandWADLqueries">Service listings and WADL
queries</h1><p>Links to WADL instances for RESTful endpoints are available from
{base endpointaddress}/services, in addition to SOAP endpoints if
any.</p><p>For example, given</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+</div></div><p>Note that Javadoc can be properly supported by enabling the
"parsejavadoc" execution and a docProvider property.</p><h2
id="JAXRSServicesDescription-WADLTransformations">WADL
Transformations</h2><p>Starting from CXF 3.0.4 it is possible to configure
WADLGenerator with a 'stylesheetReference' property pointing to a local XSLT
template. </p><p>If an 'applyStylesheetLocally' property is disabled
(default) then a generated WADL XML representation will include an XML XSLT
processing instruction pointing to a template with the browser downloading it
in the next step and doing the transformation itself. Otherwise WADLGenerator
will attempt to do a local transformation before returning a response to the
browser.</p><p>This feature can help with further enhancing the generated WADL
XML with some simple transformations (example, adding some information to WADL
XML that is not possible to get from the annotated JAX-RS resources) or convert
it to HTML.</p><h2 id="JAXRSServic
esDescription-ServicelistingsandWADLqueries">Service listings and WADL
queries</h2><p>Links to WADL instances for RESTful endpoints are available from
{base endpointaddress}/services, in addition to SOAP endpoints if
any.</p><p>For example, given</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre class="brush: xml; gutter: false; theme: Default"
style="font-size:12px;">Base address : 'http://localhost:8080'
WAR name : 'store'
CXFServlet : '/books/*'
@@ -437,7 +441,7 @@ public class FictionBookOrders {
public class SportBookOrders {
}
</pre>
-</div></div><p>then WADL will contain the description of both
FictionBookOrders and SportBookOrders resources.</p><p>> <a shape="rect"
class="external-link"
href="http://localhost:8080/store/books/orders/fiction?_wadl";
rel="nofollow">http://localhost:8080/store/books/orders/fiction?_wadl</a><br
clear="none"> > <a shape="rect" class="external-link"
href="http://localhost:8080/store/books/orders/sport?_wadl";
rel="nofollow">http://localhost:8080/store/books/orders/sport?_wadl</a></p><p>will
give you all the info for FictionBookOrders and SportBookOrders
respectively.</p><p><strong>Note</strong> that WadlGenerator will return an
existing WADL document instead of auto-generating a new one if
jaxrs:server/@docLocation attribute has been set.</p><p>By default, starting
from CXF 2.5.1 and 2.4.5, the media type for a ?_wadl response is set to
application/xml which is to do with the fact that Firefox does not really like
'application/vnd.sun.wadl+xml' unless some wadl plugin is register
ed. If HTTP Content-Type is set to 'application/xml' then Firefox will show it
with no problems.</p><p>You can easily customize what Content-Type is set by
either using a WadlGenerator 'defaultMediaType' property or using the extension
mappings and adding a .wadl at the end of request URI instead of using a _wadl
query: "http://localhost:8080/store/books/orders/fiction.wadl";, where
extensions will map a 'wadl' to 'application/vnd.sun.wadl+xml' or indeed to
'application/xml'.</p><h1 id="JAXRSServicesDescription-WADLinJSONformat">WADL
in JSON format</h1><p>Use a "?_wadl&_type=json" or something like
"fiction.wadl", where extensions will map a 'wadl' to 'application/json' in
order to get a WADL JSON representations, please see <a shape="rect"
class="external-link"
href="http://sberyozkin.blogspot.com/2011/10/describing-json-services-in-wadl.html";
rel="nofollow">this blog entry</a> for more information.</p><h1
id="JAXRSServicesDescription-HidinglinkstoJAXRSendpointsfromtheservicespa
ge">Hiding links to JAXRS endpoints from the services page</h1><p>In some
cases you may not want the users to see the links to some JAXRS endpoints. For
example, if you have an AtomPullServer endpoint collecting the log entries for
a number of application endpoints, you may not want to see AtomPullServer
endpoint being listed among the endpoints representing the actual application
and which users are actually interested in. If so then adding an
"org.apache.cxf.endpoint.private" boolean property with a value "true" will do
the trick; note the same property can be used by jaxws endpoints.</p></div>
+</div></div><p>then WADL will contain the description of both
FictionBookOrders and SportBookOrders resources.</p><p>> <a shape="rect"
class="external-link"
href="http://localhost:8080/store/books/orders/fiction?_wadl";
rel="nofollow">http://localhost:8080/store/books/orders/fiction?_wadl</a><br
clear="none"> > <a shape="rect" class="external-link"
href="http://localhost:8080/store/books/orders/sport?_wadl";
rel="nofollow">http://localhost:8080/store/books/orders/sport?_wadl</a></p><p>will
give you all the info for FictionBookOrders and SportBookOrders
respectively.</p><p><strong>Note</strong> that WadlGenerator will return an
existing WADL document instead of auto-generating a new one if
jaxrs:server/@docLocation attribute has been set.</p><p>By default, starting
from CXF 2.5.1 and 2.4.5, the media type for a ?_wadl response is set to
application/xml which is to do with the fact that Firefox does not really like
'application/vnd.sun.wadl+xml' unless some wadl plugin is register
ed. If HTTP Content-Type is set to 'application/xml' then Firefox will show it
with no problems.</p><p>You can easily customize what Content-Type is set by
either using a WadlGenerator 'defaultMediaType' property or using the extension
mappings and adding a .wadl at the end of request URI instead of using a _wadl
query: "http://localhost:8080/store/books/orders/fiction.wadl";, where
extensions will map a 'wadl' to 'application/vnd.sun.wadl+xml' or indeed to
'application/xml'.</p><h2 id="JAXRSServicesDescription-WADLinJSONformat">WADL
in JSON format</h2><p>Use a "?_wadl&_type=json" or something like
"fiction.wadl", where extensions will map a 'wadl' to 'application/json' in
order to get a WADL JSON representations, please see <a shape="rect"
class="external-link"
href="http://sberyozkin.blogspot.com/2011/10/describing-json-services-in-wadl.html";
rel="nofollow">this blog entry</a> for more information.</p><h1
id="JAXRSServicesDescription-HidinglinkstoJAXRSendpointsfromtheservicespa
ge">Hiding links to JAXRS endpoints from the services page</h1><p>In some
cases you may not want the users to see the links to some JAXRS endpoints. For
example, if you have an AtomPullServer endpoint collecting the log entries for
a number of application endpoints, you may not want to see AtomPullServer
endpoint being listed among the endpoints representing the actual application
and which users are actually interested in. If so then adding an
"org.apache.cxf.endpoint.private" boolean property with a value "true" will do
the trick; note the same property can be used by jaxws endpoints.</p></div>
</div>
<!-- Content -->
</td>
