Tools (original) (raw)

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

• CopyJAXWS_HOME/lib/javax.annotation-api.jar JAXWS_HOME/lib/jsr181-api.jar JAXWS_HOME/lib/jaxws-api.jar 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 fromwsdl:fault (if any)
• Async Reponse Bean derived from responsewsdl: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.3.0-SNAPSHOT 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. wsimport Syntax

wsimport [OPTION]...

The following table lists the wsimport options:

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.4. 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 fromwsdl:fault (if any)
• Async Reponse Bean derived from responsewsdl: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:

where jaxws.classpath is a reference to apath-like structure, defined elsewhere in the build environment, and contains the list of classes required by the JAX-WS tools.

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. wsimport Task Attributes

wsimport supports the following parameter attributes:

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 .

3.2.3.2. arg

Additional command line arguments passed to thewsimport. For details about the syntax, seethe 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 followingwsimport 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 thewsimport 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. javacarg

The usage is similar to <arg> nested element, except that these arguments are directly passed to the Javac Compiler, which will be used for compiling sources generated during processing the referenced wsdl. For details about the syntax, see the relevant section in the Ant manual.Note: use '=' instead of space as a delimiter between option name and its value.

3.2.3.5. jvmarg

Use nested <jvmarg> elements to specify arguments for the the forked VM (ignored if fork is disabled), see the relevant section in the Ant manual.

3.2.3.6. xmlcatalog

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

3.2.3.7. depends/produces

Files specified with this nested element are taken into account when the task does a modification date check. For proper syntax, see .

3.3. wsimport Examples

The above example generates client-side artifacts forAddNumbers.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.

The above example shows how to generates artifacts forAddNumbers.wsdl while passing options to JAXBxjc tool for XML Schema to Java compilation using your JAXB plugin. Note extension attribute which is set totrue. 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.3.0-SNAPSHOT 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. wsgen Syntax

wsgen [OPTION]...

The following table lists the wsgen options:

4.4. wsgen Example

wsgen -d stock -cp myclasspath stock.StockService

This will generate the wrapper classes needed forStockService 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. Using wsgen Task

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

where jaxws.classpath is a reference to apath-like structure, defined elsewhere in the build environment, and contains the list of classes required by the JAX-WS tools.

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

5.2.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" fork="true|false" failonerror="true|false" xnocompile="true|false">

The classpath/cp attribute is a path-like structure and can also be set via nested<classpath> elements.

5.2.3. Nested Elements

wsgen supports the following nested element parameters.

5.2.3.1. external-metadata

An optional element external-metadata can be used if there are any web service metadata to be specified in xml file instead of java annotations:

For details seeExternal Web Service Metadata.

5.2.3.2. javacarg

The usage is similar to <arg> nested element, except that these arguments are directly passed to the Javac Compiler, which will be used for compiling sources generated during processing the referenced wsdl. For details about the syntax, see the relevant section in the Ant manual. Note: use '=' instead of space as a delimiter between option name and its value.

5.2.3.3. jvmarg

Use nested <jvmarg> elements to specify arguments for the the forked VM (ignored if fork is disabled), see the relevant section in the Ant manual.

5.3. wsgen Task Examples

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:

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 specifycom.sun.tools.ws.processor.modeler.annotation.WebServiceAp. The-sourcepath <path> option must also be provided so thatjavac 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 useannotationProcessing Ant Task.

7. annotationProcessing Ant Task

7.1. annotationProcessing Task Overview

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

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:

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:

where jaxws.classpath is a reference to apath-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

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

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 multipleannotationProcessing rounds. The classpath is a reference to a path-like structure jaxws.classpath, defined elsewhere in the build environment. This will also fork off theannotationProcessing process using the defaultjava 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 ofapt.

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.