The WSIT Tutorial

Chapter 2 Introduction to WSIT

This tutorial describes how to use the Web Services Interoperability Technologies (WSIT), a product of Sun Microsystems web services interoperability effort to develop Java clients and service providers that interoperate with Microsoft .NET 3.0 clients and service providers.

What is WSIT?

Sun is working closely with Microsoft to ensure interoperability of web services enterprise technologies such as message optimization, reliable messaging, and security. The initial release of WSIT is a product of this joint effort. WSIT is an implementation of a number of open web services specifications to support enterprise features. In addition to message optimization, reliable messaging, and security, WSIT includes a bootstrapping and configuration technology. Figure 2–1 shows the underlying services that were implemented for each technology.

Figure 2–1 WSIT Web Services Features

Diagram showing WSIT web services features:
Core XML, Core Web Services, Bootstrapping, Security, and Reliability

Starting with the core XML support currently built into the Java platform, WSIT uses or extends existing features and adds new support for interoperable web services. See the following sections for an overview of each feature:

Bootstrapping and Configuration

Bootstrapping and configuration consists of using a URL to access a web service, retrieving its WSDL file, and using the WSDL file to create a web service client that can access and consume a web service. The process consists of the following steps, which are shown in Figure 2–2.

Figure 2–2 Bootstrapping and Configuration

Diagram showing bootstrapping and configuration

  1. Client acquires the URL for a web service that it wants to access and consume. How you acquire the URL is outside the scope of this tutorial. For example, you might look up the URL in a Web Services registry.

  2. The client uses the URL and the wsimport tool to send a MetadataExchangeRequest to access the web service and retrieve the WSDL file. The WSDL file contains a description of the web service endpoint, including WS-Policy assertions that describe the security and/or reliability capabilities and requirements of the service. The description describes the requirements that must be satisfied to access and consume the web service.

  3. The client uses the WSDL file to create the web service client.

  4. The web service client accesses and consumes the web service.

Chapter 4, Bootstrapping and Configuration explains how to bootstrap and configure a web service client and a web service endpoint that use the WSIT technologies.

Message Optimization Technology

A primary function of web services applications is to share data among applications over the Internet. The data shared can vary in format and include large binary payloads, such as documents, images, music files, and so on. When large binary objects are encoded into XML format for inclusion in SOAP messages, even larger files are produced. When a web service processes and transmits these large files over the network, the performance of the web service application and the network are negatively affected. In the worst case scenario the effects are as follows:

One way to deal with this problem is to encode the binary objects so as to optimize both the SOAP application processing time and the bandwidth required to transmit the SOAP message over the network. In short, XML needs to be optimized for web services. This is the exactly what the Message Optimization technology does. It ensures that web services messages are transmitted over the Internet in the most efficient manner.

Sun recommends that you use message optimization if your web service client or web service endpoint will be required to process binary encoded XML documents larger than 1KB.

For instructions on how to use the Message Optimization technology, see Chapter 5, Message Optimization.

Reliable Messaging Technology

Reliable Messaging is a Quality of Service (QoS) technology for building more reliable web services. Reliability is measured by a system’s ability to deliver messages from point A to point B without error. The primary purpose of Reliable Messaging is to ensure the delivery of application messages to web service endpoints.

The reliable messaging technology ensures that messages in a given message sequence are delivered at least once and not more than once and optionally in the correct order. When messages in a given sequence are lost in transit or delivered out of order, this technology enables systems to recover from such failures. If a message is lost in transit, the sending system retransmits the message until its receipt is acknowledged by the receiving system. If messages are received out of order, the receiving system may re-order the messages into the correct order.

The Reliable Messaging technology can also be used to implement session management. A unique message sequence is created for each client-side proxy, and the lifetime of the sequence identifier coincides with the lifetime of the proxy. Therefore, each message sequence can be viewed as a session and can be used to implement session management.

You should consider using reliable messaging if the web service is experiencing the following types of problems:

To help decide whether or not to use reliable messaging, weigh the following advantages and disadvantages:

