You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cxf.apache.org by bu...@apache.org on 2015/03/05 18:47:17 UTC
svn commit: r942474 - in /websites/production/cxf/content:
cache/docs.pageCache docs/jaxrs-services-description.html
Author: buildbot
Date: Thu Mar 5 17:47:16 2015
New Revision: 942474
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 Thu Mar 5 17:47:16 2015
@@ -118,11 +118,11 @@ 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.rbtoc1424090804525 {padding: 0px;}
-div.rbtoc1424090804525 ul {list-style: disc;margin-left: 0px;}
-div.rbtoc1424090804525 li {margin-left: 0px;padding-left: 0px;}
+div.rbtoc1425577607815 {padding: 0px;}
+div.rbtoc1425577607815 ul {list-style: disc;margin-left: 0px;}
+div.rbtoc1425577607815 li {margin-left: 0px;padding-left: 0px;}
-/*]]>*/</style></p><div class="toc-macro rbtoc1424090804525">
+/*]]>*/</style></p><div class="toc-macro rbtoc1425577607815">
<ul class="toc-indentation"><li><a shape="rect" href="#JAXRSServicesDescription-WADLoverview">WADL 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>
@@ -254,7 +254,7 @@ div.rbtoc1424090804525 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</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="confluenceTd"><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 implementation 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" rowspan="1" class="confluenc
eTd"><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">-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:date' 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.xm
l.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 mapping 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><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</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="confluenceTd"><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 implementation 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" rowspan="1" class="confluenc
eTd"><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">-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:date' 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.xm
l.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 mapping 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. Lin
king 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">
<script class="theme: Default; brush: xml; gutter: false" type="syntaxhighlighter"><![CDATA[<jaxb:bindings version="2.0"
xmlns:jaxb="http://java.sun.com/xml/ns/jaxb"
xmlns:xs="http://www.w3.org/2001/XMLSchema"