Serving a WADL document for your resources

A developer might not want to expose the Web Application Description Language (WADL) document via an OPTIONS request to limit the amount of information a third party can gather about a service. By providing less information, security through obscurity may be achieved.

About this task

By default, a WADL document can be requested for a particular resource by invoking an HTTP OPTIONS request for any Java API for RESTful Web Services (JAX-RS) URL. You can issue an OPTIONS request with most HTTP clients.

You can also build your own WADL document by using the org.apache.wink.common.model.wadl.WADLGenerator. WADLGenerator builds a Java Architecture for XML Binding (JAXB) annotated object model so you can easily return it as an entity response in an @OPTIONS resource method. If you want a service document for all the classes in your application, you can use the WADLGenerator to create a WADL representation. The service document can help enhance the understanding.

In the following example, you can use the WADLGenerator to build a JAXB model of your resources. You can then return the JAXB model for clients to consume.

Procedure

  1. Use org.apache.wink.common.model.wadl.WADLGenerator to build your WADL document. The following example illustrates a basic resource with an OPTIONS request:
    @javax.ws.rs.Path("myexample")
    public class MyResource {
        @Context
        javax.ws.rs.core.Application app;
        
        @javax.ws.rs.OPTIONS
        @Produces("application/vnd.sun.wadl+xml")
        public org.apache.wink.common.model.wadl.Application getOptions() {
            org.apache.wink.common.model.wadl.Application wadlAppDoc = new WADLGenerator().generate("", app.getClasses());
            /* modify the  wadlAppDoc JAXB model if you want to add additional information */
            return wadlAppDoc;
        }
    }

    You can inject the Application sub-class that contains all your resource classes. Then you can pass in the classes to the WADLGenerator to generate all your classes.

  2. Return the org.apache.wink.common.model.wadl.Application class, which is a JAXB annotated object. The JAX-RS MessageBodyWriter for JAXB annotated types will be used to serialize the WADL document to the client.
    @javax.ws.rs.Path("myexample")
    public class MyResource {
        @Context
        javax.ws.rs.core.Application app;
        
        @javax.ws.rs.OPTIONS
        @Produces("application/vnd.sun.wadl+xml")
        public org.apache.wink.common.model.wadl.Application getOptions() {
            org.apache.wink.common.model.wadl.Application wadlAppDoc = new WADLGenerator().generate("", app.getClasses());
            /* modify the  wadlAppDoc JAXB model if you want to add additional information */
            return wadlAppDoc;
        }
    }

Results

You have built your WADL document using the WADLGenerator.

Task topic    

Terms and conditions for information centers | Feedback

Last updated: April 18, 2014 05:01 AM CDT
http://www14.software.ibm.com/webapp/wsbroker/redirect?version=phil&product=was-nd-iseries&topic=twbs_jaxrs_wadl_serving
File name: twbs_jaxrs_wadl_serving.html