Level: Introductory Peter Brittenham (peterbr@us.ibm.com), Sr. Software Engineer, IBM
18 Nov 2003 If you are a Web service developer, you want to ensure that your service will interoperate with any consumer that wants to use it. The best way to do this is to follow the guidelines that are listed in the WS-I Basic Profile 1.0. If you are developing a new Web service or if you have Web services that already exist, the WS-I Test Tools provide an easy way to determine if your services conform to these guidelines. In this article, Peter Brittenham provides an overview of the WS-I Test Tools.
Introduction
In August 2003, the Web Services Interoperability Organization (WS-I) published the
Basic Profile 1.0. This profile contains implementation guidelines for the core Web
services specifications: XML 1.0, XML Schema 1.0, SOAP 1.1, WSDL 1.1 and UDDI 2.0.
These guidelines are a set of requirements that define how these specifications should
be used to develop interoperable Web services. The WS-I test tools can be used to verify
that a Web service conforms to these requirements. A draft (beta) release of the WS-I
test tools is available from the WS-I Web site (see Resources), and a final release should
be available later this fall.
This article describes the basic architecture of the Test Tools. We will follow with future articles and
tutorials on how to use these tools to test your services application for interoperability and what to do
in case you do find your application non-compliant with the Basic Profile.
Tools architecture
The WS-I Test Tools consist of two tools: the monitor and analyzer. The monitor provides
an unobtrusive way to log Web service messages using a man-in-the-middle approach. The
purpose of the analyzer is to determine if a set of Web service related artifacts
conform to the requirements in the WS-I Basic Profile 1.0. There are three basic types
of artifacts:
- messages -- The set of messages that were logged by the monitor.
- description -- The service description for the Web service (this includes
any referenced XML schema definitions), if the location of the WSDL
document is available.
- discovery -- The UDDI entries for a Web service, if the UDDI entries reference a
WSDL-based service description.
Figure 1 provides an overview of the WS-I Test Tools architecture.
Figure 1. WS-I Test Tools architecture
Monitor overview
The monitor contains two primary functions: message interceptor and message logger.
The message interceptor intercepts the messages that are sent from a service requestor to
a Web service and from a Web service back to the service requestor. The logger formats the
intercepted messages into a standard format and then writes them out to a message log.
With these two functions, a single monitor can intercept and log messages from multiple
Web services. The monitor functions are controlled by a configuration file which defines
the association between the ports the monitor listens on for incoming messages, and the Web
service location where the monitor should forward the messages.
When using the monitor, the service requestor views it as if it was the Web service.
All SOAP messages are sent to the monitor instead of the Web service. Since this is not
the normal mode of operation for the requestor, there are three basic ways to do this:
- Alter the requestor to point at the monitor instead of the Web service.
- Move the Web service to a new location and run the monitor in its place.
- Alter the Web service endpoint information that the requestor uses.
There are several system configurations that can be used to run the monitor. There
are four basic system configurations which define the systems where the requestor, monitor,
and Web service can run.
- The requestor, monitor, and Web service can be run on the same system.
- The monitor can be run on the same system as the requestor, and the Web service
can run on a different system.
- The requestor can be on a different system than the monitor and Web service.
- The requestor, monitor, and Web service can be run on three different systems.
Figure 2 illustrates all of the system configuration options for the monitor.
Figure 2. Monitor system configurations
Monitor configuration file
The monitor requires one input file. This file is an XML document that contains the
configuration options that tell the monitor what it needs to monitor and where it needs
to log the messages it intercepts. Listing 1 contains an example of a monitor
configuration file.
Listing 1. Monitor configuration file
1 <?xml version="1.0" encoding="utf-8" ?>
2 <configuration xmlns="http://www.ws-i.org/testing/2003/03/monitorConfig/">
3 <comment>
4 This configuration file is used to test the LoggingFacility WS-I sample application.
5 </comment>
6 <logFile replace="true" location="log.xml">
7 <addStyleSheet href="c:/wsi-test-tools/common/xsl/log.xsl" type="text/xsl"/>
8 </logFile>
9 <logDuration>600</logDuration>
10 <cleanupTimeoutSeconds>3</cleanupTimeoutSeconds>
11 <manInTheMiddle>
12 <redirect>
13 <comment>Redirect from port 4040 to wsi.alphaworks.ibm.com.</comment>
14 <listenPort>4040</listenPort>
15 <schemeAndHostPort>http://wsi.alphaworks.ibm.com</schemeAndHostPort>
16 <maxConnections>1000</maxConnections>
17 <readTimeoutSeconds>15</readTimeoutSeconds>
18 </redirect>
19 </manInTheMiddle>
20 </configuration>
|
The primary elements in the example configuration file are explained below. A
detailed description of all configuration elements is located in the WS-I Monitor
Tool Function Specification (see Resources).
Table 1
| Line Number | XML Element | Description | Example Contents | | 6-8 | <logFile> | Indicates the file that should be used to log the messages. | The messages will be put into a file named log.xml. | | 12-18 | <redirect> | Defines the parameters for monitoring a single service
location. | This example contains two redirect statements, so two
service locations will be monitored at the same time. | | 14 | <listenPort> | Defines the port that the monitor listens on for incoming
messages. | The monitor will listen on ports 4040 and 4041 for incoming
messages. | | 15 | <schemeAndHostPort> | Defines the location where the messages should be forwarded. | The messages received on port 4040 are forwarded to
localhost on port 8080, and the messages received on port 4041 are sent to uddi.ibm.com
on port 80 (the default HTTP port). |
Message log file
The log file created by the monitor is an XML document. This file contains run time
information for the monitor tool, the monitor configuration information, and the messages
that were intercepted while the monitor was running. The log files can be viewed as an
XML document (see Resources), or a style sheet is available to view it in an HTML format. This log file
contains two messages: the request being sent to the Web service and the response returned
by the Web service.
Analyzer overview
The analyzer tool determines if the artifacts for a Web service conform to the Basic
Profile by processing a set of test assertions. A test assertion is a testable expression
of one or more requirements in the Basic Profile. All of the test assertions are listed
in a test assertion document (see Resources), which is an XML document whose contents are
segmented by artifact type (discovery, description, and messages).
The input for the analyzer includes the location of the test assertion document and
references to the Web service artifacts. The output from the analyzer is a conformance
report. All of this information is specified in the analyzer configuration file.
Analyzer configuration file
Just like the monitor tool, the analyzer uses an XML document to define its
configuration options. Listing 2 contains an example of an analyzer
configuration file.
Listing 2. Analyzer configuration file with uddiReference element
1 <configuration name="Sample Basic Profile Analyzer Configuration"
2 xmlns="http://www.ws-i.org/testing/2003/03/analyzerConfig/">
3 <description>
4 This file contains a sample of the configuration file for
5 the Basic Profile Analyzer.
6 </description>
7
8 <verbose>false</verbose>
9 <assertionResults type="all" messageEntry="true" failureMessage="true"/>
10 <reportFile replace="true" location="report.xml">
11 <addStyleSheet href="c:/wsi-test-tools/common/xsl/report.xsl" type="text/xsl"/>
12 </reportFile>
13 <testAssertionsFile>
14 c:/wsi-test-tools/common/profiles/BasicProfileTestAssertions.xml
15 </testAssertionsFile>
16 <logFile correlationType="endpoint">
17 log.xml
18 </logFile>
19 <uddiReference>
20 <uddiKey type="bindingKey">22e841c0-0ef2-11d7-a725-000629dc0a53</uddiKey>
21 <inquiryURL>http://uddi.ibm.com/ubr/inquiryapi</inquiryURL>
22 </uddiReference>
23 </configuration>
|
For this configuration file, the artifacts that will be analyzed are the messages
in the log.xml file (lines 16 to 18), the UDDI entry for this Web service (lines 19 to 22),
and the WSDL document that is referenced by the UDDI tModel entry (this is not directly
referenced by an entry in the configuration file).
A reference to a discovery artifact (<uddiReference> element)
and a reference to a description artifact (<wsdlReference> element)
can not be specified in the same configuration file. When the
<uddiReference> element is specified, the description related
test assertions are processed if the UDDI tModel contains a reference to a WSDL binding element.
The following analyzer configuration file shows how to use the
<wsdlReference> element (lines 19 to 27). This is a
reference to a binding element in the WSDL document.
Listing 3. Analyzer Configuration File with wsdlReference Element
1 <configuration name="Sample Basic Profile Analyzer Configuration"
2 xmlns="http://www.ws-i.org/testing/2003/03/analyzerConfig/">
3 <description>
4 This file contains a sample of the configuration file for
5 the Basic Profile Analyzer.
6 </description>
7
8 <verbose>false</verbose>
9 <assertionResults type="all" messageEntry="true" failureMessage="true"/>
10 <reportFile replace="true" location="report.xml">
11 <addStyleSheet href="c:/wsi-test-tools/common/xsl/report.xsl" type="text/xsl"/>
12 </reportFile>
13 <testAssertionsFile>
14 c:/wsi-test-tools/common/profiles/BasicProfileTestAssertions.xml
15 </testAssertionsFile>
16 <logFile correlationType="endpoint">
17 log.xml
18 </logFile>
19 <wsdlReference>
20 <wsdlElement type="binding"
21 namespace="http://www.ws-i.org/SampleApplications/
SupplyChainManagement/2002-08/LoggingFacility.wsdl">
22 LoggingFacilitySoapBinding
23 </wsdlElement>
24 <wsdlURI>
25 http://www.ws-i.org/SampleApplications/
SupplyChainManagement/2002-08/LoggingFacility.wsdl
26 </wsdlURI>
27 </wsdlReference>
28 </configuration>
|
The key configuration options from the two example files are described in the table below.
All of the configuration options are described in detail within the WS-I Analyzer Tool Function
Specification (see Resources).
Table 2
| Line Number | XML Element | Description | Example Contents | | 10-12 | <reportFile> | Contains the file name for the output conformance report. | The conformance report will be put into the
report.xml file. | | 13-15 | <testAssertionFile> | Location of the test assertion document. | The test assertion document is located in
the /wsi-test-tools/common/profiles directory. | | 16-18 | <logFile> | Location of the message log file. | The messages are in the file named log.xml. | | 19-22(first example file) | <uddiReference> | The UDDI entry that should be analyzed. If a
bindingTemplate is specified and it referenced a tModel with a WSDL reference,
then the WSDL document is also analyzed. | The UDDI entry is a bindingTemplate with a bindingKey
value of 22e841c0-0ef2-11d7-a725-000629dc0a53. | | 19-27(second example file) | <wsdlReference> | The location of the WSDL document and the element
within that document where the analysis should begin. All elements referenced by
the specified element are also analyzed. Any types and import elements are also
analyzed. | The WSDL document is analyzed starting with the
binding element named LoggingFacilitySoapBinding. The portType, operation and
message elements referenced by this binding are also analyzed. |
 |
