wadl2java Tool Documentation
General
The current release of this tool will generate a java client based on the provided WADL that maks use of the Jersey 1.x and JAX-RS 2.0 client API. Future versions of the tool will generate clients for JAX-RS 2.0 proxy bsaed clients.
The default generation style is jersey1x
but you can generate
JAX-RS 2.0 compatible code by setting this to be jaxrs20
When analyzing the WADL the generator will produce one class per WADL root resource. You can override the uri at deploy time by creating a jax-rs-catalog.xml file under META-INF.
<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <uri name="api.search.yahoo.com/NewsSearchService/V1/" uri="qa.example.com/mock/resource"/> </catalog>
Command Line Usage
Execute the wadl2java
tools as follows:
wadl2java -o outputDir -p package [-a] [-s jaxrs20] [-c customization]* file.wadl
where:
-o outputDir
- specifies the directory into which generated source code will be written, the directory must already exist
-p package
- specifies the Java package name in which generated code will reside
-a
- turns on automatic package name generation for schema files. If not specified, all generated code goes into
package
. If specified, each schema namespace name is mapped to a package name and classes generated for elements and types in that namespace are generated in their own package -c customization
- is the path or URL of a JAXB binding customization file (zero or more customization files can be specified)
-s jaxrs20
- Specifies the generation style for the code, defaults to jersey1x
file.wadl
- is the path or URL of the WADL file to process
For example:
wadl2java -o gen-src -p com.example.service example.com/service.wadl
Would process the WADL file at example.com/service.wadl
and generate Java source code in the directory ./gen-src/com/example/service
.
Apache Ant Plug-in Task Usage
Include wadl2java
as a build step in an Apache Ant build script as follows:
<property name="wadl2java.project" value="path/to/wadl2java" /> <taskdef name="wjc" classname="org.jvnet.ws.wadl2java.WJCTask"> <classpath> <fileset dir="${wadl2java.project}/lib" includes="*.jar" excludes="wadl-cmdline*.jar"/> </classpath> </taskdef> <target name="-pre-compile"> <echo message="Compiling the description..." /> <wjc description="file.wadl" package="package" autoSchemaPackage="true|false" target="outputDir"> <customizations dir="." includes="customization" /> <produces dir="outputDir" includes="**/*.java" /> <depends dir="." includes="*.xsd"/> <depends dir="." includes="build.xml"/> <depends dir="${wadl2java.project}" includes="wadl2java.jar"/> <customClassName uri="api.search.yahoo.com/NewsSearchService/V1/" classname="YahooNews" /> </wjc> </target>
where outputDir
, package
, customization
and file.wadl
are as specified above.
The Ant plug-in task has additional capabilities not provided with the command line tool: before the WADL file is processed it compares the modification dates of file.wadl
, package
and any file listed in a child <depends>
element to the modification dates of any files listed in a child <produces>
element. If any of the former are more recent that the oldest of the latter then file.wadl
is processed, otherwise processing is skipped, this means that the tool will only run when its deemed necessary. In the example above, the tool will only run when the WADL file, the customization file, one of the imported schemas, the build script or the wadl2java
tool is modified.
The style of the generated proxy is controlled using the <generationStyle>
element under the wjc element.
Maven Plug-in Usage
In order to use the Maven support, you first of all need to tell Maven about a couple of additional Maven repositories; otherwise it won't be able to automatically download the plugin and its dependencies.
Once you have done that, generating sources from a WADL file is as
easy as calling mvn wadl:generate
. By default, it will
expect the WADL files to reside in src/main/wadl
, but
this is one of the properties you can override.
Note that the plugin will automatically register the
generated sources to be included in the compilation phase. So, if
you register the plugin for the generate-sources
phase
(as in the example below), then the only thing you have to do is
call mvn compile
; this will generate the sources and
compile them in a single pass.
Find a sample configuration below. Note that this example is part of the distribution.
<?xml version="1.0"?> <project> <modelVersion>4.0.0</modelVersion> <groupId>com.yahoo.search</groupId> <artifactId>search-api</artifactId> <version>1.1-SNAPSHOT</version> <name>Yahoo Search API</name> <repositories> <repository> <id>wadl-repository</id> <name>WADL Maven Repository</name> <url>https://wadl.dev.java.net/nonav/repository/</url> </repository> <repository> <id>maven2-repository.dev.java.net</id> <name>Java.net Repository for Maven</name> <url>download.java.net/maven/2/</url> </repository> <repository> <id>wadl-snapshots</id> <name>WADL Snapshots Repository</name> <url>https://wadl.dev.java.net/nonav/snapshots</url> <snapshots> <enabled>true</enabled> </snapshots> <releases> <enabled>false</enabled> </releases> </repository> </repositories> <pluginRepositories> <pluginRepository> <id>wadl-snapshots</id> <name>WADL Snapshots Repository</name> <url>https://wadl.dev.java.net/nonav/snapshots</url> <snapshots> <enabled>true</enabled> </snapshots> <releases> <enabled>false</enabled> </releases> </pluginRepository> </pluginRepositories> <dependencies> <dependency> <groupId>org.jvnet.ws.wadl</groupId> <artifactId>wadl-core</artifactId> <version>1.1.2</version> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-compiler-plugin</artifactId> <configuration> <source>1.5</source> <target>1.5</target> </configuration> </plugin> <plugin> <groupId>org.jvnet.ws.wadl</groupId> <artifactId>wadl-client-plugin</artifactId> <version>1.1.2</version> <executions> <execution> <goals> <goal>generate</goal> </goals> </execution> </executions> <configuration> <sourceDirectory>../share</sourceDirectory> <packageName>com.yahoo.search</packageName> <autopackaging>true</autopackaging> <customizations> <customization>../share/binding.xjb</customization> </customizations> <customClassNames> <property> <name>api.search.yahoo.com/NewsSearchService/V1/</name> <value>YahooNews</value> </property> </customClassNames> </configuration> </plugin> </plugins> </build> </project>
The style of the generated proxy is controlled using the <generationStyle>
element under the configuration element.