cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > JAXRS Services Description
Date Wed, 22 Dec 2010 15:42:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/1810/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Services+Description">JAXRS
Services Description</a></h2>
    <h4>Page  <b>added</b> by             <a href="https://cwiki.apache.org/confluence/display/~sergey_beryozkin">Sergey
Beryozkin</a>
    </h4>
         <br/>
    <div class="notificationGreySide">
         <span style="font-size:2em;font-weight:bold"> JAX-RS Services Description </span>

<div>
<ul>
    <li><a href='#JAXRSServicesDescription-WADLsupport'>WADL support</a></li>
    <li><a href='#JAXRSServicesDescription-DocumentingresourceclassesandmethodsinWADL'>Documenting
resource classes and methods in WADL</a></li>
    <li><a href='#JAXRSServicesDescription-CustomWADLproviders'>Custom WADL providers</a></li>
<ul>
    <li><a href='#JAXRSServicesDescription-RepresentingexternalschemasandnonJAXBtypes'>Representing
external schemas and non JAXB types</a></li>
</ul>
    <li><a href='#JAXRSServicesDescription-GeneratingtheclientcodefromWADL'>Generating
the client code from WADL</a></li>
    <li><a href='#JAXRSServicesDescription-HidinglinkstoJAXRSendpointsfromtheservicespage'>Hiding
links to JAXRS endpoints from the services page</a></li>
</ul></div>

<h1><a name="JAXRSServicesDescription-WADLsupport"></a>WADL support</h1>

<p>CXF JAX-RS supports the auto-generation of <a href="http://www.w3.org/Submission/wadl"
class="external-link" rel="nofollow">WADL</a> for JAX-RS endpoints. <br/>
Note that JAX-RS subresources are supposed to be late-resolved, 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.</p>

<p>WADL instances for RESTful endpoints are available from {base endpointaddress}/services,
in addition to SOAP endpoints if any. Note that you can override the location at which listings
are provided (in case you would like '/services' be available to your resources) using<br/>
'service-list-path' servlet parameter, ex :</p>

<p>&gt; 'service-list-path' = '/listings'</p>

<p>Going to the service listings page is not the only way to see the wadl instances,
generally one can get it using a ?_wadl query.</p>

<p>For example, given</p>

<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
Base address : 'http://localhost:8080'
WAR name : 'store'
CXFServlet : '/books/*'
jaxrs:server/@address = '/orders'
jaxrs:server/@staticSubresourceResoulution = 'true'
</pre>
</div></div>

<p>and 2 root resource classes registered with this endpoint, say</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
@Path(<span class="code-quote">"/fiction"</span>) 
<span class="code-keyword">public</span> class FictionBookOrders {
}
@Path(<span class="code-quote">"/sport"</span>) 
<span class="code-keyword">public</span> class SportBookOrders {
}
</pre>
</div></div>

<p>then</p>

<p>&gt; <a href="http://localhost:8080/store/books/orders?_wadl" class="external-link"
rel="nofollow">http://localhost:8080/store/books/orders?_wadl</a></p>

<p>will give you the description of all the root resource classes registered<br/>
with a given jaxrs:server endpoint, including all the subresources. While</p>

<p>&gt; <a href="http://localhost:8080/store/books/orders/fiction?_wadl" class="external-link"
rel="nofollow">http://localhost:8080/store/books/orders/fiction?_wadl</a><br/>
&gt; <a href="http://localhost:8080/store/books/orders/sport?_wadl" class="external-link"
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>If you have many jaxrs:endpoints then visiting</p>

<p>&gt; <a href="http://localhost:8080/store/books" class="external-link" rel="nofollow">http://localhost:8080/store/books</a>
<br/>
&gt; <a href="http://localhost:8080/store/books/services" class="external-link" rel="nofollow">http://localhost:8080/store/books/services</a>
</p>

<p>will let you see all the WADL links.</p>

<p>Note that the media type for a ?_wadl response is set to 'application/vnd.sun.wadl+xml'
which is something Firefox does not really<br/>
like unless some wadl plugin is registered. If an HTTP Accept header is set to 'application/xml'
then Firefox will show it with no problems. Doing<br/>
'?_wadl&amp;_type=xml' will ensure a WADL generator will see Accept being set set to 'application/xml'.</p>

<h1><a name="JAXRSServicesDescription-DocumentingresourceclassesandmethodsinWADL"></a>Documenting
resource classes and methods in WADL</h1>

<p>WADL documents can include <a href="http://www.w3.org/Submission/wadl/#x3-80002.3"
class="external-link" rel="nofollow">doc</a> fragments. Users may want to use <a
href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/Description.java"
class="external-link" rel="nofollow">Description</a> annotations which can be attached
to resource classes and methods.</p>

<h1><a name="JAXRSServicesDescription-CustomWADLproviders"></a>Custom WADL
providers</h1>

<p>One can register a custom WADLGenerator as a jaxrs:provider. The custom generator
can extend the default <br/>
org.apache.cxf.jaxrs.model.wadl.WADLGenerator or register a default one with one of the following
properties set.</p>

<ul class="alternate" type="square">
	<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>


<h2><a name="JAXRSServicesDescription-RepresentingexternalschemasandnonJAXBtypes"></a>Representing
external schemas and non JAXB types</h2>

<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" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
WadlGenerator wg = <span class="code-keyword">new</span> WadlGenerator();
wg.setSchemaLocations(Collections.singletonList(<span class="code-quote">"classpath:/book.xsd"</span>));
</pre>
</div></div> 

