Links: Table of Contents | Single HTML | Single PDF

Tools

1. Overview

1.1. How do I pick a tool?

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

  1. Starting from Java sources:

    1. Use annotationProcessing Ant task to generate the artifacts required by the JAX-WS specification.

    2. Package the web.xml, sun-jaxws.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file,

    3. Deploy the WAR to a web container.

  2. Starting from Java classes:

    1. Use wsgen to generate portable artifacts.

    2. Package the web.xml, sun-jaxws.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file,

    3. Deploy the WAR to a web container.

  3. Starting from a WSDL file:

    1. Use wsimport to generate portable artifacts.

    2. Implement the service endpoint.

    3. Package the WSDL file, schema documents, web.xml, sun-jaxws.xml, service endpoint interface and implementation class, value types, and generated classes, if any, into a WAR file.

    4. Deploy the WAR to a web container.

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

  1. Starting from deployed web service's WSDL

    1. Use wsimport to generate the client-side artifacts.

    2. Implement the client to invoke the web service.

1.2. Running tools on JDK6

  • Copy JAXWS_HOME/lib/jaxws-api.jar to $JDK6_HOME/jre/lib/endorsed directory

  • Copy JAXWS_HOME/lib/jaxb-api.jar to $JDK6_HOME/jre/lib/endorsed directory

For details see Endorsed Directory Mechanism. Above, JAXWS_HOME points to the root directory of the extracted JAX-WS RI bundle. JDK6_HOME points to JDK 6 installation directory.

1.3. Maven plugins

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

2. wsimport

2.1. wsimport Overview

The wsimport tool generates JAX-WS portable artifacts, such as:

  • Service Endpoint Interface (SEI)

  • Service

  • Exception class mapped from wsdl:fault (if any)

  • Async Reponse Bean derived from response wsdl:message (if any)

  • JAXB generated value types (mapped java classes from schema types)

These artifacts can be packaged in a WAR file with the WSDL and schema documents along with the endpoint implementation to be deployed. JAX-WS RI 2.2.7 also provides a wsimport Ant Task.

2.2. Launching wsimport

  • Solaris/Linux

    • JAXWS_HOME/bin/wsimport.sh -help
  • Windows

    • JAXWS_HOME\bin\wsimport.bat -help

2.3. Running wsimport on JDK 6

To run on JDK 6 follow these Running tools on JDK6.

2.4. wsimport Syntax

wsimport [OPTION]... <WSDL>

The following table lists the wsimport options:

OptionDescription
-d <directory>Specify where to place generated output files.
-b <path>Specify external JAX-WS or JAXB binding files or additional schema files (Each <file> must have its own -b).
-B <jaxbOption>Pass this option to JAXB schema compiler.
-catalogSpecify catalog file to resolve external entity references, it supports TR9401, XCatalog, and OASIS XML Catalog format. Please read the documentation of Catalog and see catalog sample.
-extensionAllow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.
-helpDisplay help.
-httpproxy:<host>:<port>Specify an HTTP proxy server (port defaults to 8080).
-keepKeep generated source code files. It is enabled when -s option.
-p <pkg>Specifying a target package via this command-line option, overrides any wsdl and schema binding customization for package name and the default package name algorithm defined in the specification.
-s <directory>Specify where to place generated source code files. keep is turned on with this option.
-encoding <encoding>Set the encoding name for generated sources, such as EUC-JP or UTF-8. If -encoding is not specified, the platform default encoding is used.
-verboseOutput messages about what the compiler is doing.
-versionPrint version information.
-fullversionPrint full version information.
-clientjar <jarfile>Creates the jar file of the generated artifacts along with the WSDL metadata required for invoking the web service.
-wsdllocation <location>@WebServiceClient.wsdlLocation value.
-target <version>Generate code as per the given JAX-WS specification version. For example, "-target 2.0" generates compliant code for JAX-WS 2.0 spec. Default value is 2.2.
-quietSuppress wsimport output.
-XadditionalHeadersMap the headers not bound to request or response message to Java method parameters.
-XauthfileFile to carry authorization information in the format http://username:password@example.org/stock?wsdl. Default value is $HOME/.metro/auth
-XdebugPrint debug information.
-XdisableAuthenticatorDisables Authenticator used by JAX-WS RI, -Xauthfile option will be ignored if -XdisableAuthenticator is set.
-Xno-addressing-databindingEnable binding of W3C EndpointReferenceType to Java.
-XnocompileDo not compile generated Java files.
-XdisableSSLHostnameVerificationDisbales the SSL Hostname verification while fetching the wsdls.

