Publishing the meta data

The following two methods are used for publishing WADL of a Web resource:

HTTP GET method
HTTP OPTIONS method

The following table describes the conditions for publishing WADL of a Web resource by using the HTTP GET method. WADL is published when the JAX-RS engine receives an HTTP request that fulfills all the conditions described in the following table.

Table 13-2 HTTP request (GET) required for publishing the meta data of a Web resource

No.	Item		Condition
1	HTTP method		GET method
2	URL	Schema	http or https
3		Host name (:Port number)	Host name (and port number) having a Web resource that requests the publication of the meta data
4		Context path	Context path of a Web application, which includes a Web resource that requests the publication of the meta data
5		The path following the context path	application.wadl

For example, consider the context root of a Web application (WAR file) containing a Web resource to be a sample, and the name of the host on which a Web application is published is example.org. In this case the URL will be . Here, all the Web resources specified in the com.sun.jersey.config.property.packages initialization parameter (init-param element) of web.xml are included in the WADL to be published. If the com.sun.jersey.config.property.packages initialization parameter (init-param element) is not coded in web.xml, all the Web resources in the WAR file are included. For details on the com.sun.jersey.config.property.packages initialization parameter (init-param element) of web.xml, see 11.2 Creating web.xml.

An example of WADL of a Web resource is as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
 <doc xmlns:jersey="http://jersey.dev.java.net/" jersey:generatedBy="Cosminexus JAX-RS 09-00"/>
 <resources base="http://example.org/sample/">
  <resource path="root">
   <method name="GET" id="resourceMethod">
    <response>
     <representation mediaType="*/*"/>
    </response>
   </method>
   <method name="POST" id="postHandler">
    <request>
     <representation mediaType="*/*">
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       style="query" name="form"/>
     </representation>
    </request>
    <response>
     <representation mediaType="text/html"/>
    </response>
   </method>
   <resource path="subresourceMethod">
    <method name="GET" id="subResourceMethod">
     <request>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="1"
       type="xs:string" style="matrix" name="matrix"/>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       name="cookie"/>
     </request>
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
   <resource path="exception">
    <method name="GET" id="subResourceMethodThrowingException">
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
   <resource path="subresourceLocator/{id}">
    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
     style="template" name="id"/>
    <method name="GET" id="getHandlerForSubResource">
     <request>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       style="header" name="HeaderKey"/>
     </request>
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
  </resource>
 </resources>
</application>

The following table describes the conditions for publishing the meta data of a Web resource by using the HTTP OPTIONS method. The meta data is published when the JAX-RS engine on the Web Service machine receives an HTTP request that fulfills all the conditions described in the following table.

Table 13-3 HTTP request (OPTIONS) required for publishing the meta data of a Web resource

No.	Item		Condition
1	HTTP method		OPTIONS method
2	URL	Schema	http
3		Host name (: Port number)	Host name (and port number) having a Web resource that requests the publication of the meta data
4		Context path	Context path of a Web application which includes a Web resource that requests the publication of the meta data
5		Web resource path	Value of the Path annotation used in a Web resource

For example, consider the value of the Path annotation of the Web resource A to be "/rootA", the host name to be "example.org", and the context path to be "sample". In this case, the URL to publish the meta data will be: http://example.org/sample/rootA.

In such a case, only the requested Web resources are included in WADL to be published.

Hint: If a method of the target Web resource contains the OPTIONS annotation and can process the HTTP OPTIONS request, then the JAX-RS engine does not publish WADL and calls a method that processes the HTTP OPTIONS request of a Web resource. If the Web resource fails to process the HTTP OPTIONS request, the JAX-RS engine automatically generates WADL.

An example of WADL in which the HTTP OPTIONS method is used is as follows.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
 <doc xmlns:jersey="http://jersey.dev.java.net/" jersey:generatedBy="Cosminexus JAX-RS 09-00"/>
 <resources base="http://example.org/sample/">
  <resource path="/root">
   <method name="GET" id="resourceMethod">
    <response>
     <representation mediaType="*/*"/>
    </response>
   </method>
   <method name="POST" id="postHandler">
    <request>
     <representation mediaType="*/*">
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       style="query" name="form"/>
     </representation>
    </request>
    <response>
     <representation mediaType="text/html"/>
    </response>
   </method>
   <resource path="subresourceMethod">
    <method name="GET" id="subResourceMethod">
     <request>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" default="1"
       type="xs:string" style="matrix" name="matrix"/>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       name="cookie"/>
     </request>
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
   <resource path="exception">
    <method name="GET" id="subResourceMethodThrowingException">
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
   <resource path="subresourceLocator/{id}">
    <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
     style="template" name="id"/>
    <method name="GET" id="getHandlerForSubResource">
     <request>
      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string"
       style="header" name="HeaderKey"/>
     </request>
     <response>
      <representation mediaType="*/*"/>
     </response>
    </method>
   </resource>
  </resource>
 </resources>
</application>

You can choose whether to publish WADL by specifying true or false in the com.sun.jersey.config.feature.DisableWADL property. Specify this property in:

cjrconf.properties file
Servlet initialization parameter of web.xml

If the property is specified in both of the above mentioned locations, a priority is given to the servlet initialization parameter.

The following table describes the existence of the WADL publication.

Table 13-4 Existence of WADL publication

No.	Servlet initialization parameter	Value	Operations of the JAX-RS engine
1	com.sun.jersey.config.feature.DisableWADL	true	Does not publish WADL. The value is not case sensitive.
		false	Publishes WADL. The value is not case sensitive.
		A value other than true or false	Publishes WADL by using the settings mentioned in the common definition file (cjrconf.properties) and ignores the value specified in web.xml. Checks if the default value false has been specified and then publishes WADL.

13.3 Publishing the meta data

(1) Conditions for publishing the meta data