Test assertion document
The following figure contains an HTML rendering of a single test assertion. Each
test assertion has a unique identifier and contains all of the information that is needed
to understand how the analyzer will process the assertion. For this example, the test
assertion identifier is WSI2406. The purpose of the test assertion is to analyze a WSDL
binding element to verify that the value of the use attribute is "literal" when it is used
on the body, fault, header, and headerfault SOAP binding elements.
Figure 3. Test assertion example
The following table contains a description of the primary components of this test
assertion. All of the information in the test assertion document is described in detail
within the WS-I Analyzer Tool Functional Specification (see Resources).
Table 3
| Test Assertion Content | Description | Sample | | Entry Type | The primary type of data that will be analyzed. | The WSDL binding element. | | Test Type | Indicates if conformance is required or recommended by
the Basic Profile. | This test assertion is required, so if it fails then
the artifacts fail the conformance test. | | Additional Entry Types | The additional types of data that are needed to process
the test assertion. As an example, a test assertion for a response message may require
analysis of the request message. In this example, the request message would be listed
as an additional entry type. | No additional data is required. | | Prerequisites | Other test assertions that must pass before this test
assertion can be processed. | WSI2073 must have a passed result before this test
assertion can be processed. | | Profile Requirements | Reference to the requirements in the Basic Profile that
are associated with this test assertion. | This test assertion is targeted at the R2706 and R2723
requirements in the Basic Profile. Aspects of R2707 have also been taken into
consideration. | | Context | The conditions that must exist to process the test assertion. | This test assertion will only be processed if the WSDL
document contains a binding element and that binding element contains a body, fault,
header or headerfault SOAP binding element with a use attribute. | | Assertion Description | The description of the assertion. | The value of the use attribute must be "literal". If it
isn't, then this test assertion will fail. | | Failure Message | The message that will be displayed in the conformance
report if the test assertion fails. | If this assertion fails, then this message will help explain
why it failed. |
|
Profile conformance report
The output from the analyzer is a conformance report. The conformance report will contain
the results for all of the test assertions that were processed. As was true with the
message log file, the report file can be viewed as an XML document, or a stylesheet is
available so that it can be viewed in an HTML format. The test assertion results are
listed by entry within an artifact type. For example, the test assertions for a binding
element in a WSDL document (the entry) would appear within the description artifact type.
A test assertion may have one of five possible results: passed, failed, warning,
notApplicable, or missingInput. If any of the test assertions failed, then the artifacts
that were analyzed do not conform to the Basic Profile. When using the HTML view of the
report, the assertion results are color coded the way that they are listed in the following
table.
Table 4
The HTML format for the report contains a couple of summaries that are not available
in the XML version of the report file. The overall summary will indicate if the specified
artifacts passed or failed conformance. If overall
summary result is failed, then you should
look through the detailed test assertion results to determine which test assertions failed.
The detailed test assertion results are listed by entry (for example, WSDL binding element, message
log entry ID, etc.). Reviewing the test assertion description and the associated profile
requirements will help you understand what you need to change to make your Web service
conform to the Basic Profile.
Summary
This article has presented an overview of the WS-I test tools. These tools provide
Web service developers with an easy way to determine if their Web services conform to the
requirements in the Basic Profile 1.0. The next article in this series will provide
step-by-step instructions on how to install and use the test tools.
Download | Name | Size | Download method |
|---|
| log_no_xsl.xml | 140.0 KB | HTTP |
Resources
About the author  | | | Peter is currently a Web Services Architect in the IBM Emerging Technologies group. He has worked with the WS-I organization since April 2002, and was the architect for the Java version of the WS-I test tools. |
Rate this page
| 
