Tools

The following lists the process to create a web service starting from Java sources, classes, and a WSDL file (server side):

The following lists the process to invoke a web service (client side):

You can use all jaxws tools within your maven build. Information about maven plugin and its usage is located at the plugin homepage.

The wsimport tool generates Jakarta XML Web Services portable artifacts, such as:

These artifacts can be packaged in a WAR file with the WSDL and schema documents along with the endpoint implementation to be deployed. Eclipse Implementation of XML Web Services 4.0.0 also provides a wsimport Ant Task.

The following table lists the wsimport options:

Multiple Jakarta XML Web Services and Jakarta XML Binding binding files can be specified using -b option and they can be used to customize various things like package names, bean names, etc. More information on Jakarta XML Web Services and Jakarta XML Binding binding files can be found in the WSDL Customization.

wsimport -p stockquote http://stockquote.xyz/quote?wsdl

This will generate the Java artifacts and compile them by importing the http://stockquote.xyz/quote?wsdl.

The wsimport generates Jakarta XML Web Services portable artifacts, such as:

To use this wsimport task, a <taskdef> element needs to be added to the project as given below:

<taskdef name="wsimport" classname="com.sun.tools.ws.ant.WsImport">
    <classpath path="jaxws.classpath"/>
</taskdef>

where jaxws.classpath is a reference to a path-like structure, defined elsewhere in the build environment, and contains the list of classes required by the Jakarta XML Web Services tools.

<wsimport
        wsdl="..."
        destdir="directory for generated class files"
        sourcedestdir="directory for generated source files"
        keep="true|false"
        disableXmlSecurity="true|false"
        encoding="..."
        extension="true|false"
        verbose="true|false"
        wsdlLocation="..."
        clientJar="jar file"
        catalog="catalog file"
        package="package name"
        target="target release"
        binding="..."
        quiet="true|false"
        fork="true|false"
        failonerror="true|false"
        xadditionalHeaders="true|false"
        xauthfile="authorization file"
        xdisableAuthenticator="true|false"
        xdebug="true|false"
        xNoAddressingDatabinding="true|false"
        xnocompile="true|false">
    <binding dir="..." includes="..."/>
    <arg value="..."/>
    <xjcarg value="..."/>
    <javacarg value="..."/>
    <jvmarg value="..."/>
    <xmlcatalog refid="another catalog file"/>
    <depends file="..."/>
    <produces dir="..."/>
</wsimport>

<wsimport
        destdir="${build.classes.home}"
        debug="true"
        wsdl="AddNumbers.wsdl"
        binding="custom.xml"/>

The above example generates client-side artifacts for AddNumbers.wsdl, stores .class files in the ${build.classes.home} directory using the custom.xml customization file. The classpath used is xyz.jar and compiles with debug information on.

<wsimport
        keep="true"
        sourcedestdir="${source.dir}"
        destdir="${build.classes.home}"
        extension="true"
        wsdl="AddNumbers.wsdl">
    <xjcarg value="-cp"/>
    <xjcarg file="path/to/fluent-api.jar" />
    <xjcarg value="-Xfluent-api"/>
</wsimport>

The above example shows how to generates artifacts for AddNumbers.wsdl while passing options to Jakarta XML Binding xjc tool for XML Schema to Java compilation using your Jakarta XML Binding plugin. Note extension attribute which is set to true. You need to set this to use Jakarta XML Binding plugins.

Multiple Jakarta XML Web Services and Jakarta XML Binding binding files can be specified using -b option and they can be used to customize various things like package names, bean names, etc. More information on Jakarta XML Web Services and Jakarta XML Binding binding files can be found in the WSDL Customization.

The wsgen tool generates Jakarta XML Web Services portable artifacts used in Jakarta XML Web Services web services. The tool reads a web service endpoint class and generates all the required artifacts for web service deployment, and invocation. Eclipse Implementation of XML Web Services 4.0.0 also provides a wsgen Ant Task.

The following table lists the wsgen options:

-servicename "{http://mynamespace/}MyService"

-portname "{http://mynamespace/}MyPort"

wsgen -d stock -cp myclasspath stock.StockService

This will generate the wrapper classes needed for StockService annotated with @WebService annotation inside the stock directory.

wsgen -wsdl -d stock -cp myclasspath stock.StockService

This will generate a SOAP 1.1 WSDL and schema for your Java class stock.StockService annotated with @WebService annotation.

wsgen -wsdl:Xsoap1.2 -d stock -cp myclasspath stock.StockService

Will generate a SOAP 1.2 WSDL.

wsgen generates Jakarta XML Web Services portable artifacts used in Jakarta XML Web Services web services. The tool reads a web service endpoint class and generates all the required artifacts for web service deployment, and invocation.

