Web Service Repository

Contents

Overview

The Web Services Repository stores information about Web Services whose definitions have been imported using Policy Studio or Service Manager. The WSDL files that contain these Web Services definitions are stored together with their related XML Schemas. Clients of the Web Service can then query the repository for the WSDL file, which they can use to build and send messages to the Web Service using the Enterprise Gateway.

When you import WSDL files into the repository, this auto-generates a Service Handler that is used to control and validate requests to the Web Service and responses from the Web Service. You can import the WSDL file from the file system, a URL, or from a UDDI registry. You can also test the WSDL file for compliance with Web Services Interoperability (WS-I) standards.

This topic describes how to test for WS-I compliance, how to import a Web Service definition into the repository, and shows what is created at each step.

Testing WS-I Compliance

Before importing the WSDL file, you can check it for compliance with the WS-I Basic Profile. The Basic Profile consists of a set of assertions and guidelines on how to ensure maximum interoperability between different implementations of Web Services. For example, there are recommendations on what style of SOAP to use (document/literal), how schema information is included in WSDL files, and how message parts are defined to avoid ambiguity for consumers of WSDL files.

The Policy Studio uses the Java version of the WS-Interoperability Testing Tools to test imported WSDL files for compliance with the recommendations in the Basic Profile. A report is generated showing which recommendations have passed and which have failed. While you can still import a WSDL file that does not comply with the Basic Profile, there is no certainty that consumers of the Web Service can use it without encountering problems.

Important Note:
Before you run the WS-I compliance test, you must ensure that the Java version of the Interoperability Testing Tools is installed on the machine on which the Policy Studio is running. You can download these tools from www.ws-i.org.

To configure the location of the WS-I testing tools, select Window -> Preferences from the Policy Studio main menu. In the Preferences dialog, select the WS-I Settings, and browse to the location of the WS-I testing tools. You must specify the full path to these tools (for example, C:\Program Files\WSI_Test_Java_Final_1.1\wsi-test-tools). For more details on configuring WS-I settings, see the Policy Studio Preferences topic.

Running the WS-I Compliance Test
To run the WS-I compliance test on a WSDL file, perform the following steps:

  1. Select Tools -> Run WS-I Compliance Test from the Policy Studio main menu.
  2. In the Run WS-I Compliance Test dialog, browse to the WSDL File or specify the WSDL URL.
  3. Click OK. The WS-I Analysis tools run in the background in Policy Studio.

The results of the compliance test are displayed in your browser in a WS-I Profile Conformance Report. The overall result of the compliance test is displayed in the Summary section. The results of the WS-I compliance tests are grouped by type in the Artifact: description section. For example, you can access details for a specific port type, operation, or message by clicking the appropriate link in the Entry List table. Each Entry displays the results for the relevant WS-I Test Assertions.

Importing the WSDL File

The Web Services Repository is displayed as a top-level node in the Policy Studio Policies tree view. WSDL files are imported into Web Service Groups, which provide a convenient way of keeping groups of related Web Service definitions together. You can import a WSDL file into the default group by right-clicking the Web Services node, and selecting Register Web Service.

Alternatively, you can add a new Web Services group by right-clicking the default Web Services group, or the Web Services Repository node, and selecting Add a new Web Services group. When the new group is added, you can right-click it in the tree, and select Register Web Service.

Loading the WSDL File

In the Import WSDL wizard, the Load WSDL screen enables you to choose the WSDL location from the following options:

  • File system
  • URL
  • UDDI registry

Select the appropriate option depending on the location of the WSDL that you wish to import. If you wish to retrieve a WSDL file from a UDDI directory, see the Retrieving WSDL Files from a UDDI Directory topic.

Click Next.

Selecting WSDL Operations

The WSDL Operations screen of the wizard displays all operations defined in the WSDL file. The Relative Path, Binding, and Namespace of each operation are also displayed.

Select the operations that you wish to create policy resolvers for. The Policy Studio uses the Web Service location, SOAP operation, and SOAP Action specified in the WSDL to create Relative Path, SOAP Operation, and SOAP Action policy resolving filters in the Service Handler.

Click Next.

WSDL Import Settings

In the WSDL Import Settings screen, the Remove unselected operations from the WSDL checkbox specifies whether the Policy Studio removes unselected operations from the WSDL file that is stored in the repository. As a result, removed operations are not exposed to clients that download the WSDL file for the Web Service.

Important Note:
When a request is made to the Enterprise Gateway for a WSDL file that has been imported into the Web Services Repository, it changes the address of the Web Service specified in the location attribute of the <soap:address> element to point to the machine on which the Enterprise Gateway is running, rather than the machine hosting the Web Service. This means that when a client downloads the WSDL file for the Web Service, it routes messages through the Enterprise Gateway instead of attempting to send messages directly to the Web Service, which typically is not available on a public IP address. For a detailed example, see Publishing the WSDL.

Click Next.

Deploy Policy

The final screen in the wizard enables you to select where to deploy the newly created policy (or policies). The Deploy Policy screen displays a list of all available Services and their corresponding Relative Paths. Select a Relative Path under which the policy is deployed. All requests arriving on the selected path are dispatched to the newly created policy.

