ANT_OPTS="-Djava.endorsed.dirs=PATH_TO_YOUR_ENDORSED_DIR"
Appendix B: Rebuild Rules |
Previous | Contents |
The XML-WS 3.0 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 XML-WS TCK require that you first rebuild them using your generation tools.
This appendix contains the following sections:
The set of prebuilt archives and classes that ship with the XML-WS TCK
were built using the XML-WS Compatible Implementation tools
(wsgen Reference and wsimport Reference), and
must be deployed and run against your implementation of XML-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 XML-WS Compatible Implementation. These tests are known as reverse
tests. The test names of all the tests that will be run against the
Compatible 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 XML-WS
implementation.
Note
|
The same test client source file is used for each |
To be able to run the entire test suite in a single run, you must have your implementation and the Compatible Implementation configured simultaneously. Please see Configuring Your Environment to Simultaneously Run the XML-WS TCK Against the VI and the XML-WS Compatible Implementation for more information.
Instead of rebuilding and overwriting the TCK prebuilt classes and archives for each test directory, the XML-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 XML-WS TCK.
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 8 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 8
contains an implementation of JAX-WS 2.2 which will conflict with XML-WS
3.0, therefore this property must be set so that XML-WS 3.0 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 XML-WS 3.0 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 -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 XML-WS Compatible 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 Compatible Implementation.
Note
|
None of the XML-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 llc
.
The following is a listing of classes built using the XML-WS Compatible Implementation.
$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 lld
.
This shows you the listing of archives built using the XML-WS Compatible Implementation.
$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 -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 -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 lld
.
This shows the listing of all archives and XML-WS Compatible Implementation 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 -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.
When rebuilding the XML-WS TCK classes, it is strongly recommended that you use the procedure described in the previous section, Rebuilding the XML-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.
Run your tools in each of the XML-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 XML-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
XML-WS TCK jaxws
tools.
Note
|
None of the XML-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.
The wsgen
tool generates XML-WS portable artifacts used in XML-WS Web
services. The tool reads a Web service endpoint class and generates all
the required artifacts for Web service deployment and invocation.
wsgen [options] SEI
where SEI is the service endpoint interface implementation class.
Table B-1 wsgen Command Syntax
Option | Description |
---|---|
|
Specify where to find input class files. |
|
Same as |
|
Specify where to place generated output files. |
|
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. |
|
Display help. |
|
Keep generated files. |
|
Used only in conjunction with the |
|
Specify where to place generated source files. |
|
Output messages about what the compiler is doing. |
|
Print version information. Use of this option will ONLY print version information; normal processing will not occur. |
|
By default |
|
Used only in conjunction with the
|
|
Used only in conjunction with the
|
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 |
---|---|---|
|
Name of the service endpoint interface implementation class. |
SEI |
|
Specify where to place output generated classes. |
|
|
Specify where to find input class files. |
|
|
Same as |
|
|
Used only in conjunction with the |
|
|
Specify where to place generated source files. |
|
|
Keep generated files. |
|
|
Output messages about what the compiler is doing. |
|
|
Specify that a WSDL file should be generated. |
|
|
Used in conjunction with |
|
|
Used in conjunction with the
|
|
|
Used in conjunction with the
|
|
|
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. |
|
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
XML-WS tools.
The wsimport
tool generates XML-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:
wsimport [options] wsdl
where wsdl is the WSDL file.
Table B-3 wsimport Command Syntax
Option | Description |
---|---|
|
Specify where to place generated output files. |
|
Specify external XML-WS or JAXB binding files (Each |
|
Pass this option to JAXB schema compiler |
|
Specify catalog file to resolve external entity references,
it supports |
|
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. |
|
Display help. |
|
Specify an HTTP proxy server (port defaults
to |
|
Keep generated files. |
|
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. |
|
Specify where to place generated source files. |
|
Output messages about what the compiler is doing. |
|
Print version information. |
|
|
|
Generate code for the specified version of the XML-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 3.0. |
|
Suppress |
|
Map the headers not bound to request or response message to Java method parameters. |
|
File to carry authorization information in the format
|
|
Print debug information. |
|
Enable binding of W3C
|
|
Do not compile generated Java files. |
|
Disables the SSL Hostname verification while fetching the wsdls. |
Multiple XML-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 XML-WS and JAXB
binding files can be found in the customization documentation.
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 file. |
|
|
Specify where to place output generated classes |
|
|
Specify where to place generated source files, keep is turned on with this option |
|
|
Keep generated files, turned on with |
|
|
Output messages about what the compiler is doing |
|
|
Specify external XML-WS or JAXB binding files |
|
|
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 |
|
|
The WSDL URI passed through this option is used to set
the value of |
|
|
Specify catalog file to resolve external entity references,
it supports |
|
|
Specifies the target package |
|
|
Generate code for the specified version of the XML-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 3.0. |
|
|
Suppress |
|
|
Map headers not bound to request or response message to Java method parameters. |
|
|
File to carry authorization information in the format
|
|
|
Print debug information. |
|
|
Enable binding of W3C EndpointReferenceType to Java. |
|
|
Do not compile generated Java files. |
|
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
XML-WS tools.
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.
<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 |