For instructions on how to use the Reliable Messaging technology, see Chapter 6, Using Reliable Messaging.

Security Technology

Until now, web services have relied on transport-based security such as SSL to provide point-to-point security. WSIT implements WS-Security so as to provide interoperable message content integrity and confidentiality, even when messages pass through intermediary nodes before reaching their destination endpoint. WS-Security as provided by WSIT is in addition to existing transport-level security, which may still be used.

WSIT also enhances security by implementing WS-Secure Conversation, which enables a consumer and provider to establish a shared security context when a multiple-message-exchange sequence is first initiated. Subsequent messages use derived session keys that increase the overall security while reducing the security processing overhead for each message.

Further, WSIT implements two additional features to improve security in web services:

WSIT implements these features in such a way as to ensure that web service binding security requirements, as defined in the WSDL file, can interoperate with and be consumed by WSIT and WCF endpoints.

For instructions on how to use the WS-Security technology, see Chapter 7, Using WSIT Security.

How WSIT Relates to Windows Communication Foundation (WCF)

Web services interoperability is an initiative of Sun and Microsoft. The goal is to produce web services consumers and producers that support platform independence, and then to test and deliver products to market that interoperate across different platforms.

WSIT is the product of Sun’s web services interoperability initiative. Windows Communication Foundation (WCF) is Microsoft’s unified programming model for building connected systems. WCF, which is now available as part of the .NET Framework 3.0 product, includes application programming interfaces (APIs) for building secure, reliable, transacted web services that interoperate with non-Microsoft platforms.

In a joint effort, Sun Microsystems and Microsoft are testing WSIT against WCF to ensure that Sun web service clients (consumers) and web services (producers) do in fact interoperate with WCF web services applications and vice versa. The testing will ensure that the following interoperability goals are realized:

Sun is building WSIT on the Java platform and Microsoft is building WCF on the .NET 3.0 platform. The sections that follow describe the web services specifications implemented by Sun Microsystems in Web Services Interoperability Technologies (WSIT) and provide high-level descriptions of how each WSIT technology works.

Note –

Because WSIT-based clients and services are interoperable, you can gain the benefits of WSIT without using WCF.

WSIT Specifications

The specifications for bootstrapping and configuration, message optimization, reliable messaging, and security technologies are discussed in the following sections:

WSIT 1.0 implements the specification versions listed in Table 2–1.

Table 2–1 WSIT Specification Versions




WS-MetadataExchange v1.1 

Reliable Messaging 

WS-ReliableMessaging v1.0 

WS-ReliableMessaging Policy v1.0 

Atomic Transactions 

WS-AtomicTransaction v1.0 

WS-Coordination v1.0 


WS-Security v1.1 

WS-SecurityPolicy v1.1 

WS-Trust v1.0 

WS-SecureConversation v1.0 


WS-Policy v1.2 

WS-PolicyAttachment v1.2 

The same versions of these specifications are also implemented in WCF in .NET 3.0. Sun will update to the standard versions of these specifications in a future release of WSIT. Those versions will coincide with the versions used in WCF in .NET 3.5.

Bootstrapping and Configuration Specifications

Bootstrapping and configuring involves a client getting a web service URL (perhaps from a service registry) and obtaining the information needed to build a web services client that is capable of accessing and consuming a web service over the Internet. This information is usually obtained from a WSDL file. Figure 2–3 shows the specifications that were implemented to support bootstrapping and configuration.

Figure 2–3 Bootstrapping and Configuration Specifications

Diagram of bootstrapping and configuration specifications

In addition to the Core XML specifications, bootstrapping and configuration was implemented using the following specifications:

Message Optimization Specifications

Message optimization is the process of transmitting web services messages in the most efficient manner. It is achieved in web services communication by encoding messages prior to transmission and then de-encoding them when they reach their final destination.

Figure 2–4 shows the specifications that were implemented to optimize communication between two web service endpoints.

Figure 2–4 Message Optimization Specifications

Diagram of message optimization specifications

In addition to the Core XML specifications, optimization was implemented using the following specifications:

Reliable Messaging Specifications

Reliability is measured by a system’s ability to deliver messages from point A to point B without error. Figure 2–5 shows the specifications that were implemented to ensure reliable delivery of messages between two web services endpoints.

Figure 2–5 Reliable Messaging Specifications

Diagram of reliable messaging specifications

In addition to the Core XML specifications and supporting standards (Web Services Security and Web Services Policy, which are required building blocks), the reliability feature is implemented using the following specifications:

Security Specifications

Figure 2–6 shows the specifications implemented to secure communication between two web service endpoints and across intermediate endpoints.

Figure 2–6 Web Services Security Specifications

Diagram of web services security specifications

In addition to the Core XML specifications, the security feature is implemented using the following specifications:

How the WSIT Technologies Work

The following sections provide a high-level description of how the message optimization, reliable messaging, and security technologies work.

How Message Optimization Works

Message optimization ensures that web services messages are transmitted over the Internet in the most efficient manner. Because XML is a textual format, binary files must be represented using character sequences before they can be embedded in an XML document. A popular encoding that permits this embedding is known as base64 encoding, which corresponds to the XML Schema data type xsd:base64Binary. In a web services toolkit that supports a binding framework, a value of this type must be encoded before transmission and decoded before binding. The encoding and decoding process is expensive and the costs increase linearly as the size of the binary object increases.

Message optimization enables web service endpoints to identify large binary message payloads, remove the message payloads from the body of the SOAP message, encode the message payloads using an efficient encoding mechanism (effectively reducing the size of the payloads), re-insert the message payloads into the SOAP message as attachments (the file is linked to the SOAP message body by means of an Include tag). Thus, message optimization is achieved by encoding binary objects prior to transmission and then de-encoding them when they reach there final destination.

The optimization process is really quite simple. To effect optimized message transmissions, the sending endpoint checks the body of the SOAP message for XML encoded binary objects that exceed a predetermined size and encodes those objects for efficient transmission over the Internet.

SOAP MTOM, paired with the XML-binary Optimized Packaging (XOP), addresses the inefficiencies related to the transmission of binary data in SOAP documents. Using MTOM and XOP, XML messages are dissected in order to transmit binary files as MIME attachments in a way that is transparent to the application. This transformation is restricted to base64 content in canonical form as defined in XSD Datatypes as specified in XML Schema Part 2: Datatypes Second Edition, W3C Recommendation 28 October 2004.

Thus, the WSIT technology achieves message optimization through an implementation of the MTOM and XOP specifications. With the message optimization feature enabled, small binary objects are sent in-line in the SOAP body. For large binary objects, this becomes quite inefficient, so the binary object is separated from the SOAP body, encoded, sent as an attachment to the SOAP message, and decoded when it reaches its destination endpoint.

How Reliable Messaging Works

When reliable messaging is enabled, messages are grouped into sequences, which are defined by the client’s proxies. Each proxy corresponds to a message sequence, which consists of all of the request messages for that proxy. Each message contains a sequence header. The header includes a sequence identifier that identifies the sequence and a unique message number that indicates the order of the message in the sequence. The web service endpoint uses the sequence header information to group the messages and, if the Ordered Delivery option is selected, to process them in the proper order. Additionally, if secure conversation is enabled, each message sequence is assigned its own security context token. The security context token is used to sign the handshake messages that initialize communication between two web service endpoints and subsequent application messages.

Thus, using the Reliable Messaging technology, web service endpoints collaborate to determine which messages in a particular application message sequence arrived at the destination endpoint and which messages require resending. The reliable messaging protocol requires that the destination endpoint return message-receipt acknowledgements that include the sequence identifier and the message number of each message received. If the source determines that a message was not received by the destination, it resends the message and requests an acknowledgement. Once the source has sent all messages for a given sequence and their receipt has been acknowledged by the destination, the source terminates the sequence.

