The Web Services Policy Framework (WS-Policy) provides a standard mechanism to express the capabilities, requirements, and general characteristics of a Web service as policies. A service provider uses a policy to convey conditions under which it provides services to a Web service client. The information shared by the Web service through a policy can be used by the client to determine how to communicate with the Web service.

IBM® Rational® Application Developer Version 7.5 enables a Web service provider that uses IBM® WebSphere® Application Server V7.0 to share the policy configuration with the client in two ways:

• Share Policy Configuration in a published WSDL (Web Services Description Language) file or a WSDL file acquired through an HTTP GET request.
• Share Policy Configuration in a WSDL file acquired via WS-MetadataExchange GetMetadata request.

The WS-MetadataExchange

A Web service uses metadata, such as WSDL, an XML schema, and WS-Policy, to describe what a Web service client needs to interact with the Web service. To communicate effectively with a Web service, it is important for a Web service client to retrieve the metadata. WS-MetadataExchange, a Web service specification, defines a standard way to encapsulate the metadata of a Web service. It also specifies mechanisms for the retrieval of metadata (for example: GetMetdata).

The advantage of using WS-MetadataExchange over an HTTP GET request is the ability to securely share policy configuration with the Web service client. To learn more about WS-MetadataExchange, see the WS-MetadataExchange specification, which is cited in the Resources section.

Back to top

The policy set

A policy set is a collection of policies that provides qualities of protection for Web services. For example, the WebSphere Application Server V7.0 WS-I (RSP Reliable Secure Profile) policy set (see Resources) consists of WS-Security, WS-Addressing, and WS-ReliableMessaging policy types. These policy types (in combination or on their own) provide the following qualities of protection:

• Reliable message delivery to the intended receiver in the presence of software, system, or network failure by enabling WS-ReliableMessaging.
• Message confidentiality through encryption that includes encrypting the message body and signature elements using WS-Security and WS-SecureConversation (an extension of WS-Security).
• Message integrity (ensuring that messages have originated from an appropriate sender and were not modified during transmission) through digital signature that includes signing the message body, time stamp, WS-Addressing and WS-ReliableMessaging headers using WS-Security and WS-SecureConversation. The WS-Addressing headers allow uniform addressing of messages to and from the Web service in a transport-independent way.

WebSphere Application Server V7.0 provides several policy set templates that you can tailor to your requirements. This article demonstrates using the WS-Policy support in Rational Application Developer V7.5 by applying WS-I RSP policy set to a Web service provider and client.

The details of WS-Policy and the various policy specifications are beyond the scope of this article. However, see Resources for a link to further details.

Back to top

Benefits of Web services framework (WS-Policy)

WS-Policy enables a Web service client to communicate with the Web service provider yet minimizes out-of-band information. This information (such as paper notes and e-mail exchanges between software developers) is required for applications to communicate with each other under actual business conditions, such as security and reliability. Consider the following example in the absence of WS-Policy.

The WS-I RSP policy set enables secure and reliable message transmission between a Web service provider and client. The IT department of a multinational bank wants to host a Web service from its global headquarters in New York. Due to the sensitive data that a banking business transmits, the Web service provider in New York equips the Web service with the WS-I RSP policy set. Each of the bank's regional headquarters runs a Web service client that is configured to communicate with the Web service hosted in New York.

If the Web service in New York is altered to use a different policy set, then the Web service application provider in New York has to send a notice containing configuration information to each of its clients. However, if the Web service provider and the client were to use the WS-Policy framework, they would not have to exchange policy configuration information through manual means such as e-mail exchanges, because the new policy configuration would have been shared by the Web service provider automatically using the WS-Policy framework.

Back to top

Add the WS-I RSP policy set to the JAX-WS Web service

Prerequisite:To follow the example in this article, you need Rational Application Developer V7.5 installed with at least the WebSphere V7.0 test server.

Import the project

1. Download the simpleProject.zip file from the Downloads section into your file system. This file is a project interchange file that contains a simple Web service and a Web service client.
2. Launch Rational Application Developer by selecting Programs > IBM Software Delivery Platform > IBM Rational Application Developer 7.5 > IBM Rational Application Developer from the start menu.
3. Import the project into Rational Application Developer as shown in Figures 1, 2, and 3 by clicking File > Import > other > Project Interchange.