Multiple JAX-WS and JAXB 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 JAX-WS and JAXB binding files can be found in the WSDL Customization.

2.5. wsimport Example

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.

3. wsimport Ant Task

3.1. wsimport Task Overview

The wsimport generates JAX-WS portable artifacts, such as:

  • Service Endpoint Interface (SEI)

  • Service

  • Exception class mapped from wsdl:fault (if any)

  • Async Reponse Bean derived from response wsdl:message (if any)

  • JAXB generated value types (mapped java classes from schema types)

3.2. Using wsimport Task

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 JAX-WS tools.

<wsimport
        wsdl="..."
        destdir="directory for generated class files"
        sourcedestdir="directory for generated source files"
        keep="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"
        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="..."/>
    <xmlcatalog refid="another catalog file"/>
</wsimport>

3.2.1. Environment Variables

  • ANT_OPTS - command-line arguments that should be passed to the JVM. For example, you can define system properties or set the maximum Java heap size here.

3.2.2. Parameter Attributes

wsimport supports the following parameter attributes.

AttributeDescriptionRequiredCommand line
wsdlWSDL file.Yes.WSDL location
destdirSpecify where to place output generated classes.No. Defaults to current working directory.-d
sourcedestdirSpecify where to place generated source code files, keep is turned on with this option.No. Defaults to current working directory.-s
encodingSet the encoding name for generated sources, such as UTF-8.No. Defaults to platform default.-encoding
keepKeep generated source code files, turned on with sourcedestdir option.No. Defaults to false.-keep
verboseOutput JAX-WS RI version and messages about what the compiler is doingNo. Defaults to false.-verbose.
bindingSpecify external JAX-WS or JAXB binding files or additional schema files (Each <file> must have its own -b).No. No defaults.-b
extensionallow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.No. Defaults to false.-extension
wsdllocationThe wsdl URI passed thru this option will be used to set the value of @WebService.wsdlLocation and @WebServiceClient.wsdlLocation annotation elements on the generated SEI and Service interface.No. Defaults to the wsdl URL passed to wsdl attribute.-wsdllocation
clientJarCreates the jar file of the generated artifacts along with the WSDL metadata required for invoking the web service.No.-clientJar
catalogSpecify catalog file to resolve external entity references, it supports TR9401, XCatalog, and OASIS XML Catalog format. Additionally, ant xmlcatalog type can be used to resolve entities, see catalog sample and Catalog.No. No defaults.-catalog
packageSpecifies the target package.No. It default to the WSDL/Schema targetNamespace to package mapping as defined by the JAXB 2.1 spec.-p
targetGenerate code as per the given JAXWS specification version. For example, 2.0 value generates compliant code for JAXWS 2.0 spec.No. Defaults to 2.2.-target
quietSuppress wsimport output.No. Defaults to false.-quiet
xadditionalHeadersMap headers not bound to request or response message to Java method parameters.No. Defaults to false.-XadditionalHeaders
xauthfileFile to carry authorization information in the format http://username:password@example.org/stock?wsdl.No. Defaults to $HOME/.metro/auth.-Xauthfile
xdebugPrint debug information.No. Defaults to false.-Xdebug
xdisableAuthenticatorDisables Authenticator used by JAX-WS RI, -Xauthfile option will be ignored if -XdisableAuthenticator is set.No. Defaults to false.-XdisableAuthenticator
xNoAddressingDatabindingEnable binding of W3C EndpointReferenceType to Java.No. Defaults to false.-Xno-addressing-databinding
xnocompileDo not compile generated Java files.No. Defaults to false.-Xnocompile

3.2.3. Nested Elements

wsimport supports the following nested element parameters.

3.2.3.1. binding

To specify more than one external binding file at the same time, use a nested <binding> element, which has the same syntax as <fileset>.

3.2.3.2. arg

