Generated WADL for Resource List

Question

I am afraid a couple of days with the following problem. I searched quite a bit for the answer, here in SO, on the mailing lists and the network as a whole, but could not find the answer to this specific question.

Setting up the problem area ...

I am using Jersey 1.16 inside Tomcat 7.

I created a simple JAX-RS resource that looks like this:

@Path("/") @Produces({ "application/xml", "text/plain" }) public class ExampleResource { @GET public List<Thing> getThings() { List<Thing> list = new ArrayList<>(); list.add(new Thing("a thing 1", "a thing description 1")); list.add(new Thing("a thing 2", "a thing description 2")); return list; } } 

Thing is an annotated POJO JAXB similar to this

  @XmlRootElement(name = "thing") public class Thing { private String name; private String description; // getters, setters and @XmlElement annotations ommited for brevity 

I also set up WadlGeneratorJAXBGrammarGenerator.class

And when I ask GET http://localhost:8092/rest , it works like a charm - a formatted collection of Thing is returned.

The automatically generated WADL http://localhost:8092/rest/application.wadl almost perfect, it looks like this:

 <?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application xmlns="http://wadl.dev.java.net/2009/02"> <doc xmlns:jersey="http://jersey.java.net/" jersey:generatedBy="Jersey: 1.16 11/28/2012 02:09 PM" /> <grammars> <include href="application.wadl/xsd0.xsd"> <doc title="Generated" xml:lang="en" /> </include> </grammars> <resources base="http://localhost:8092/rest/"> <resource path="/"> <method id="getThings" name="GET"> <response> <ns2:representation xmlns:ns2="http://wadl.dev.java.net/2009/02" xmlns="" element="thing" mediaType="application/xml" /> <representation mediaType="text/plain" /> </response> </method> </resource> </resources> </application> 

As I said, almost perfect, and that is the problem.

 <ns2:representation xmlns:ns2="http://wadl.dev.java.net/2009/02" xmlns="" element="thing" mediaType="application/xml" /> 

WADL does not describe that /getThings returns a List<Thing> . Rather, it looks like this refers to a single Thing element in xsd0.xsd . Therefore, when I submit it, for example, wadl2java, it generates an untyped client. To get a List<Thing> , I need to manually encode it, something like

List<Thing> asXml = root().getAsXml(new GenericType<List<Thing>>(){});

Does anyone know if it is possible to have an automatic WADL creation that somehow indicates that this particular resource returns a List of resources of a certain type?

And I don't want to create an additional ThingList JAXB-annotated class and return it instead to the jersey resource.

I’m almost there, creating a “perfect” WADL, it’s just (hopefully) a little piece that I’m missing ...

Thank you very much!

Answer 1

I have the same problem and I solved it by creating my own WADL.

To do this, you need to add the following files to your project

application-doc.xml for high level WADL comments

application-grammers.xml that defines the location of your schema (with your Things and Thing and complextypes elements)

resourcedoc.xml, it is generated by the maven plugin, and it reads your jersey classes that contain javadoc annotations of your response element.

just add this HrWadlGeneratorConfig class to your project and add it as init param to the jersey servlet

  <init-param> <param-name>com.sun.jersey.config.property.WadlGeneratorConfig</param-name> <param-value>nl.amis.hr.wadl.HrWadlGeneratorConfig</param-value> </init-param> 

Class

  package nl.amis.hr.wadl; import com.sun.jersey.api.wadl.config.WadlGeneratorConfig; import com.sun.jersey.api.wadl.config.WadlGeneratorDescription; import com.sun.jersey.server.wadl.generators.WadlGeneratorApplicationDoc; import com.sun.jersey.server.wadl.generators.WadlGeneratorGrammarsSupport; import com.sun.jersey.server.wadl.generators.resourcedoc.WadlGeneratorResourceDocSupport; import com.sun.research.ws.wadl.Grammars; import com.sun.research.ws.wadl.Include; import com.sun.research.ws.wadl.ObjectFactory; import java.util.List; public class HrWadlGeneratorConfig extends WadlGeneratorConfig { @Override public List<WadlGeneratorDescription> configure() { ObjectFactory obj = new ObjectFactory() ; Grammars gram = obj.createGrammars(); Include e = obj.createInclude(); e.setHref("schema.xsd"); gram.getInclude().add(e); WadlGeneratorConfigDescriptionBuilder builder = generator(WadlGeneratorApplicationDoc.class) .prop( "applicationDocsStream", "application-doc.xml" ) .generator( WadlGeneratorGrammarsSupport.class ) .prop( "grammarsStream", "application-grammars.xml" ) .generator( WadlGeneratorResourceDocSupport.class ) .prop( "resourceDocStream", "resourcedoc.xml" ); return builder.descriptions(); } } 

Here is a jersey class snippet and the name @ response.representation.200.qname points to an element in your own schema.xsd

  /** * Returns the item if existing. * * @response.representation.200.qname employees * @response.representation.200.mediaType application/xml,application/json * @response.representation.200.doc This is the representation returned by default * @response.representation.200.example {@link EmployeeExample#SAMPLE_ITEM} * * * @return the requested item if this service is available */ @GET public List<Employee> getEmployees() { return hrBean.getEmployeesFindAll(); } 

and maven pom, which generates the resourcedoc.xml file, which we will use the WADL generator.

  <pluginManagement> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>2.4</version> </plugin> </plugins> </pluginManagement> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <executions> <execution> <goals> <goal>javadoc</goal> </goals> <phase>compile</phase> </execution> </executions> <configuration> <encoding>UTF-8</encoding> <verbose>false</verbose> <show>public</show> <subpackages>nl.amis.hr.restful</subpackages> <doclet>com.sun.jersey.wadl.resourcedoc.ResourceDoclet</doclet> <docletPath>${path.separator}${project.build.outputDirectory}</docletPath> <docletArtifacts> <docletArtifact> <groupId>nl.amis.hr</groupId> <artifactId>Model</artifactId> <version>1.0-SNAPSHOT</version> </docletArtifact> <docletArtifact> <groupId>com.sun.jersey.contribs</groupId> <artifactId>wadl-resourcedoc-doclet</artifactId> <version>1.17.1</version> </docletArtifact> <docletArtifact> <groupId>com.sun.jersey</groupId> <artifactId>jersey-server</artifactId> <version>1.17.1</version> </docletArtifact> <docletArtifact> <groupId>xerces</groupId> <artifactId>xercesImpl</artifactId> <version>2.6.1</version> </docletArtifact> </docletArtifacts> <!-- the following option is required as a work around for version 2.5 of the javadoc plugin which will be used by a maven version > 2.0.9 --> <useStandardDocletOptions>false</useStandardDocletOptions> <additionalparam>-output ${project.build.outputDirectory}/resourcedoc.xml</additionalparam> </configuration> </plugin> 

here is a complete example on github https://github.com/biemond/JDeveloper12c_12.1.2/tree/master/RestFulOWSM/WebService