4. In the From zip file text box, enter the name of the file that you want to import, as shown in Figure 3. This will be the absolute path of the simpleProject.zip file that you downloaded in Step 1.

5. Click Select All and then click Finish.
6. This previous operation imports a Web service, a Web service client, and the corresponding EAR (enterprise archive) files that hold the service project and client project.

Deploy projects to WebSphere Application Server V7.0

1. Start the WebSphere Application Server V7.0 by right-clicking WebSphere Application Server V7.0 at localhost in the server editor and selecting Start, as shown in Figure 4.

2. Add the Web service and Web service client projects to the WebSphere Application Server V7.0 by right clicking WebSphere Application Server V7.0 at localhost in the server editor and selecting Add and Remove Projects, as shown in Figure 5.

3. Select Add All and click Finish, as shown in Figure 6. This will deploy the Web service and Web service client on the WebSphere Application Server V7.0

Attach the WS-I RSP policy set to the Web service provider

1. Click the Services Tab, which is adjacent to the Enterprise Explorer tab, as Figure 7 shows.

2. Right-click HelloWorldService under the JAX-WS (the Java API for XML Web Services) node and select Manage Policy Set Attachment (Figure 8).

3. The application table will be empty (as shown in Figure 9) indicating that the simpleWebServiceProjectEAR application does not have any policy set attached to it. Click the Add button to add a policy set to the Web service contained in the simpleWebServiceProjectEAR application.

