wadl2java Tool Documentation

Command Line Usage

Execute the wadl2java tools as follows:

wadl2java -o outputDir -p package [-a] [-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)
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"/>
  </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.

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>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-SNAPSHOT</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-maven-plugin</artifactId>
        <version>1.1-SNAPSHOT</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>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>