wadl2java Tool Documentation

General

The current release of this tool will generate a java client based on the provided WADL that makes 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.x proxy based clients when this is standardized.

The default generation style is jersey1x but you can generate Jersey 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="http://api.search.yahoo.com/NewsSearchService/V1/"
          uri="http://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 http://example.com/service.wadl

Would process the WADL file at http://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="http://www.bbc.co.uk" classname="BBCSchedule" />
  </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>bbc.schedule</groupId>
  <artifactId>schedule-api</artifactId>
  <version>1.1-SNAPSHOT</version>
  <name>BBC Schedule 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>http://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.6</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-compiler-plugin</artifactId>
        <configuration>
          <source>1.6</source>
          <target>1.6</target>
        </configuration>
      </plugin>
      <plugin>
        <groupId>org.jvnet.ws.wadl</groupId>
        <artifactId>wadl-client-plugin</artifactId>
        <version>1.1.6</version>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <sourceDirectory>../share</sourceDirectory>
          <packageName>bbc.schedule</packageName>
          <autopackaging>false</autopackaging>
          <customizations>
            <customization>../share/binding.xjb</customization>
          </customizations>
          <customClassNames>
            <property>
              <name>http://www.bbc.co.uk</name>
              <value>BBCSchedule</value>
            </property>
         </customClassNames>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

The style of the generated proxy is controlled using the <generationStyle> element under the configuration element.

Terms of Use; Privacy Policy; Copyright ©2013-2014 (revision 20140418.2d69abc)
 
 
Close
loading
Please Confirm
Close