Skip to end of metadata
Go to start of metadata

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.

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
  -j  --clientjar=<name>      Create a jar file of the generated artifacts for calling the webservice
  -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.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
  -d, --encoding=<charset>    The charset encoding to use for generated sources
  -n, --nocompile             Do not compile generated sources


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:jaxws-tools-maven-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:

Attribute Description Default
bindingFiles JAXWS or JAXB binding file true
classpathElements Each classpathElement provides a
library file to be added to classpath
${project.compileClasspathElements}
or
${project.testClasspathElements}
catalog Oasis XML Catalog file for entity resolution none
targetPackage The target Java package for generated code. generated
bindingFiles One or more JAX-WS or JAXB binding file none
wsdlLocation Value to use for @WebServiceClient.wsdlLocation generated
outputDirectory The output directory for generated artifacts.
${project.build.outputDirectory}
or
${project.build.testOutputDirectory}
sourceDirectory The output directory for Java source.
${project.build.directory}/generated-sources/wsconsume
verbose Enables more informational output about command progress. false
wsdls The WSDL files or URLs to consume n/a
extension Enable SOAP 1.2 binding extension. false
encoding The charset encoding to use for generated sources.
${project.build.sourceEncoding}
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
fork Whether or not to run the generation task in a separate VM.
false
target A preference for the JAX-WS specification target Depends on the underlying stack and endorsed dirs if any

Examples

You can use wsconsume in your own project build simply referencing the jaxws-tools-maven-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.

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:

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:

Plugin stack dependencyThe plugin itself does not have an explicit dependency to a JBossWS stack, as it's meant for being used with implementations of any supported version of the JBossWS SPI. So the user is expected to set a dependency in his own pom.xml to the desired JBossWS stack version. The plugin will rely on the that for using the proper tooling.

Be careful when using this plugin with the Maven War Plugin as that include any project dependency into the generated application war archive. You might want to set <scope>provided</scope> for the JBossWS stack dependency to avoid that.
Up to version 1.1.2.Final, the artifactId of the plugin was maven-jaxws-tools-plugin.

Ant Task

 The wsconsume Ant task (org.jboss.ws.tools.ant.WSConsumeTask) has the following attributes:

Attribute Description Default
fork Whether or not to run the generation task in a separate VM. true
keep Keep/Enable Java source code generation. false
catalog Oasis XML Catalog file for entity resolution none
package The target Java package for generated code. generated
binding A JAX-WS or JAXB binding file none
wsdlLocation Value to use for @WebServiceClient.wsdlLocation generated
encoding The charset encoding to use for generated sources n/a
destdir The output directory for generated artifacts. "output"
sourcedestdir The output directory for Java source. value of destdir
target The JAX-WS specification target. Allowed values are 2.0, 2.1 and 2.2  
verbose Enables more informational output about command progress. false
wsdl The WSDL file or URL n/a
extension Enable SOAP 1.2 binding extension. false
additionalHeaders Enables processing of implicit SOAP headers false
Users also need to put streamBuffer.jar and stax-ex.jar to the classpath of the ant task to generate the appropriate artefacts.
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:

Element Description Default
binding A JAXWS or JAXB binding file none
jvmarg Allows 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:

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Dec 07, 2012

    I also had to add

    <dependency>
                <groupId>org.apache.ws.xmlschema</groupId>
                <artifactId>xmlschema-core</artifactId>
                <scope>provided</scope>
    </dependency>

    to the Maven dependencies.

    Otherwise I get:

    Failed to invoke JavaToWS
    java.lang.NoClassDefFoundError: org/apache/ws/commons/schema/resolver/URIResolver

  2. Dec 10, 2012

    Strange, xmlschema-core should be pulled in as a transitive dependency of cxf-api and hence jbossws-cxf-client.

  3. Aug 22, 2013

    Instructions here doesn't work. I always get an error. Which version is the right version to use?

    Error:

    [ERROR] Failed to execute goal on project test-ws: Could not resolve dependencies for project au.com.example.webservice:test-ws:jar:0.0.1-SNAPSHOT: Failure to find org.jboss.ws.cxf:jbossws-cxf-client:jar:4.0.0.GA in http://repo.maven.apache.org/maven2 was cached in the local repository, resolution will not be reattempted until the update interval of central has elapsed or updates are forced -> [Help 1]
    [
    [ERROR] Failed to execute goal on project test-ws: Could not resolve dependencies for project au.com.example.webservice:test-ws:jar:0.0.1-SNAPSHOT: Failure to find org.jboss.ws.cxf:jbossws-cxf-client:jar:4.0.0.GA in http://repo.maven.apache.org/maven2 was cached in the local repository, resolution will not be reattempted until the update interval of central has elapsed or updates are forced -> [Help 1]

    1. Aug 22, 2013

      You most likely didn't configure the Maven repository properly. See e.g. https://community.jboss.org/wiki/JBossWS-Mavenization#Create_or_Update_Maven_Settings_JBoss_Nexus_Maven_Repository

      Alternatively, move to at least JBossWS 4.1.0.Final, whose artifacts are available on Maven Central repository too.

      1. Aug 22, 2013

        Thanks, it worked when i added the repositories of jboss to my POM. 

        But when I tried to change the jbossws-cxf-client version to 4.1.0.Final there were errors. What version should i use for maven-jaxws-tools-plugin? 

        [ERROR] Failed to execute goal org.jboss.ws.plugins:maven-jaxws-tools-plugin:1.1.0.GA:wsconsume (default) on project test-ws: Error while running wsconsume: org.jboss.ws.api.tools.WSContractConsumer -> [Help 1]