Appendix B

Previous Contents

B Rebuilding the JAX-WS TCK Using the Vendor’s Toolset

The JAX-WS 2.3 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 the JAX-WS Reference Implementation tools (wsgen Reference and wsimport Reference), 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 JAX-WS Reference Implementation. These tests are known as reverse tests. The test names of all the tests that will be run against the 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.

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 Reference Implementation configured simultaneously. Please see Configuring Your Environment to Simultaneously Run the JAX-WS TCK Against the VI and the JAX-WS 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.

  1. Create your own version of the Ant tasks WsImport and WsGen.
    Documentation for these tasks can be found later in this appendix:

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

  3. If using Java SE 8 or above:

    1. 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 8 contains an implementation of JAX-WS 2.2 which will conflict with JAX-WS 2.3, therefore this property must be set so that JAX-WS 2.3 will be used during the building of tests and during test execution.

    2. Set the java.endorsed.dirs property in the ANT_OPTS environment variable to point to the location in which only the JAX-WS 2.3 API jars exist; for example:

      ANT_OPTS="-Djava.endorsed.dirs=PATH_TO_YOUR_ENDORSED_DIR"
  4. Change to the jaxws test directory and execute the following build target:

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

  1. Change to the <TS_HOME>/src/com/sun/ts/tests/jaxws/ee/w2j/document/literal/httptest directory.

  2. Run <TS_HOME>/tools/ant/bin/ant llc.
    The following is a listing of classes built using the JAX-WS RI.

    $TS_HOME/tools/ant/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/
  3. Run <TS_HOME>/tools/ant/bin/ant lld.
    This shows you the listing of archives built using the JAX-WS RI.

    $TS_HOME/tools/ant/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
  4. 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:

    <TS_HOME>/tools/ant/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.

  5. Run <TS_HOME>/tools/ant/bin/ant -Dbuild.vi=true llc.
    This shows you the listing of classes (under <TS_HOME>/classes_vi_built) built using your Implementation.

    $TS_HOME/tools/ant/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
  6. Run <TS_HOME>/tools/ant/bin/ant lld.
    This shows the listing of all archives and JAX-WS RI deployment plan descriptors for this test directory. Those built using your implementation are prepended with vi_built_.

    $TS_HOME/tools/ant/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
  7. 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:

    <TS_HOME>/tools/ant/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.

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

  2. Use the existing customization files and/or any handler files that exist in each of the test directories.

  3. 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 Chapter 4, "Setup and Configuration" 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

where SEI is the service endpoint interface implementation class.

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 interface 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.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: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 (http://ant.apache.org/manual/using.html#path) and can also be set by using 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 (http://ant.apache.org/manual/using.html#path), 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.

This section contains the following topics:

B.5.1 wsimport Syntax

wsimport [options] wsdl

where wsdl is the WSDL file.

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 Catalog Support 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 for the specified version of the JAX-WS specification. For example, a value of 2.0 generates code that is compliant with the JAX-WS 2.0 Specification. The default value is 2.3.

-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

Disables 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, such as package names and bean names. 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 for the specified version of the JAX-WS specification. For example, a value of 2.0 generates code that is compliant with the JAX-WS 2.0 Specification. The default value is 2.3.

-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 (http://ant.apache.org/manual/using.html#path) and can also be set by using 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 (http://ant.apache.org/manual/using.html#path), defined elsewhere in the build environment, and contains the list of classes required by the JAX-WS tools.

B.5.2.1 Nested Elements

wsimport supports the following nested element parameters.

  • binding: To specify more than one binding file at the same time, use a nested <binding> element, which has the same syntax as <fileset>. See http://ant.apache.org/manual/Types/fileset.html for more information.

  • arg: Additional command line arguments passed to the wsimport Ant task. For details about the syntax, see the arg section (http://ant.apache.org/manual/using.html#arg) 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 -XdisableSSLHostnameVerification command-line option for wsimport. This nested element can be used to pass –X command-line options directly, as done with –XadditionalHeaders. To use any of these features from the wsimport Ant task, you must specify the appropriate nested <arg> elements.

  • xjcarg: The usage of xjcarg is similar to that of the <arg> nested element, except that these arguments are passed directly to the XJC tool (JAXB Schema Compiler), which compiles the schema that the WSDL references. For details about the syntax, see the arg section (http://ant.apache.org/manual/using.html#arg) in the Ant manual.

  • xmlcatalog: The xmlcatalog (http://ant.apache.org/manual/Types/xmlcatalog.html) element is used to resolve entities when parsing schema documents.

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.


Previous Contents
Eclipse Foundation Logo  Copyright © 2018, Oracle and/or its affiliates. All rights reserved.