JBossWS - wsconsume

    wsconsume is a command line tool and ant task that "consumes" the abstract contract (WSDL file) and produces portable JAX-WS service and client artifacts. For a more detailed overview, see "Using wsconsume".

    Command Line Tool

    The command line tool has the following usage:

    usage: wsconsume [options] <wsdl-url>
    options: 
      -h, --help                  Show this help message
      -b, --binding=<file>        One or more JAX-WS or JAXB binding files
      -k, --keep                  Keep/Generate Java source
      -c  --catalog=<file>        Oasis XML Catalog file for entity resolution
      -p  --package=<name>        The target package for generated source
      -w  --wsdlLocation=<loc>    Value to use for @WebServiceClient.wsdlLocation
      -o, --output=<directory>    The directory to put generated artifacts
      -s, --source=<directory>    The directory to put Java source
      -t, --target=<2.0|2.1|2.2>  The JAX-WS specification target
      -q, --quiet                 Be somewhat more quiet
      -v, --verbose               Show full exception stack traces
      -l, --load-consumer         Load the consumer and exit (debug utility)
      -e, --extension             Enable SOAP 1.2 binding extension
      -a, --additionalHeaders     Enables processing of implicit SOAP headers

     

    Note : The wsdlLocation is used when creating the Service to be used by clients and will be added to the @WebServiceClient annotation, for an endpoint implementation based on the generated service endpoint interface you will need to manually add the wsdlLocation to the @WebService annotation on your web service implementation and not the service endpoint interface.

    Examples

    Generate artifacts in Java class form only:

    wsconsume Example.wsdl
    

    Generate source and class files:

    wsconsume -k Example.wsdl
    

    Generate source and class files in a custom directory:

    wsconsume -k -o custom Example.wsdl
    

    Generate source and class files in the org.foo package:

    wsconsume -k -p org.foo Example.wsdl
    

    Generate source and class files using multiple binding files:

    wsconsume -k -b wsdl-binding.xml -b schema1-binding.xml -b schema2-binding.xml

    Maven Plugin

    The wsconsume tools is included in the org.jboss.ws.plugins:maven-jaxws-tools-plugin plugin. The plugin has two goals for running the tool, wsconsume and wsconsume-test, which basically do the same during different maven build phases (the former triggers the sources generation during generate-sources phase, the latter during the generate-test-sources one).

    The wsconsume plugin has the following parameters:

    AttributeDescriptionDefault
    bindingFilesJAXWS or JAXB binding filetrue
    classpathElements

    Each classpathElement provides a

    library file to be added to classpath

    ${project.compileClasspathElements}

    or

    ${project.testClasspathElements}

    catalogOasis XML Catalog file for entity resolutionnone
    targetPackageThe target Java package for generated code.generated
    bindingFilesOne or more JAX-WS or JAXB binding filenone
    wsdlLocationValue to use for @WebServiceClient.wsdlLocationgenerated
    outputDirectoryThe output directory for generated artifacts.

    ${project.build.outputDirectory}

    or

    ${project.build.testOutputDirectory}

    sourceDirectoryThe output directory for Java source.${project.build.directory}/wsconsume/java
    verboseEnables more informational output about command progress.false
    wsdlsThe WSDL files or URLs to consumen/a
    extensionEnable SOAP 1.2 binding extension.false
    argLine

    An optional additional argline to be used when running in fork mode;

    can be used to set endorse dir, enable debugging, etc.


    Example

    <argLine>-Djava.endorsed.dirs=...</argLine>

    none
    forkWhether or not to run the generation task in a separate VMfalse
    targetA preference for the JAX-WS specification targetDepends on the underlying stack and endorsed dirs if any

    Examples

    You can use wsconsume in your own project build simply referencing the maven-jaxws-tools-plugin in the configured plugins in your pom.xml file.

    The following example makes the plugin consume the test.wsdl file and generate SEI and wrappers' java sources. The generated sources are then compiled together with the other project classes.

    <build>
      <plugins>
        <plugin>
          <groupId>org.jboss.ws.plugins</groupId>
          <artifactId>maven-jaxws-tools-plugin</artifactId>
          <version>1.0.0.GA</version>
          <configuration>
            <wsdls>
              <wsdl>${basedir}/test.wsdl</wsdl>
            </wsdls>
          </configuration>
          <executions>
            <execution>
              <goals>
                <goal>wsconsume</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
    

     

    You can also specify multiple wsdl files, as well as force the target package, enable SOAP 1.2 binding and turn the tool's verbose mode on:

     

    <build>
      <plugins>
        <plugin>
          <groupId>org.jboss.ws.plugins</groupId>
          <artifactId>maven-jaxws-tools-plugin</artifactId>
          <version>1.0.0.GA</version>
          <configuration>
            <wsdls>
              <wsdl>${basedir}/test.wsdl</wsdl>
              <wsdl>${basedir}/test2.wsdl</wsdl>
            </wsdls>
            <targetPackage>foo.bar</targetPackage>
            <extension>true</extension>
            <verbose>true</verbose>
          </configuration>
          <executions>
            <execution>
              <goals>
                <goal>wsconsume</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
    

     

    Finally, if the wsconsume invocation is required for consuming a wsdl to be used in your testsuite only, you might want to use the wsconsume-test goal as follows:

     

    <build>
      <plugins>
        <plugin>
          <groupId>org.jboss.ws.plugins</groupId>
          <artifactId>maven-jaxws-tools-plugin</artifactId>
          <version>1.0.0.GA</version>
          <configuration>
            <wsdls>
              <wsdl>${basedir}/test.wsdl</wsdl>
            </wsdls>
          </configuration>
          <executions>
            <execution>
              <goals>
                <goal>wsconsume-test</goal>
              </goals>
            </execution>
          </executions>
        </plugin>
      </plugins>
    </build>
    

    Ant Task

     

    Note

    With 2.0.GA the task was renamed to org.jboss.wsf.spi.tools.ant.WSConsumeTask.

     

    Note

    With 4.0.GA the task was renamed to org.jboss.ws.tools.ant.WSConsumeTask.

     

    Note

    Users also need to put streamBuffer.jar and stax-ex.jar to the classpath of the ant task to generate the appropriate artefacts.

     

    To use the task, you will first need to make it available with something like

     

    <taskdef name="wsconsume" classname="org.jboss.wsf.spi.tools.ant.WSConsumeTask">

        <classpath>

            <pathelement location="${path_to_jboss}/client/jbossws-spi.jar" />

            <pathelement location="${path_to_jboss}/client/jbossws-native-core.jar" />

            <pathelement location="${path_to_jboss}/client/jbossws-common.jar" />

            <pathelement location="${path_to_jboss}/client/jaxws-tools.jar" />

            <pathelement location="${path_to_jboss}/client/wstx.jar"/>

        </classpath>

    </taskdef>

     

     

    The wsconsume ant task has the following attributes:

    AttributeDescriptionDefault
    forkWhether or not to run the generation task in a separate VM.true
    keepKeep/Enable Java source code generation.false
    catalogOasis XML Catalog file for entity resolutionnone
    packageThe target Java package for generated code.generated
    bindingA JAX-WS or JAXB binding filenone
    wsdlLocationValue to use for @WebServiceClient.wsdlLocationgenerated
    destdirThe output directory for generated artifacts."output"
    sourcedestdirThe output directory for Java source.value of destdir
    targetThe JAX-WS specification target. Allowed values are 2.0, 2.1 and 2.2
    verboseEnables more informational output about command progress.false
    wsdlThe WSDL file or URLn/a
    extensionEnable SOAP 1.2 binding extension.

    false

    additionalHeadersEnables processing of implicit SOAP headersfalse

    Note : The wsdlLocation is used when creating the Service to be used by clients and will be added to the @WebServiceClient annotation, for an endpoint implementation based on the generated service endpoint interface you will need to manually add the wsdlLocation to the @WebService annotation on your web service implementation and not the service endpoint interface.

     

    Also, the following nested elements are supported:

    ElementDescriptionDefault
    bindingA JAXWS or JAXB binding filenone
    jvmargAllows setting of custom jvm arguments

     

    Examples

    Generate JAX-WS source and classes in a separate JVM with separate directories, a custom wsdl location attribute, and a list of binding files from foo.wsdl:

    <wsconsume 
      fork="true"
      verbose="true"
      destdir="output"
      sourcedestdir="gen-src"
      keep="true"
      wsdllocation="handEdited.wsdl" 
      wsdl="foo.wsdl">
      <binding dir="binding-files" includes="*.xml" excludes="bad.xml"/>
    </wsconsume>