Rebuilding the JAX-WS TCK Using the Vendor's Toolset
The JAX-WS 2.2 specification requires that each implementation has a way to generate WSDL from Java, and to generate Java from WSDL. To verify that implementations do this in a compatible manner, half of the tests in the JAX-WS TCK require that you first rebuild them using your generation tools.
This appendix contains the following sections:
B.1 Overview
The set of prebuilt archives and classes that ship with the JAX-WS TCK were built using Sun Reference Implementation tools (wsgen and wsimport), and must be deployed and run against your implementation of JAX-WS. These tests are referred to as forward tests.
You must also rebuild the archives and classes associated with these tests using your generation tools, and then deploy and run them against the Sun Reference Implementation. These tests are known as reverse tests. The test names of all the tests that will be run against the Sun Reference Implementation are identical to the forward test names found in the client Java source files, with the added suffix of _reverse. Essentially, for each forward test, there is an identical reverse test. This ensures that the same behaviors are verified on each JAX-WS implementation.
Figure B-1 JAX-WS TCK Test Paths

Note - The same test client source file is used for each forward and reverse test. Likewise, they also share the same test description, which only appears under the forward test name in the client Java source file.
To be able to run the entire test suite in a single run, you must have your implementation and the Sun Reference Implementation configured simultaneously. Please see 4.4 Configuring Your Environment to Simultaneously Run the JAX-WS TCK Against the VI and the Sun RI for more information.
B.2 Rebuilding the JAX-WS TCK Classes Using Ant
Instead of rebuilding and overwriting the TCK prebuilt classes and archives for each test directory, the JAX-WS TCK provides a way for you to plug in your generation tools so that you may leverage the existing build infrastructure that creates new classes and archives alongside those that ship with the JAX-WS TCK.
To Rebuild the JAX-WS TCK Classes Using Ant
- Create your own version of the Ant tasks WsImport and WsGen.
Documentation for these tasks can be found later in this appendix:
- Set the wsimport.ant.classname and wsgen.ant.classname properties in <TS_HOME>/bin/ts.jte to point to your implementations of the above two tasks.
- If using Java SE 6 or above:
- Verify that the property endorsed.dirs is set to the location of the VI API jars for those technologies you wish to override. Java SE 6 contains an implementation of JAX-WS 2.0 which will conflict with JAX-WS 2.2, therefore this property must be set so that JAX-WS 2.2 will be used during the building of tests and during test execution.
- Set the java.endorsed.dirs property in the ANT_OPTS environment variable to point to
the location in which only the JAX-WS 2.2 API jars exist; for example:
ANT_OPTS="-Djava.endorsed.dirs=PATH_TO_YOUR_ENDORSED_DIR"
- Change to the jaxws test directory and execute the following build target
<ANT_HOME>/bin/ant -Dbuild.vi=true clean build
The clean and build targets may be executed in any subdirectory under <TS_HOME>/src/com/sun/ts/tests/jaxws as long as the -Dbuild.vi=true system property is also set. Failure to set this property while invoking these targets will result in the prebuilt classes and archives being deleted and/or overwritten.
After completing the steps above, rebuilt class files will appear under <TS_HOME>/classes_vi_built so as not to affect class files that were generated and compiled with the Sun Reference Implementation. Rebuilt archives will be prefixed with the string, vi_built, and will be created in the same directory (under <TS_HOME>/dist) as those built using the Sun Reference Implementation.
Note - None of the JAX-WS test client source code or the service endpoint implementation test source code is to be altered in any way by a Vendor as part of the rebuild process.
Example B-1 Rebuilding a Single Test Directory
To further illustrate this process, the example below walks you through the rebuilding of a single test directory.
Change to the <TS_HOME>/src/com/sun/ts/tests/jaxws/ee/w2j/document/literal/httptest directory.
Run <ANT_HOME>/bin/ant llc.
The following is a listing of classes built using the Sun RI.
$ANT_HOME/bin/ant llc /var/tmp/jaxwstck/classes/com/sun/ts/tests/jaxws/ee/w2j/document/literal/httptest ---------------------------------------------------------------------------------- total 60 -rw-r--r-- 1 root root 13825 Apr 12 08:32 Client.class -rw-r--r-- 1 root root 2104 Apr 12 08:32 HelloImpl.class -rw-r--r-- 1 root root 1153 Apr 12 08:32 Hello.class -rw-r--r-- 1 root root 793 Apr 12 08:32 HelloOneWay.class -rw-r--r-- 1 root root 796 Apr 12 08:32 HelloRequest.class -rw-r--r-- 1 root root 799 Apr 12 08:32 HelloResponse.class -rw-r--r-- 1 root root 1564 Apr 12 08:32 HttpTestService.class -rw-r--r-- 1 root root 2845 Apr 12 08:32 ObjectFactory.class drwxr-xr-x 3 root root 512 Apr 12 08:32 generated_classes/ -rw-r--r-- 1 root root 293 Apr 12 08:32 package-info.class drwxr-xr-x 3 root root 512 Apr 12 08:31 generated_sources/
Run <ANT_HOME>/bin/ant lld.
This shows you the listing of archives built using the Sun RI.
$ANT_HOME/bin/ant lld /var/tmp/jaxwstck/dist/com/sun/ts/tests/jaxws/ee/w2j/document/literal/httptest ------------------------------------------------------------------------------- total 286 -rw-r--r-- 1 root root 113318 Apr 12 08:32 WSW2JDLHttpTest.war
Once your <TS_HOME>/bin/ts.jte file is configured and your implementations of the wsgen and wsimport tasks are specified, run the following command:
<ANT_HOME>/bin/ant -Dbuild.vi=true build
This builds the classes and archives using your implementation. Once this has been done successfully, proceed to the next step.
Run <ANT_HOME>/bin/ant -Dbuild.vi=true llc.
This shows you the listing of classes (under <TS_HOME>/classes_vi_built) built using your Implementation.
$ANT_HOME/bin/ant -Dbuild.vi=true llc /var/tmp/jaxwstck/classes_vi_built/com/sun/ts/tests/jaxws/ee/w2j/document/literal/httptest ------------------------------------------------------------------------------------------- total 60 -rw-r--r-- 1 root root 1153 Apr 12 12:01 Hello.class -rw-r--r-- 1 root root 793 Apr 12 12:01 HelloOneWay.class -rw-r--r-- 1 root root 796 Apr 12 12:01 HelloRequest.class -rw-r--r-- 1 root root 799 Apr 12 12:01 HelloResponse.class -rw-r--r-- 1 root root 1564 Apr 12 12:01 HttpTestService.class -rw-r--r-- 1 root root 2845 Apr 12 12:01 ObjectFactory.class drwxr-xr-x 3 root root 512 Apr 12 12:01 generated_classes/ -rw-r--r-- 1 root root 293 Apr 12 12:01 package-info.class drwxr-xr-x 3 root root 512 Apr 12 12:01 generated_sources/ -rw-r--r-- 1 root root 2104 Apr 12 08:33 HelloImpl.class -rw-r--r-- 1 root root 13825 Apr 12 08:33 Client.class
Run <ANT_HOME>/bin/ant lld.
This shows the listing of all archives and Sun RI deployment plan descriptors for this test directory. Those built using your implementation are prepended with vi_built_.
$ANT_HOME/bin/ant lld /var/tmp/jaxwstck/dist/com/sun/ts/tests/jaxws/ee/w2j/document/literal/httptest ------------------------------------------------------------------------------- total 286 -rw-r--r-- 1 root root 22676 Apr 12 12:01 vi_built_WSW2JDLHttpTest.war -rw-r--r-- 1 root root 113318 Apr 12 08:32 WSW2JDLHttpTest.war
Running the clean target while specifying the build.vi system property will only clean the classes and archives that you rebuilt. To clean them, run:
<ANT_HOME>/bin/ant -Dbuild.vi=true clean
Notice that the vi_built classes and archives are deleted.
Next Steps
Once you have successfully built the archives using your implementation, you can then proceed to the configuration section to learn how to deploy these archives and how to run the reverse tests.
B.3 Rebuilding the JAX-WS TCK Classes Manually
When rebuilding the JAX-WS TCK classes, it is strongly recommended that you use the procedure described in the previous section, Rebuilding the JAX-WS TCK Classes Using Ant. However, if you choose not to use the existing Ant-based TCK infrastructure to rebuild the tests, you can use the following procedure to rebuild the classes manually.
To Rebuild the JAX-WS TCK Classes Manually
- Run your tools in each of the JAX-WS test directories under <TS_HOME>/src/com/sun/ts/tests/jaxws, being sure
to place all newly compiled classes under <TS_HOME>/classes_vi_built.
Also be sure not to overwrite any of the compiled classes under <TS_HOME>/classes.
- Use the existing customization files and/or any handler files that exist in each of the test directories.
- Package the newly generated artifacts and all the other required classes into new
WAR files, prepeded with the string vi_built_.
These WAR files should reside in the same directory with the prebuilt WAR files under <TS_HOME>/dist directory.
Next Steps
As part of the manual rebuild process, you may also need to modify some of the following files. However, this is not recommended, since doing so can result in the JAX-WS TCK not being able to be built or run the prebuilt archives shipped with the TCK. The files you may need to modify are:
XML files in <TS_HOME>/bin/xml ; these files are used to generate the various WARs.
Any build.xml file in <TS_HOME>/src/com/sun/ts/tests/jaxws.
The <TS_HOME>/src/com/sun/ts/tests/jaxws/common/common.xml file, which is the main build file used for the jaxws build process. This common.xml file contains all the Ant tasks specific to invoking the JAX-WS TCK jaxws tools.
Note - None of the JAX-WS TCK test client source code or the service endpoint implementation test source code is to be altered in any way by a Vendor as part of the rebuild process.
Once you have successfully built the archives, you can proceed to the configuration section to learn how to deploy these archives and how to run the reverse tests.
B.4 wsgen Reference
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.
B.4.1 wsgen Syntax
wsgen [options] <SEI>
Table B-1 wsgen Command Syntax
Option |
Description |
---|---|
-classpath <path> |
Specify where to find input class files. |
-cp <path> |
Same as -classpath <path>. |
-d <directory> |
Specify where to place generated output files. |
-extension |
Allow 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. |
-help |
Display help. |
-keep |
Keep 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. |
-verbose |
Output messages about what the compiler is doing. |
-version |
Print 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 deployed. 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; for 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; for example: -portname "{http://mynamespace/}MyPort" |
B.4.2 wsgen Ant Task
An Ant task for the wsgen tool is provided along with the tool. 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" verbose="true|false" genwsdl="true|false" protocol="soap1.1|Xsoap1.2" servicename="..." portname="..."> extension="true|false" <classpath refid="..."/> </wsgen>
Table B-2 wsgen Attributes and Elements
Attribute |
Description |
Command Line |
---|---|---|
sei |
Name of the service endpoint implementation class. |
SEI |
destdir |
Specify where to place output generated classes. |
-d |
classpath |
Specify where to find input class files. |
-classpath |
cp |
Same as -classpath. |
-cp |
resourcedestdir |
Used only in conjunction with the -wsdl option. Specify where to place generated resource files such as WSDLs. |
-r |
sourcedestdir |
Specify where to place generated source files. |
-s |
keep |
Keep generated files. |
-keep |
verbose |
Output messages about what the compiler is doing. |
-verbose |
genwsdl |
Specify that a WSDL file should be generated. |
-wsdl |
protocol |
Used in conjunction with genwsdl to specify the protocol to use in the wsdl:binding. Value values are soap1.1or Xsoap1.2, default is soap1.1. Xsoap1.2is not standard and can only be used in conjunction with the -extensions option. |
-wsdl:soap1.1 |
servicename |
Used in conjunction with the genwsdl option. Used to specify a particular wsdl:service name for the generated WSDL; for example: servicename="{http://mynamespace/}MyService" |
-servicename |
portname |
Used in conjunction with the genwsdl option. Used to specify a particular wsdl:portmame name for the generated WSDL; for example: portname="{http://mynamespace/}MyPort" |
-servicename |
extension |
Allow 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 |
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 shown 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.
B.4.3 wsgen Example
<wsgen resourcedestdir="" sei="fromjava.server.AddNumbersImpl"> <classpath refid="compile.classpath"/> </wsgen>
B.5 wsimport Reference
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.
The wsimport tool can be launched using the command line script wsimport.sh (UNIX) or wsimport.bat (Windows). There is also an Ant task to import and compile the WSDL. See the below for further details.
B.5.1 wsimport Syntax
wsimport [options] <wsdl>
Table B-3 wsimport Command Syntax
Option |
Description |
---|---|
-d <directory> |
Specify where to place generated output files. |
-b <path> |
Specify external JAX-WS or JAXB binding files (Each <file> must have its own -b). |
-B <jaxbOption> |
Pass this option to JAXB schema compiler |
-catalog |
Specify catalog file to resolve external entity references, it supports TR9401, XCatalog, and OASIS XML Catalog format. Please read the XML Entity and URI Resolvers document or see the wsimport_catalog sample. |
-extension |
Allow 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. |
-help |
Display help. |
-httpproxy:<host>:<port> |
Specify an HTTP proxy server (port defaults to 8080). |
-keep |
Keep generated files. |
-p |
Specifying a target package with 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 files. |
-verbose |
Output messages about what the compiler is doing. |
-version |
Print version information. |
-wsdllocation <location> |
@WebService.wsdlLocation and @WebServiceClient.wsdlLocation value. |
-target |
Generate code per the given JAX-WS specification version. Version 2.0 will generate compliant code per the JAX-WS 2.0 specification. |
-quiet |
Suppress wsimport output. |
-XadditionalHeaders |
Map the headers not bound to request or response message to Java method parameters. |
-Xauthfile |
file to carry authorization information in the format http://username:password@example.org/stock?wsdl. Default value is $HOME/.metro/auth. |
-Xdebug |
Print debug information. |
-Xno-addressing-databinding |
Enable binding of W3C EndpointReferenceType to Java. |
-Xnocompile |
Do not compile generated Java files. |
-XdisableSSLHostnameVerification |
Disbales the SSL Hostname verification while fetching the wsdls. |
Multiple JAX-WS and JAXB binding files can be specified using the -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 customization documentation.
B.5.2 wsimport Ant Task
An Ant task for the wsimport tool is provided along with the tool. The attributes and elements supported by the Ant task are listed below.
<wsimport wsdl="..." destdir="directory for generated class files" sourcedestdir="directory for generated source files" keep="true|false" extension="true|false" verbose="true|false" version="true|false" wsdlLocation="..." catalog="catalog file" package="package name" target="target release" binding="..." quiet="true|false" xadditionalHeaders="true|false" xauthfile="authorization file" xdebug="true|false" xNoAddressingDatabinding="true|false" xnocompile="true|false" <binding dir="..." includes="..." /> <arg value="..."/> <xjcarg value="..."/> <xmlcatalog refid="another catalog file"/>> </wsimport>
Table B-4 wsimport Attributes and Elements
Attribute |
Description |
Command Line |
---|---|---|
wsdl |
WSDL file. |
WSDL |
destdir |
Specify where to place output generated classes |
-d |
sourcedestdir |
Specify where to place generated source files, keep is turned on with this option |
-s |
keep |
Keep generated files, turned on with sourcedestdir option |
-keep |
verbose |
Output messages about what the compiler is doing |
-verbose |
binding |
Specify external JAX-WS or JAXB binding files |
-b |
extension |
Allow 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 |
wsdllocation |
The WSDL URI passed through this option is used to set the value of @WebService.wsdlLocation and @WebServiceClient.wsdlLocation annotation elements on the generated SEI and Service interface |
-wsdllocation |
catalog |
Specify catalog file to resolve external entity references, it supports TR9401, XCatalog, and OASIS XML Catalog format. Additionally, the Ant xmlcatalog type can be used to resolve entities. See the wsimport_catalog sample for more information. |
-catalog |
package |
Specifies the target package |
-p |
target |
Generate code per the given JAX-WS specification version. Version 2.0 will generate compliant code per the JAX-WS 2.0 specification. |
-target |
quiet |
Suppress wsimport output. |
-quiet |
xadditionalHeaders |
Map headers not bound to request or response message to Java method parameters. |
-XadditionalHeaders |
xauthfile |
File to carry authorization information in the format http://username:password@example.org/stock?wsdl. |
-Xauthfile |
xdebug |
Print debug information. |
-Xdebug |
xNoAddressingDatabinding |
Enable binding of W3C EndpointReferenceType to Java. |
-Xno-addressing-databinding |
xnocompile |
Do not compile generated Java files. |
-Xnocompile |
The binding attribute is like a path-like structure and can also be set via nested <binding> elements, respectively. Before this task can be used, a <taskdef> element needs to be added to the project as shown 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.
B.5.3 wsimport Examples
<wsimport destdir="" debug="true" wsdl="AddNumbers.wsdl" binding="custom.xml"/>
The above example generates client-side artifacts for AddNumbers.wsdl and stores .class files in the destination directory using the custom.xml customization file. The classpath used is xyz.jar and compiles with debug information on.
<wsimport keep="true" sourcedestdir="" destdir="" wsdl="AddNumbers.wsdl"> <binding dir="${basedir}/etc" includes="custom.xml"/> </wsimport>
The above example generates portable artifacts for AddNumbers.wsdl, stores .java files in the destination directory, and stores .class files in the same directory.