The web service destination endpoint in turn sends the application messages along to the application. If ordered delivery is configured (optional), the destination endpoint reconstructs a complete stream of messages for each sequence in the exact order in which the messages were sent and sends them along to the destination application. Thus, through the use of the reliable messaging protocol, the destination endpoint is able to provide the following delivery assurances to the web service application:

Figure 2–7 shows a simplified view of client and web service application message exchanges when the Reliable Messaging protocol is not used.

Figure 2–7 Application Message Exchange Without Reliable Messaging

Diagram of application message exchange without reliable

When the Reliable Messaging protocol is not used, application messages flow over the HTTP connection with no delivery assurances. If messages are lost in transit or delivered out of order, the communicating endpoints have no way of knowing.

Figure 2–8 shows a simplified view of client and web service application message exchanges when reliable messaging is enabled.

Figure 2–8 Application Message Exchange with Reliable Messaging Enabled

Diagram of application message exchange with reliable
messaging enabled

With reliable messaging enabled, the Reliable Messaging source module is plugged into the JAX-WS web service client. The source module transmits the application messages and keeps copies of the messages until their receipt is acknowledged by the destination module through the exchange of protocol messages. The destination module acknowledges messages and optionally buffers them for ordered-delivery guarantee. After guaranteeing order, if configured, the destination module allows the messages to proceed through the JAX-WS dispatch for delivery to the endpoint or application destination.

How Security Works

The following sections describe how the WSIT security technologies, security policy, trust, and secure conversation work.

How Security Policy Works

The WSIT Web Service Security Policy implementation builds on the features provided by the Web Service Policy implementation in WSIT. It enables users to use XML elements to specify the security requirements of a web service endpoint, that is, how messages are secured on the communication path between the client and the web service. The web service endpoint specifies the security requirements to the client as assertions (see Figure 2–9).

Figure 2–9 Security Policy Exchange

Diagram of security policy exchange

The security policy model uses the policy specified in the WSDL file for associating policy assertions with web service communication. As a result, whenever possible, the security policy assertions do not use parameters or attributes. This enables first-level, QName-based assertion matching to be done at the framework level without security domain-specific knowledge. The first-level matching provides a narrowed set of policy alternatives that are shared by the client and web service endpoint when they attempt to establish a secure communication path.

Note –

A QName is a qualified name, as specified by the XML Schema Part2: Datatypes specification, Namespaces in XML, and Namespaces in XML Errata. A qualified name is made up of a namespace URI, a local part, and a prefix.

The benefit of representing security requirements as assertions is that QName matching is sufficient to find common security alternatives and that many aspects of security can be factored out and reused. For example, it may be common that the security mechanism is constant for a web service endpoint, but that the message parts that are protected, or secured, may vary by message action.

The following types of assertions are supported:

How Trust Works

Figure 2–10 shows how the Web Services Trust technology establishes trust.

Figure 2–10 Trust and Secure Conversation

Diagram of trust and secure conversation

    To establish trust between a client, a Security Token Service, and a web service:

  1. The client establishes an HTTPS connection with the Secure Token Service using one of the following methods:

    • Username Authentication and Transport Security: The client authenticates to the Security Token Service using a username token. The Security Token Service uses a certificate to authenticate to the Client. Transport security is used for message protection.

    • Mutual Authentication: Both the client-side and server-side use X509 certificates to authenticate to each other. The client request is signed using Client’s X509 certificate, then signed using ephemeral key. The web service signs the response using keys derived from the client’s key.

  2. The client sends a RequestSecurityToken message to the Security Token Service.

  3. The Security Token Service sends a Security Assertion Markup Language (SAML) token to the Client.

  4. The client uses the SAML token to authenticate itself to the web service and trust is established.

All communication uses SOAP messages.

How Secure Conversation Works

Figure 2–11 shows how the Web Services Secure Conversation technology establishes a secure conversation when the Trust technology is not used.

Figure 2–11 Secure Conversation

Diagram of secure conversation

    To establish a secure conversation between a Client and a web service:

  1. The client sends a X509 Certificate to authenticate itself to the web service.

  2. The web service sends a X509 Certificate to authenticate itself to the client.

All communication uses SOAP messages.