Before this task can be used, a <taskdef> element needs to be added to the project as given below:

<taskdef name="wsgen" classname="com.sun.tools.ws.ant.WsGen">
    <classpath path="jaxws.classpath"/>
</taskdef>

where jaxws.classpath is a reference to a path-like structure, defined elsewhere in the build environment, and contains the list of classes required by the Eclipse Implementation of XML Web Services tools.

<wsgen
        sei="..."
        destdir="directory for generated class files"
        classpath="classpath" | cp="classpath"
        resourcedestdir="directory for generated resource files such as WSDLs"
        sourcedestdir="directory for generated source files"
        keep="true|false"
        encoding="..."
        verbose="true|false"
        genwsdl="true|false"
        protocol="soap1.1|Xsoap1.2"
        servicename="..."
        portname="..."
        disableXmlSecurity="true|false"
        extension="true|false"
        inlineSchemas="true|false"
        fork="true|false"
        failonerror="true|false"
        xnocompile="true|false"
        xnosource="true|false">
    <classpath refid="..."/>
    <externalmetadata file="..."/>
    <javacarg value="..."/>
    <jvmarg value="..."/>
</wsgen>

servicename="{http://mynamespace/}MyService"

portname="{http://mynamespace/}MyPort"

<wsgen
        resourcedestdir="${wsdl.dir}"
        sei="fromjava.server.AddNumbersImpl">
    <classpath refid="compile.classpath"/>
    <external-metadata file="metadata-AddNumbersImpl.xml"/>
</wsgen>

As an improvement for the apt Pluggable Annotation Processing API was introduced in Java SE 6. It provides an API to allow the processing of JSR 175 annotations (metadata); this will require modeling elements of the Java TM programming language as well as processing-specific functionality.

The javac generates the portable artifacts used in Jakarta XML Web Services services.

The following table lists the javac options useful for annotation processing:

More options and detailed information on javac can be found here.

It is important when using javac with Jakarta XML Web Services to specify all of the JAR files in the distributed Jakarta XML Web Services bundle in the classpath passed to javac. As Jakarta XML Web Services annotation processor you have to specify com.sun.tools.ws.processor.modeler.annotation.WebServiceAp. The -sourcepath <path> option must also be provided so that javac and the Jakarta XML Web Services annotation processor can find all types referenced by a web service endpoint implementation class. In case you don't have additional annotation processors it's recommended to use annotationProcessing Ant Task.

An Ant task for the annotationProcessing is provided with Eclipse Implementation of XML Web Services 4.0.0.

The attributes and elements supported by the Ant task almost the same as for the javac ant task. With only one restriction: by default jax-ws annotation processor will be used. There several additional attributes for usability improvement:

The list of source files to be processed are specified via a nested <srcdir> element. That is, a path-like structure. The classpath attribute is a path-like structure and can also be set via nested <classpath> elements. Before this task can be used, a <taskdef> element needs to be added to the project as given below:

<taskdef name="annotationProcessing"
        classname="com.sun.tools.ws.ant.AnnotationProcessingTask">
    <classpath refid="jaxws.classpath"/>
</taskdef>

where jaxws.classpath is a reference to a path-like structure, defined elsewhere in the build environment, and contains the list of classes required by the Jakarta XML Web Services tools.

<annotationProcessing
        destdir="${build.classes.home}"
        sourceDestDir="${build.classes.home}"
        srcdir="${basedir}/src"
        includes="*.java"
        sourcepath="${basedir}/src">
    <classpath refid="jaxws.classpath"/>
</annotationProcessing>

The above example processes the Java source files in the ${basedir}/src directory and generates the source and class files in ${build.classes.home}. ${basedir}/src is directory used to search for source files for multiple annotationProcessing rounds. The classpath is a reference to a path-like structure jaxws.classpath, defined elsewhere in the build environment.

<annotationProcessing
        debug="true"
        verbose="true"
        destdir="${build.classes.home}"
        srcdir="${basedir}/src""
        includes="**/server/*.java"
        sourceDestDir="${build.classes.home}"
        sourcepath="${basedir}/src">
    <classpath refid="jaxws.classpath"/>
</annotationProcessing>

The above example processes the Java source files in ${basedir}/src/**/server, generates the source and class files in ${build.classes.home}, compiles with debug information on, prints a message about what the compiler is doing. ${basedir}/src is the directory used to search for source files for multiple annotationProcessing rounds. The classpath is a reference to a path-like structure jaxws.classpath, defined elsewhere in the build environment. This will also fork off the annotationProcessing process using the default java executable.

For backwards compatibility Apt Ant task still exists, but is marked as deprecated, and can be used with certain restrictions.