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:
- Select Tools -> Run WS-I Compliance Test
from the Policy Studio main menu.
- In the Run WS-I Compliance Test dialog, browse to
the WSDL File or specify the WSDL URL.
- 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.
|
Registering the WSDL File
|
|
The Web Services Repository is displayed under the Business
Services node in the Policy Studio tree. 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 Registry
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.
Use the Remove unselected operations from the WSDL checkbox to specify
whether the Policy Studio removes unselected operations from the WSDL file 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, instead of the machine
hosting the Web Service. This means when a client downloads the WSDL file for the Web
Service, it routes messages through the Enterprise Gateway instead of sending messages directly
to the Web Service, which is typically not available on a public IP address. For a detailed
example, see Publishing the WSDL.
Click Next.
|
WS-Policy Options
|
|
Configure the following options on this screen:
Secure this virtualized service with a WS-Policy
Specifies whether to use a WS-Policy to secure the Web Service being virtualized by the
Enterprise Gateway. When this setting is selected, the Secure Virtual Service
dialog is displayed after the Import WSDL wizard. This dialog enables
you to configure a WS-Policy that the Enterprise Gateway enforces on messages that it receives
from the client. This setting is unselected by default.
Use the WS-Policy in the WSDL to connect securely to the back-end Web
Service
When the WSDL file includes WS-Policy information, this setting specifies whether to
use this WS-Policy to connect securely to the Web Service. This setting is enabled
(and selected by default) only if the selected WSDL file includes WS-Policy information.
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.
|
WSDL Import Summary
|
|
When you have finished configuring security policies, the Summary dialog
displays details on the imported WSDL file. For example, this includes the location of the
WSDL file, and a tab for each Web Service virtualized by the Enterprise Gateway. Each tab includes
the path to the Web Service that is published by the Enterprise Gateway.
WSDL Import Summary Options
The Summary dialog also enables you to configure the following
options on the tab for each Web Service:
|
Validation
|
If you wish to use a dedicated validation policy for all messages sent to the
Web Service, select this checkbox, and click the browse button to configure a
policy in the dialog. For example, this enables you to delegate to a custom
validation policy used by multiple Web Services.
|
|
Routing
|
If you wish to use a dedicated routing policy to send all messages on to the
Web Service, select this checkbox, and click the browse button to configure a
policy in the dialog. For example, this enables you to delegate to a custom
routing policy used by multiple Web Services.
|
|
WSDL Access Options
|
Select whether to make the WSDL for this Web Service available to clients. The
Allow the Enterprise Gateway to publish WSDL to clients checkbox is
selected by default. The published WSDL represents a virtualized view of the Web
Service. Clients can retrieve the WSDL from the Enterprise Gateway, generate SOAP requests,
and send them to the Enterprise Gateway, which routes them on to the Web Service. For more
details, see Publishing the WSDL.
|
These options enable you to configure the underlying auto-generated Service Handler (Web
Service Filter) without having to navigate to it in the Policies tree.
These are the most commonly modified Web Service Filter options after importing
a WSDL file. Changes made in the Summary dialog are visible in the underlying
Web Service Filter. For more details, see the Web
Service Filter topic.
You can also access these options under the Listeners node after the WSDL file has
been imported. Right-click the appropriate Web Service Resolver node, and select Quick-Edit
Policy to display a dialog that enables you to configure these options.
|
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, 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.
Web Service Resolver
A new Web Service Resolver node is created for each imported Web Service in the
Services tree view. The Web Service Resolver is used to identify
messages destined for this Web Service, and to map them to the Service
Handler (Web Service Filter) for the Web Service.
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 the Web Service Filter topic.
Policy Container
A container for the newly generated policies is created under the Generated Policies
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.
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.
Publishing to UDDI
For details on how to publish a WSDL file registered in the Web Services Repository to
a UDDI directory, see the Publishing WSDL Files
to a UDDI Registry topic.
|
|