Click Finish.

Secure Virtual Service

When you click Finish in the wizard, the Secure Virtual Service dialog is displayed. This enables you to specify policies to enforce security between a client and the Enterprise Gateway. For more details, see Securing a Virtual Service using Policies. In addition, if the imported WSDL file contains WS-Policy assertions, you are prompted to configure settings to enforce security between the Enterprise Gateway and the Web Service. For more details, see Configuring Security Policies from WSDL Files.

When you have finished configuring security settings, the Summary dialog displays summary information for the imported WSDL file.

What is created?

What is created when you import the WSDL file depends on whether you configured a policy to enforce security between the client and the Enterprise Gateway, and whether the WSDL file contains any WS-Policy annotations. However, assuming that the default options are selected in the WSDL Import wizard, the following list summarizes what is created by the wizard:

Web Service
A new Web Service tree node is created for each imported WSDL file in the Policies tree view. This tree node contains the WSDL file itself, together with any imported resources, such as other WSDL files or schema files. Click the new Web Service node in the tree to view the list of imported WSDL files and XML Schemas. The Schemas are listed by namespace.

You can view the imported WSDL file by clicking the location of the WSDL file under the Web Service node in the tree. If you have selected to remove unselected operations from the WSDL, these operations are removed from the stored WSDL.

Policy Container
A container for the newly generated policies is created under the Generated Circuits node in the Policies tree. The new container is named after the service (for example, Web Services.HelloWorldService).

Policy
A policy for the Web Service is created in the generated policy container. The policy name includes the relative path to the service (for example, /HelloWorldService/HelloWorld). Clients can specify WSDL on a request query string to retrieve the WSDL file (for example, http://localhost:8080/HelloWorldService/HelloWorld?WSDL). For more details, see Publishing the WSDL.

Service Handler
A Service Handler for the Web Service is created under the generated policy in the Policies tree. This is used to control and validate requests to the Web Service and responses from the Web Service. The Service Handler is named after the Web Service (for example, Service Handler for 'HelloWorldService').

The Service Handler is a Web Service Filter, and is used to control the following:

  • Routing
  • Validation
  • Message request/response processing
  • WSDL options
  • Monitoring options

For more details, see Web Service Filter.

Security Policies
If you decided to configure a WS-policy to enforce security between the client and the Enterprise Gateway (as described earlier in Secure Virtual Service), or if the imported WSDL file contains WS-Policy assertions, a number of additional policies are automatically created in the generated policy container. These generated policies include the filters required to generate and/or validate the relevant security tokens (for example, SAML tokens, WS-Security Username tokens, and WS-Addressing headers). These policies perform the necessary cryptographic operations (for example, signing/verifying and encryption/decryption) to meet the security requirements of the specified policies.

Publishing the WSDL

When the WSDL has been imported into the Web Services Repository, it can be retrieved by clients. In effect, by importing the WSDL into the repository, you are publishing the WSDL. In this way, consumers of the services defined in the WSDL can learn how to communicate with those services by retrieving the WSDL for those services. However, to do this, the location of the service must be changed to reflect the fact that the Enterprise Gateway now sits between the client and the defined service.

For example, assume that the WSDL file states that a particular service resides at http://www.example.com/services/myService:

<service name="myService">
  <port binding="SoapBinding" name="mySample">
    <wsdl:address location="http://www.example.com/services/myService"/>
  </port>
</service>

When deployed behind the Enterprise Gateway, this URL is no longer accessible to consumers of the service. Because of this, clients must send SOAP messages through the Enterprise Gateway to access the service. In other words, they must now address the machine hosting the Enterprise Gateway instead of that directly hosting the service.

When the WSDL file has been published to the repository, clients can retrieve it. However, when returning the WSDL to the client, the Enterprise Gateway dynamically changes the value of the location attribute in the service element in the WSDL file to point to the machine on which the Enterprise Gateway resides. The details regarding the physical location of the Web Service are preserved in the Connection filters, which are responsible for routing messages on to the service.

Assuming that the Enterprise Gateway is running on port 8080 on a machine called SERVICES, the location specified in the exported WSDL file is changed to the following:

<service name="myService">
  <port binding="SoapBinding" name="mySample">
    <wsdl:address location="http://SERVICES:8080/services/myService"/>
  </port>
</service>

When the modified WSDL file is distributed to the client, it now routes messages to the machine hosting the Enterprise Gateway instead of attempting to directly access the Web Service.

Accessing the WSDL
For the client to access this modified WSDL file, the Policy Studio provides a WSDL retrieval facility whereby clients can query the Web Services Repository for the WSDL file for a particular Web Service. To do this, the client must pass the name WSDL on the query string to the Relative Path mapped to the policy for this Web Service.

For example, if the policy is deployed under http://SERVICES:8080/services/getQuote, the client can retrieve the WSDL for this Web Service by sending a request to http://SERVICES:8080/services/getQuote?WSDL. When the client has a copy of the updated WSDL file, it knows how to create correctly formatted messages for the service, and perhaps more importantly, it knows to route messages to the Enterprise Gateway rather than to the Web Service directly.