<p>In this case the grammar section will have the 'book.xsd' schema inlined. If this
schema imports other schemas then the imports with relative URIs will be replaced by the absolute
URIs based on the current endpoint's base address. For example, if the endpoint address is
"http://somehost/bar" and the 'book.xsd' imports "foo/book1.xsd" then the published WADL will
contain an "http://somehost/bar/foo/book1.xsd". At the moment a custom RequestHandler filter
will have to be registered to serve resources such as "http://somehost/bar/foo/book1.xsd"
which can 'calculate' which resource is required get the absolute request URI and comparing
it with the base URI, possibly with the help of the injected JAXRS UriInfo context. Alternatively,
resources such as book1.xsd may be served by CXFServlet itself (see the Redirection with CXFServlet)
 </p>

<p>TODO : add ignoreImports flag so that users can list root and imported schemas in
"schemaLocations" and have them all inlined.</p>

<p>Note that the root schema such as "book.xsd" is inlined - you can have it referenced
only by setting an 'externalLinks' list property. This will very well when the "book.xsd"
is indeed available at some external URI, but this property can be used to avoid the local
schemas being inlined. Moreover, using JAXB will not be required. The result will look like
this :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
<span class="code-tag">&lt;wadl:grammars&gt;</span>
<span class="code-tag">&lt;wadl:include href=<span class="code-quote">"http://books.xsd"</span>/&gt;</span>
<span class="code-tag">&lt;/wadl:grammars&gt;</span>
</pre>
</div></div> 

<p>Note that "schemaLocations" and "externalLinks" properties differ in that the schemas
referenced by the former one are inlined.</p>

<p>You can also customize the way schema elements are referenced. When WADLGenerator
creates WADL representation elements (representing resource method input or output types)
it will be able to link to schema elements provided a given type is actually a JAXB one, so
the result may look like this :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
&lt;!-- 
  thebook2 element is declared in a schema inlined in or referenced from the grammar section
  prefix1 is bound to that schema's target namespace and is declared at the wadl:application
element 
--&gt;
<span class="code-tag">&lt;representation mediaType=<span class="code-quote">"application/xml"</span>
element=<span class="code-quote">"prefix1:thebook2"</span>/&gt;</span>
</pre>
</div></div>

<p>If no JAXB is used then you can attach an <a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/ext/xml/XMLName.java"
class="external-link" rel="nofollow">XmlName</a> annotation to method input or output
types. Alternatively, you can register an instance of <a href="http://svn.apache.org/repos/asf/cxf/trunk/rt/frontend/jaxrs/src/main/java/org/apache/cxf/jaxrs/model/wadl/ElementQNameResolver.java"
class="external-link" rel="nofollow">ElementQNameResolver</a> with the WADLGenerator
which will be used for creating wadl:representation/@element values.</p>

<h1><a name="JAXRSServicesDescription-GeneratingtheclientcodefromWADL"></a>Generating
the client code from WADL</h1>

<p>If you register an org.apache.cxf.jaxrs.ext.codegen.CodeGeneratorProvider with a
jaxrs endpoint and issue a '_code' query to it then you will get back an XHTML page containing
the link to a zipped client source code which you can download and start customizing. </p>

<p>Internally, before the code gets generated, WADL will be generated first. The archive
will include JAXB generated classes from a WADL grammar section plus the proxy based client
code for accessing root and sub resources. The WebClient based code can not be generated just
yet but one can request that only a WADL grammar section is processed by adding a '_codeType=grammar'
query and easily adding a WebClient-based code. </p>

<p>Here is how to get the archive programmatically :</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
WebClient wc = WebClient.create(<span class="code-quote">"http:<span class="code-comment">//localhost:9080/petstore"</span>);
</span>XMLSource source = wc.query(<span class="code-quote">"_code"</span>).query(<span
class="code-quote">"_os"</span>, getOs()).get(XMLSource.class);
<span class="code-object">String</span> link = source.getValue(<span class="code-quote">"ns:html/ns:body/ns:ul/ns:a/@href"</span>,
 
              Collections.singletonMap(<span class="code-quote">"ns"</span>,<span
class="code-quote">"http:<span class="code-comment">//www.w3.org/1999/xhtml"</span>));
</span><span class="code-comment">// download a zip file          
</span>WebClient wcZip = WebClient.create(link);
InputStream is = wcZip.accept(<span class="code-quote">"application/zip"</span>).get(InputStream.class);
<span class="code-comment">// unzip and compile it</span>
</pre>
</div></div>

<p>Please see a <a href="http://svn.apache.org/repos/asf/cxf/trunk/systests/jaxrs/src/test/java/org/apache/cxf/systest/jaxrs/JAXRSClientServerResourceCreatedSpringProviderTest.java"
class="external-link" rel="nofollow">testPetStore</a> test for more details.</p>

<h1><a name="JAXRSServicesDescription-HidinglinkstoJAXRSendpointsfromtheservicespage"></a>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 of your 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 the AtomPullServer endpoint being listed among
the endpoints which the users are actually interested in. If so then adding an "org.apache.cxf.endpoint.private"
boolean property with the value "true" will do the trick; note the same property can be used
by jaxws endpoints.</p>
    </div>
    <div id="commentsSection" class="wiki-content pageSection">
       <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
       </div>
       <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Services+Description">View
Online</a>
              |
       <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/JAXRS+Services+Description?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
           </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message