Additional command line arguments passed to the wsimport. For details about the syntax, see the relevant section in the Ant manual. This nested element can be used to specify various options not natively supported in the wsimport Ant task. For example, currently there is no native support for the following wsimport command-line options:

  • -XdisableSSLHostnameVerification

This nested element can be used to pass the -X command-line options directly like "-XadditionalHeaders". To use any of these features from the wsimport Ant task, you must specify the appropriate nested <arg> elements.

3.2.3.3. xjcarg

The usage is similar to <arg> nested element, except that these arguments are directly passed to the XJC tool (JAXB Schema Compiler), which will be used for compiling the schema referenced in the wsdl. For details about the syntax, see the relevant section in the Ant manual.

3.2.3.4. xmlcatalog

The xmlcatalog element is used to resolve entities when parsing schema documents.

3.3. Running wsimport Task on JDK 6

To run on JDK 6 follow these Running tools on JDK6.

3.4. wsimport Examples

<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 JAXB xjc tool for XML Schema to Java compilation using your JAXB plugin. Note extension attribute which is set to true. You need to set this to use JAXB plugins.

Multiple JAX-WS and JAXB 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 JAX-WS and JAXB binding files can be found in the WSDL Customization.

4. wsgen

4.1. wsgen Overview

The wsgen tool generates JAX-WS portable artifacts used in JAX-WS web services. The tool reads a web service endpoint class and generates all the required artifacts for web service deployment, and invocation. JAX-WS RI 2.2.7 also provides a wsgen Ant Task.

4.2. Launching wsgen

  • Solaris/Linux

    • JAXWS_HOME/bin/wsgen.sh -help
  • Windows

    • JAXWS_HOME\bin\wsgen.bat -help

4.3. Running wsgen on JDK 6

To run on JDK 6 follow these Running tools on JDK6.

4.4. wsgen Syntax

wsgen [OPTION]... <SEI>

The following table lists the wsgen options:

OptionDescription
-classpath <path>Specify where to find input class files.
-cp <path>Same as -classpath <path>.
-d <directory>Specify where to place generated output files.
-extensionAllow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.
-helpDisplay help.
-keepKeep generated files.
-r <directory>Used only in conjunction with the -wsdl option. Specify where to place generated resource files such as WSDLs.
-s <directory>Specify where to place generated source files.
-encoding <encoding>Set the encoding name for generated sources, such as EUC-JP or UTF-8. If -encoding is not specified, the platform default encoding is used.
-verboseOutput messages about what the compiler is doing.
-versionPrint version information. Use of this option will ONLY print version information. Normal processing will not occur.
-fullversionPrint full version information. Use of this option will ONLY print version information. Normal processing will not occur.
-wsdl[:protocol]By default wsgen does not generate a WSDL file. This flag is optional and will cause wsgen to generate a WSDL file and is usually only used so that the developer can look at the WSDL before the endpoint is deploy. The protocol is optional and is used to specify what protocol should be used in the wsdl:binding. Valid protocols include: soap1.1 and Xsoap1.2. The default is soap1.1. Xsoap1.2 is not standard and can only be used in conjunction with the -extension option.
-servicename <name>

Used only in conjunction with the -wsdl option. Used to specify a particular wsdl:service name to be generated in the WSDL. Example:

-servicename "{http://mynamespace/}MyService"
-portname <name>

Used only in conjunction with the -wsdl option. Used to specify a particular wsdl:port name to be generated in the WSDL. Example:

-portname "{http://mynamespace/}MyPort"
-inlineSchemasUsed to inline schemas in a generated wsdl. Must be used in conjunction with the -wsdl option.

4.5. wsgen Example

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.

Note

You don't have to generate WSDL at the development time as JAX-WS runtime will automatically generate a WSDL for you when you deploy your service.

5. wsgen Ant Task

5.1. wsgen Task Overview

wsgen generates JAX-WS portable artifacts used in JAX-WS web services. The tool reads a web service endpoint class and generates all the required artifacts for web service deployment, and invocation.

5.2. wsgen Task Attributes

The attributes and elements supported by the Ant task are listed below:

<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="...">
        extension="true|false"
        inlineSchemas="true|false"
    <classpath refid="..."/>
