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.
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
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
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). |
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.
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.
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. |
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. |
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.
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.
| Name | Size | Download method |
|---|---|---|
| log_no_xsl.xml | 140.0 KB | HTTP |
Information about download methods Get Adobe® Reader®
- Download the example Log file in XML.
- A First Look at the WS-I Basic Profile 1.0 gives a friendly introduction to the list of specifications and standards that constitute this Profile. (developerWorks, October 2002)
- See also the WS-I Basic Profile 1.0
- Download the WS-I Test Tools.
- Read the WS-I Monitor Tool Functional Specification.
- Find the WS-I Analyzer Tool Functional Specification here.
- Check out the WS-I Test Assertion Document.
Table of contents
Local resources
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