4. Ensure that the settings shown in Figure 10 are set in your endpoint definition dialog:
   • Service Name: simpleWebServiceProject.war:{http://test/}HelloWorldService
   • Endpoint: <all endpoints>
   • Policy Set: WS-I RSP
   • Binding: Provider sample

5. Click OK and then click Ignore All on the warning dialog. The WS-I RSP policy set is now attached to simpleWebServiceProjectEAR's HelloWorldService, as indicated in the Add Policy Set Attachment to Service page. The settings that you selected previously are now visible in the table, as shown in Figure 11.

The WS-I RSP policy set that you attached to the HelloWorldService must be shared with the Web service client. You will do this by following Steps 16 through 20.

6. Click the Next button to move to the Configure Policy Sharing page.
7. Click the Configure button on Configure Policy Sharing dialog, as shown in Figure 12.

8. You will be presented with two options for sharing the policy configuration. For this exercise, select the option to Share Policy Information via WSDL (Figure 13). This option allows a service to share policy configuration in a WSDL file acquired through an HTTP GET request.

9. Click OK. The configure policy sharing dialog should indicate that the HelloWorldService is sharing the policy.
10. Click Finish. You have now configured the Web service provider to share the policy set configuration in a WSDL file acquired through an HTTP GET request. To fully exploit the WS-Policy feature, you need to enable the Web service client to acquire the Web service provider policy set configuration. You will do that in Steps 1-5.

Acquire the WSDL file with the policy configuration

1. Select the Services Tab adjacent to the Enterprise Explorer tab (see Figure 7), and then right-click HelloWorldService under the JAX-WS node to select Show > WSDL Interface, as shown in Figure 14. The Show > WSDL Interface command acquires the WSDL file through the HTTP GET request mechanism that was discussed in the introduction to this article.

2. Click the Source tab at the bottom-left corner of the WSDL editor (see Figure 15).

The policy configuration is embedded in the <wsp:Policy> tags of the WSDL, which you should be able to see now.

Listing 1 shows a snippet of the WSDL that contains that <wsp:Policy> tags.

<addressing:Addressing xmlns:addressing="http://www.w3.org/2007/05/addressing/metadata">
lt;wsp:Policy>
     <wsp:ExactlyOne>
         <wsp:All>
         </wsp:All>
     </wsp:ExactlyOne>
   </wsp:Policy>
</addressing:Addressing>

Back to top

Attach the WS-I RSP policy set to the Web service client

1. Go to the Services view, right-click the HelloWorldService client under the client node, and then select Manage Policy Set Attachment.

2. Highlight <all services> and then select Use Provider Policy, as shown in Figure 17. Highlighting <all services> ensures that each of the service clients in the simpleWebClientEAR will be configured to acquire provider policy.

3. Because you configured the Web service provider to share policy configuration in a WSDL file acquired through an HTTP GET request, the corresponding Web service client must be configured to use an HTTP GET request to receive the WSDL that contains the policy configuration from the provider. Therefore, select HTTP Get request targeted at, as Figure 18 shows.

4. Click OK.
5. Click Finish. You have now configured the Web service client to acquire the policy configuration from the Web service provider.

Back to top

Examine the policy control files

1. In the Enterprise Explorer tab, expand simpleWebServiceProjectEAR > META-INF and simpleWebClientEAR > META-INF.
2. Double-click the files highlighted in Figure 19 (wsPolicyServiceControl.xml and wsPolicyClientControl.xml).

The wsPolicyServiceControl.xml file indicates that the policy configuration will be shared through WSDL acquired via an HTTP GET request, as shown in the following tag pair:

<ExportPolicySetConfigurationInWSDL>true</ExportPolicySetConfigurationInWSDL>

The wsPolicyClientControl.xml file indicates that the policy configuration will be acquired through WSDL by using an HTTP GET request, as shown in the following two tag pairs:

<ProviderPolicyAcquisition>
<PolicyAcquisitionClass>com.ibm.ws.wspolicy.acquisition.
		AcquireViaQWSDL</PolicyAcquisitionClass>
</ProviderPolicyAcquisition>

You now know how to use the functionality in Rational Application Developer to configure WebSphere Application Server V7.0 policy sets and share them by using the WS-Policy framework.

Back to top

Acknowledgements

The author thanks Yen Lu and Zina Mostafia for their diligent review of this article.

Back to top

Download

Information about download methods

Resources

Learn

• Learn more about WS-Policy and the various policy types.
  
  
• Read the WS-MetadataExchange specification.
  
  
• Read the WS-I RSP policy.
  
  
• Learn more about how Rational Application Developer for WebSphere Software extends Eclipse with visual development features.
  
  
• For technical resources, visit the Rational Application Developer area on developerWorks, where you will find technical documentation, how-to articles, downloads, and product information.
  
  
• Discover more about WebSphere Application Server V7.0 on the IBM WebSphere marketing Web site.
  
  
• Visit the Rational software area on developerWorks for technical resources and best practices for Rational Software Delivery Platform products.
  
  
• Subscribe to the IBM developerWorks newsletter, a weekly update on the best of developerWorks tutorials, articles, downloads, community activities, webcasts and events.
  
  
• Subscribe to the Rational Edge newsletter for articles on the concepts behind effective software development.
  
  
• Read Tackling the challenges of software development with Rational Application Developer for WebSphere Software by Lee Ackerman and S. Mahate to find out more about how Rational Application Developer V7.5 can help you deliver Web and service-oriented applications (IBM developerWorks, September 2008).
  
  

Get products and technologies

• Download trial versions of IBM Rational software.
  
  
• Download these IBM product evaluation versions and get your hands on application development tools and middleware products from DB2®, Lotus®, Tivoli®, WebSphere®, and Rational®.
  
  

Discuss

• Check out developerWorks blogs and get involved in the developerWorks community.
  
  
• Join the Rational Application Developer forum on developerWorks.
  
  

About the author

Rakan Khalid is a Cognos Solution Architect at the IBM Software Group. Rakan holds a BSc in Computer Science with First Class Honours from York University. He has worked on a broad spectrum of IBM software products including DB2 Database Management System, WebSphere Application Server, and Rational Application Developer as the Web Services Function Test Lead. In his current role as a Cognos Solution Architect, Rakan is responsible to strategise and build competitive technological and business solutions to win clients in the business intelligence software landscape.

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• The WS-MetadataExchange
• The policy set
• Benefits of Web services framework (WS-Policy)
• Add the WS-I RSP policy set to the JAX-WS Web service
• Attach the WS-I RSP policy set to the Web service client
• Examine the policy control files
• Acknowledgements
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: Rational Application Developer for WebSphere Software
• Demo: Build, test and deploy JAX-WS Web services
• Webcast: Webcast: Develop innovative applications efficiently using the right application foundation in today's economy
• Briefing: Software development conference
• Buy: Rational Application Developer for WebSphere Software

My developerWorks community

Dig deeper into Rational on developerWorks

Try Rational System Architect

See how this fully integrated collection of models and documents can help you better align your IT systems and infrastructure to simplify business processes

Special offers