</wsgen>
AttributeDescriptionCommand line
seiName of the service endpoint implementation class.SEI
destdirSpecify where to place output generated classes.-d
classpathSpecify where to find input class files.-classpath
cpSame as -classpath.-cp
resourcedestdirUsed only in conjunction with the -wsdl option. Specify where to place generated resource files such as WSDLs.-r
sourcedestdirSpecify where to place generated source files.-s
encodingSet the encoding name for generated sources, such as UTF-8.-encoding
keepKeep generated files.-keep
verboseOutput JAX_WS RI version and messages about what the compiler is doing.-verbose
genwsdlSpecify that a WSDL file should be generated.-wsdl
protocolUsed in conjunction with genwsdl to specify the protocol to use in the wsdl:binding. Value values are "soap1.1" or "Xsoap1.2", default is "soap1.1". "Xsoap1.2" is not standard and can only be used in conjunction with the -extensions option.-wsdl:soap11
servicename

Used in conjunction with the genwsdl option. Used to specify a particular wsdl:service name for the generated WSDL. Example:

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

Used in conjunction with the genwsdl option. Used to specify a particular wsdl:portname name for the generated WSDL. Example:

portname="{http://mynamespace/}MyPort"
-servicename
extensionAllow vendor extensions (functionality not specified by the specification). Use of extensions may result in applications that are not portable or may not interoperate with other implementations.-extension
inlineSchemasUsed to inline schemas in a generated wsdl. Must be used in conjunction with the wsdl option.-inlineSchemas

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="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 JAX-WS tools.

5.3. Running wsgen Task on JDK 6

To run on JDK 6 follow these Running tools on JDK6.

5.4. wsgen Task Example

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

6. Annotation Processing

6.1. javac annotation processing

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 JAX-WS services.

6.2. javac Annotation Processing Syntax

javac [JAVAC_OPTION]... <SOURCE_FILE>...

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

OptionDescription
-classpath <path> Specifies where to find user class files and annotation processor factories.
-d <path>Specifies where to place processor generated class files.
-s <path>Specifies where to place processor generated source files.
-source <release>Provide source compatibility with the specified release.
-XprintPrint out textual representation of specified types for debugging purposes; perform neither annotation processing nor compilation. The format of the output may change.
-XprintProcessorInfoPrint information about which annotations a processor is asked to process.
-XprintRoundsPrint information about initial and subsequent annotation processing rounds.
-A[key[=value]]Options to pass to annotation processors.
-proc:{none,only}Control whether annotation processing and/or compilation is done.
-sourcepath <path> Specify where to find input source files.
-endorseddirs <dirs> Override location of endorsed standards path.
-processor <class1>[,<class2>...]Names of the annotation processors to run; bypasses default discovery process
-processorpath <path>Specify where to find annotation processors

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

It is important when using javac with JAX-WS to specify all of the JAR files in the distributed JAX-WS bundle in the classpath passed to javac. As JAX-WS 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 JAX-WS 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.

7. annotationProcessing Ant Task

7.1. annotationProcessing Task Overview

An Ant task for the annotationProcessing is provided with JAX-WS RI 2.2.7.

7.2. annotationProcessing Task Attributes

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:

AttributeDescriptionRequired
procOnlyControl whether annotation processing and compilation is done. Can be true or false. Default is false.false
sourcedestdirSpecify where to place processor generated source files. -s <path>true

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 JAX-WS tools.

7.3. annotationProcessing Task Examples

<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.

7.4. Apt Ant task

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

8. apt

The apt tool provided a facility for programmatically processing the annotations added to Java by JSR 175, Metadata Facility for the Java TM Programming Language. In brief, JSR 175 allows programmers to declare new kinds of structured modifiers that can be associated with program elements, fields, methods, classes, etc.

The javac completely replaced functionality provided by apt. It was done within implementation of JSR 269, Pluggable Annotation Processing API. So it's expected programmers to use javac instead of apt.

Using javac with JAX-WS annotation processor will generate portable artifacts used in JAX-WS services.

Be aware that the apt tool and its associated API, com.sun.mirror.\*, are being deprecated in JDK 7.

For more information on this compiler please see Annotation Processing.

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