Java GUY

About Java, web services,hibernate.

Unlike PHP, Java Servlet and JSP do not have build-in mechanisms for handling form-based file uploads. One solution to this problem is to implement a function yourself to extract uploaded files contained in an HTTP request. However, a better choice is to make use of a third-party library that can help us handle file uploads.

One robust library available is the Apache Jakarta Commons FileUpload package. It is open-source and can be downloaded free of charge over the Internet. We will demonstrate how to use the Apache Jakarta Commons FileUpload package to extract uploaded files submitted from a form. The techniques are the same for HTML and XHTML. If you are not familiar with JSP or Java Servlet, you may want to read some introductory tutorials before going through this section.

Downloading the Apache Jakarta Commons FileUpload and Commons IO Libraries

To download the Apache Jakarta Commons FileUpload library, go to the home page of the Apache Jakarta Commons FileUpload project and navigate to the download section. The binaries are available in two file formats: zip format and tar-gzip format. Download either one of them and uncompress the file. Then go to the home page of the Apache Jakarta Commons IO project and repeat the same steps. We need the Commons IO library since Commons FileUpload uses it internally. Now you have two JAR files, “commons-fileupload-version.jar” and “commons-io-version.jar”, where version is the version number. At the time of writing, the latest version of the Commons FileUpload library and that of the Commons IO library are 1.1.1 and 1.2 respectively. So, the JAR files we obtain are “commons-fileupload-1.1.1.jar” and “commons-io-1.2.jar”.

At the time of writing, the most up-to-date version of the Apache Jakarta Commons FileUpload library is 1.1.1. So, we assume you are using Commons FileUpload 1.1.1 in this tutorial. For other versions of Commons FileUpload, the procedures may be slightly different but the principle is the same.

Installing Apache Jakarta Commons FileUpload and Commons IO into a Servlet/JSP Container Like Tomcat
Next, we need to install the Apache Jakarta Commons FileUpload library and the Apache Jakarta Commons IO library into a Servlet/JSP container such as Apache Tomcat. To do this, copy the JAR files “commons-fileupload-1.1.1.jar” and “commons-io-1.2.jar” to the /WEB-INF/lib/ directory in the document root of your web application.

Note that JAR libraries stored in /WEB-INF/lib/ will be available to the containing web application only. If you want to share the libraries among all web applications installed in Tomcat (suppose you are using Tomcat 5 or Tomcat 4), the JAR files should be copied to the $CATALINA_HOME/shared/lib/ directory, where $CATALINA_HOME is the root of your Tomcat installation.

Checking If an HTTP Request is Encoded in Multipart Format
Now that you have installed the Apache Jakarta Commons FileUpload library, you can start writing the code. First, we have to make sure the HTTP request is encoded in multipart format. This can be done using the static method isMultipartContent() of the ServletFileUpload class of the org.apache.commons.fileupload.servlet package:

if (ServletFileUpload.isMultipartContent(request)){
// Parse the HTTP request…
}

In the above Java code snippet, request is a javax.servlet.http.HttpServletRequest object that encapsulates the HTTP request. It should be very familiar to you if you know Java Servlet or JSP.

Parsing Form Data with Java Servlet / JSP
Second, we will parse the form data contained in the HTTP request. Parsing the form data is very straightforward with the Apache Jakarta Commons FileUpload library:

ServletFileUpload servletFileUpload = new ServletFileUpload(new DiskFileItemFactory());
List fileItemsList = servletFileUpload.parseRequest(request);

(In the above Java code snippet, DiskFileItemFactory is a class contained in the org.apache.commons.fileupload.disk package and List is an interface contained in the java.util package.)

If everything works fine, fileItemsList will contain a list of file items that are instances of FileItem of the org.apache.commons.fileupload package. A file item may contain an uploaded file or a simple name-value pair of a form field. (More details about FileItem will be provided later.)

By default, the ServletFileUpload instance created by the above Java code uses the following values when parsing the HTTP request:

Size threshold = 10,240 bytes. If the size of a file item is smaller than the size threshold, it will be stored in the memory. Otherwise it will be stored in a temporary file on disk.

Maximum HTTP request body size = -1, which means the server will accept HTTP request bodies of any size.

Repository = System default temp directory, whose value can be found by the Java code System.getProperty(“java.io.tmpdir”). Temporary files will be stored there.

If you do not like the default settings, you can change them using the methods setSizeThreshold() and setRespository() of the DiskFileItemFactory class and the setSizeMax() method of the ServletFileUpload class, like this:

DiskFileItemFactory diskFileItemFactory = new DiskFileItemFactory();
diskFileItemFactory.setSizeThreshold(40960); /* the unit is bytes */

File repositoryPath = new File(“/temp”);
diskFileItemFactory.setRepository(repositoryPath);

ServletFileUpload servletFileUpload = new ServletFileUpload(diskFileItemFactory);
servletFileUpload.setSizeMax(81920); /* the unit is bytes */

(In the above Java code snippet, File is a class of the java.io package.)

If the size of the HTTP request body exceeds the maximum you set, the SizeLimitExceededException exception (fully qualified name: org.apache.commons.fileupload.FileUploadBase.SizeLimitExceededException) will be thrown when you call the parseRequest() method:

try {
List fileItemsList = servletFileUpload.parseRequest(request);
/* Process file items… */
}
catch (SizeLimitExceededException ex) {
/* The size of the HTTP request body exceeds the limit */
}

Iterating through File Items
Third, we will iterate through the file items and process each of them. The isFormField() method of the FileItem interface is used to determine whether a file item contains a simple name-value pair of a form field or an uploaded file:

Iterator it = fileItemsList.iterator();
while (it.hasNext()){
FileItem fileItem = (FileItem)it.next();
if (fileItem.isFormField()){
/* The file item contains a simple name-value pair of a form field */
}
else{
/* The file item contains an uploaded file */
}
}

(In the above Java code snippet, Iterator is an interface in the java.util package and FileItem is an interface in the org.apache.commons.fileupload package.)

Problem(Abstract)

Sometimes it is necessary to control how long a Web Service client waits for a response after sending a request. This document discusses Java™ API for XML-based Remote Procedure Call (JAX-RPC) clients only and not SOAP with Attachments API for Java (SAAJ) or Dynamic Invocation Interface (DII) clients.

SymptomIn IBM WebSphere Application Server Version 6.0, the following error occurs if a JAX-RPC Web service client times out:

java.net.SocketTimeoutException: Socket operation timed out before it could be completed

In Application Server Version 5.1, the following error message occurs:

java.net.SocketTimeoutException: Read timed out

Resolving the problemFor a JSR 109-compliant JAX-RPC client,

there are Web service client deployment descriptors that are packaged with the application. Specifically, the ibm-webservicesclient-bnd.xmi deployment descriptor is used to control the client timeout. This deployment descriptor has a syncTimeout property. The default for this timeout value is 5 seconds. To set the syncTimeout property, see the following directions in the Information Center for WebSphere Application Server:

Configuring the ibm-webservicesclinet-bnd.xmi deployment descriptor – Version 6.0

Configuring the ibm-webservicesclient-bnd.xmi deployment descriptor – Version 5.1
Some JAX-RPC clients do not have this deployment descriptor. These clients are not JSR 109-compliant. You can alternatively set the timeout value on the stub using the setTimeout method. Here is sample code to set the timeout value on a stub:

package mypackage;
import com.ibm.ws.webservices.engine.client.Stub;

public class J2SEClient {
public static void main(String[] args) {
try
{
HelloWorldServiceLocator hwsl = new HelloWorldServiceLocator();
HelloWorld hw = hwsl.getHelloWorld();
((Stub) hw).setTimeout(60000);
hw.sayHello();
}
catch(Exception e)
{
e.printStackTrace();
}
}
}

In the previous sample code, the parameter for the setTimeout method is the number of milliseconds the client should wait for a response from the provider.

To ensure that this timeout is set properly in WebSphere Application Server V6.0, the following trace specification can be used:

com.ibm.ws.webservices.engine.*=all

In the trace, the HttpOutboundChannelConnection class will output the following:

WSWS3494I: syncTimeout value is 420 seconds to wait for response to the current SOAP over HTTP request.

Notes:
The operating system timeouts might cause the connection to time out before the syncTimeout length.

Setting the time-out to 0 will prevent the readTimeout from happening (for example, the client will not time out)

Understanding Web Services Policy

 Summary

Understanding Web Services Policy is an introductory description of the Web Services Policy language. This document describes the policy language features using numerous examples. The associated Web Services Policy Framework and Web Services Policy Attachment specifications provide the complete normative description of the Web Services Policy language.

Contents

1. Introduction
2. Basic Concepts: Policy Expression
3. Advanced Concepts I: Policy Expression
4. Advanced Concepts II: Policy Assertion Design
5. Conclusion

1. Introduction

This document, Understanding Web Services Policy, provides an introductory description of the Web Services Policy language and should be read alongside the formal descriptions contained in the WS-Policy and WS-PolicyAttachment specifications.

This document is:

  • for policy expression authors who need to understand the syntax of the language and understand how to build consistent policy expressions,
  • for policy implementers whose software modules read and write policy expressions and
  • for policy assertion authors who need to know the features of the language and understand the requirements for describing policy assertions.

This document assumes a basic understanding of XML 1.0, Namespaces in XML, WSDL 1.1 and SOAP.

Each major section of this document introduces the features of the policy language and describes those features in the context of concrete examples.

Section 2 – Basic Concepts: Policy Expression – covers the basic mechanisms of Web Services Policy. It describes how to declare and combine capabilities and requirements of a Web service as policy expressions, attach policy expressions to WSDL constructs such as endpoint and message, and re-use policy expressions.

Section 3 – Advanced Concepts I: Policy Expression – this is the first advanced section that provides more in-depth materials for policy implementers and assertion authors. It explains the basics of normalizing policy expressions, merging policies, determining the compatibility (intersection) of policies, the policy data model, the policy expression and the extensibility points built into the Web Services Policy language.

Section 4 – Advanced Concepts II: Policy Assertion Design – this is the second advanced section that walks through the dimensions of a policy assertion for assertion authors. This section describes the role of policy assertions, parts of a policy assertion, when to design policy assertions, outlines guidelines for designing policy assertions and enumerates the minimum requirements for describing policy assertions in specifications.

This is a non-normative document and does not provide a definitive specification of the Web Services Policy language. Appendix C lists all the Appendix C – XML Namespaces that are used in this document. (XML elements without a namespace prefix are from the Web Services Policy XML Namespace.)

2. Basic Concepts: Policy Expression

2.1 Web Services Policy

Web services are being successfully used for interoperable solutions across various industries. One of the key reasons for interest and investment in Web services is that they are well-suited to enable service-oriented systems. XML-based technologies such as SOAP, XML Schema and WSDL provide a broadly-adopted foundation on which to build interoperable Web services. The WS-Policy and WS-PolicyAttachment specifications extend this foundation and offer mechanisms to represent the capabilities and requirements of Web services as Policies.

Service metadata is an expression of the visible aspects of a Web service, and consists of a mixture of machine- and human-readable languages. Machine-readable languages enable tooling. For example, tools that consume service metadata can automatically generate client code to call the service. Service metadata can describe different parts of a Web service and thus enable different levels of tooling support.

First, service metadata can describe the format of the payloads that a Web service sends and receives. Tools can use this metadata to automatically generate and validate data sent to and from a Web service. The XML Schema language is frequently used to describe the message interchange format within the SOAP message construct, i.e. to represent SOAP Body children and SOAP Header blocks.

Second, service metadata can describe the ‘how’ and ‘where’ a Web service exchanges messages, i.e. how to represent the concrete message format, what headers are used, the transmission protocol, the message exchange pattern and the list of available endpoints. The Web Services Description Language is currently the most common language for describing the ‘how’ and ‘where’ a Web service exchanges messages. WSDL has extensibility points that can be used to expand on the metadata for a Web service.

Third, service metadata can describe the capabilities and requirements of a Web service, i.e. representing whether and how a message must be secured, whether and how a message must be delivered reliably, whether a message must flow a transaction, etc. Exposing this class of metadata about the capabilities and requirements of a Web service enables tools to generate code modules for engaging these behaviors. Tools can use this metadata to check the compatibility of requestors and providers. Web Services Policy can be used to represent the capabilities and requirements of a Web service.

Web Services Policy is a machine-readable language for representing the capabilities and requirements of a Web service. These are called ‘policies’. Web Services Policy offers mechanisms to represent consistent combinations of capabilities and requirements, to determine the compatibility of policies, to name and reference policies and to associate policies with Web service metadata constructs such as service, endpoint and operation. Web Services Policy is a simple language that has four elements – Policy, All, ExactlyOne and PolicyReference – and one attribute – wsp:Optional.

  1. Wsp:all
  2. Wsp:ExactlyOne
  3. Wsp:OneOrMore
  4. Wsp:policy

2.2 Simple Message

Let us start by considering a SOAP Message in the example below.

SOAP Message

  

<soap:Envelope>

  <soap:Header>

    <wsa:To>http://stock.contoso.com/realquote</wsa:To>

    <wsa:Action>http://stock.contoso.com/GetRealQuote</wsa:Action>

  </soap:Header>

  <soap:Body>…</soap:Body>

</soap:Envelope>

This message uses message addressing headers. The wsa:To and wsa:Action header blocks identify the destination and the semantics implied by this message respectively. (The prefix wsa is used here to denote the Web Services Addressing XML Namespace. Appendix C lists all the Appendix C – XML Namespaces and prefixes that are used in this document.)

Let us look at a fictitious scenario used in this document to illustrate the features of the policy language. Tony is a Web service developer. He is building a client application that retrieves real time stock quote information from Contoso, Ltd. Contoso supplies real time data using Web services. Tony has Contoso’s advertised WSDL description of these Web services. Contoso requires the use of addressing headers for messaging. Just the WSDL description is not sufficient for Tony to enable the interaction between his client and these Web services. WSDL constructs do not indicate requirements such as the use of addressing.

(The example companies, organizations, products, domain names, e-mail addresses, logos, people, places, and events depicted herein are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, places, or events is intended or should be inferred.)

Providers have the option to convey requirements, such as the use of addressing, through word-of-mouth and documentation – as they always have. To interact successfully with this service, Tony may have to read any related documentation, call someone at Contoso to understand the service metadata, or look at sample SOAP messages and infer such requirements or behaviors.

Web Services Policy is a machine-readable language for representing these Web service capabilities and requirements as policies. Policy makes it possible for providers to represent such capabilities and requirements in a machine-readable form. For example, Contoso may augment the service WSDL description with a policy that requires the use of addressing. Tony can use a policy-aware client that understands this policy and engages addressing automatically.

How does Contoso use policy to represent the use of addressing? The example below illustrates a policy expression that requires the use of addressing.

Policy Expression

 

<Policy>

  <wsap:UsingAddressing />

</Policy>

The policy expression in the above example consists of a Policy main element and a child element wsap:UsingAddressing. Child elements of the Policy element are policy assertions. Contoso attaches the above policy expression to a WSDL binding description.

The wsap:UsingAddressing element is a policy assertion. (The prefix wsap is used here to denote the Web Services Addressing – WSDL Binding XML Namespace.) This assertion identifies the use of Web Services Addressing information headers. A policy-aware client can recognize this policy assertion, engage addressing automatically, and use headers such as wsa:To and wsa:Action in SOAP Envelopes.

It is important to understand the association between the SOAP message and policy expression in the above example. As you can see by careful examination of the message, there is no reference to any policy expression. Just as WSDL does not require a message to reference WSDL constructs (such as port, binding and portType), Web Services Policy does not require a message to reference a policy expression though the policy expression describes the message.

2.3 Secure Message

In addition to requiring the use of addressing, Contoso requires the use of transport-level security for protecting messages.

Secure Message

 

<soap:Envelope>

  <soap:Header>

    <wss:Security soap:mustUnderstand=”1″ >

      <wsu:Timestamp u:Id=”_0″>

        <wsu:Created>2006-01-19T02:49:53.914Z</u:Created>

        <wsu:Expires>2006-01-19T02:54:53.914Z</u:Expires>

      </wsu:Timestamp>

    </wss:Security>

    <wsa:To>http://real.contoso.com/quote</wsa:To>

    <wsa:Action>http://real.contoso.com/GetRealQuote</wsa:Action>

  </soap:Header>

  <soap:Body>…</soap:Body>

</soap:Envelope>

 

The SOAP message in the example above includes security timestamps that express creation and expiration times of this message. Contoso requires the use of security timestamps and transport-level security – such as HTTPS – for protecting messages. (The prefixes wss and wsu are used here to denote the Web Services Security and Utility namespaces.)

Similar to the use of addressing, Contoso indicates the use of transport-level security using a policy expression. The example below illustrates a policy expression that requires the use of addressing and transport-level security for securing messages.

Addressing and Security Policy Expression

 

<Policy>

  <wsap:UsingAddressing />

  <sp:TransportBinding>…</sp:TransportBinding>

</Policy>

The sp:TransportBinding element is a policy assertion. (The prefix sp is used here to denote the Web Services Security Policy XML Namespace.) This assertion identifies the use of transport-level security – such as HTTPS – for protecting messages. Policy-aware clients can recognize this policy assertion, engage transport-level security for protecting messages and include security timestamps in SOAP Envelopes.

Tony can use a policy-aware client that recognizes this policy expression and engages both addressing and transport-level security automatically.

For the moment, let us set aside the contents of the sp:TransportBinding policy assertion and consider its details in a later section.

2.4 Other Assertions

Thus far, we explored how Contoso uses policy expressions and assertions for representing behaviors that must be engaged for a Web service interaction. What is a policy assertion? What role does it play? In brief, a policy assertion is a piece of service metadata, and it identifies a domain (such as messaging, security, reliability and transaction) specific behavior that is a requirement. Contoso uses a policy assertion to convey a condition under which they offer a Web service. A policy-aware client can recognize policy assertions and engage these behaviors automatically.

Providers, like Contoso, have the option to combine behaviors for an interaction from domains such as messaging, security, reliability and transactions. Using policy assertions, providers can represent these behaviors in a machine-readable form. Web service developers, like Tony, can use policy-aware clients that recognize these assertions and engage these behaviors automatically.

Who defines policy assertions? Where are they? Policy assertions are defined by Web services developers, product designers, protocol authors and users. Like XML Schema libraries, policy assertions are a growing collection. Several WS-* protocol specifications and applications define policy assertions:

2.5 Combining Policy Assertions

Policy assertions can be combined in different ways to express consistent combinations of behaviors (capabilities and requirements). There are three policy operators for combining policy assertions: Policy, All and ExactlyOne (the Policy operator is a synonym for All).

Let us consider the All operator first. The policy expression in the example below requires the use of addressing and transport-level security. There are two policy assertions. These assertions are combined using the All operator. Combining policy assertions using the Policy or All operator means that all the behaviors represented by these assertions are required.

Addressing and Security Policy Expression

 

<All>

  <wsap:UsingAddressing />

  <sp:TransportBinding>…</sp:TransportBinding>

</All>

In addition to requiring the use of addressing, Contoso allows either the use of transport- or message-level security for protecting messages. Web Services Policy language can indicate this choice of behaviors in a machine-readable form. To indicate the use of message-level security for protecting messages, Contoso uses the sp:AsymmetricBinding policy assertion (see the example below).

Asymmetric Binding Security Policy Assertion

 

<sp:AsymmetricBinding>…</sp:AsymmetricBinding>

The sp:AsymmetricBinding element is a policy assertion. (The prefix sp is used here to denote the Web Services Security Policy namespace.) This assertion identifies the use of message-level security – such asWS-Security 1.0 – for protecting messages. Policy-aware clients can recognize this policy assertion, engage message-level security for protecting messages and use headers such as wss:Security in SOAP Envelopes.

To allow the use of either transport- or message-level security, Contoso uses the ExactlyOne policy operator. Policy assertions combined using the ExactlyOne operator requires exactly one of the behaviors represented by the assertions. The policy expression in the example below requires the use of either transport- or message-level security for protecting messages.

Transport- or Message-Level Security Policy Expression

 

<ExactlyOne>

   <sp:TransportBinding>…</sp:TransportBinding>

   <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

</ExactlyOne>

Contoso requires the use of addressing and requires the use of either transport- or message-level security for protecting messages. They represent this combination using the All and ExactlyOne operators. Policy operators can be mixed to represent different combinations of behaviors (capabilities and requirements). The policy expression in the example below requires the use of addressing and one of transport- or message-level security for protecting messages.

Addressing and Transport- OR Message-Level Security Policy Expression

 

<All>

  <wsap:UsingAddressing />

  <ExactlyOne>

     <sp:TransportBinding>…</sp:TransportBinding>

     <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

  </ExactlyOne>

</All>

Using this policy expression, Contoso gives the choice of mechanisms for protecting messages to clients (or requestors).

2.6 Optional Policy Assertion

Through a customer survey program, Contoso learns that a significant number of their customers prefer to use the Optimized MIME Serialization (as defined in the MTOM specification) for sending and receiving messages. Contoso adds optional support for the Optimized MIME Serialization and expresses this optional behavior in a machine-readable form.

To indicate the use of optimization using the Optimized MIME Serialization, Contoso uses the mtom:OptimizedMimeSerialization policy assertion (see the example below).

Optimized MIME Serialization Policy Assertion

 

<mtom:OptimizedMimeSerialization />

The mtom:OptimizedMimeSerialization element is a policy assertion. (The prefix mtom is used here to denote the Optimized MIME Serialization Policy namespace.) This assertion identifies the use of MIME Multipart/Related serialization for messages. Policy-aware clients can recognize this policy assertion and engage Optimized MIME Serialization for messages. The semantics of this assertion are reflected in messages: they use an optimized wire format (MIME Multipart/Related serialization).

Like Contoso’s optional support for Optimized MIME Serialization, there are behaviors that may be engaged (in contrast to must be engaged) for a Web service interaction. A service provider will not fault if these behaviors are not engaged. Policy assertions can be marked optional to represent behaviors that may be engaged for an interaction. A policy assertion is marked as optional using the wsp:Optional attribute. Optional assertions represent the capabilities of the service provider as opposed to the requirements of the service provider.

In the example below, the Optimized MIME Serialization policy assertion is marked optional. This policy expression allows the use of optimization and requires the use of addressing and one of transport- or message-level security.

Optional MIME Serialization, Addressing and Transport- OR Message-Level Security Policy Expression

 

<All>

  <mtom:OptimizedMimeSerialization wsp:Optional=”true”/>

  <wsap:UsingAddressing />

  <ExactlyOne>

     <sp:TransportBinding>…</sp:TransportBinding>

     <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

  </ExactlyOne>

</All>

Contoso is able to meet their customer needs by adding optional support for the Optimized MIME Serialization. An optional policy assertion represents a behavior that may be engaged.

2.7 Nested Policy Expressions

In the previous sections, we considered two security policy assertions. In this section, let us look at one of the security policy assertions in little more detail.

As you would expect, securing messages is a complex usage scenario. Contoso uses the sp:TransportBinding policy assertion to indicate the use of transport-level security for protecting messages. Just indicating the use of transport-level security for protecting messages is not sufficient. To successfully interact with Contoso’s Web services, Tony must know what transport token to use, what secure transport to use, what algorithm suite to use for performing cryptographic operations, etc. The sp:TransportBinding policy assertion can represent these dependent behaviors. In this section, let us look at how to capture these dependent behaviors in a machine-readable form.

A policy assertion – like the sp:TransportBinding – identifies a visible domain specific behavior that is a requirement. Given an assertion, there may be other dependent behaviors that need to be enumerated for a Web Service interaction. In the case of the sp:TransportBinding policy assertion, Contoso needs to identify the use of a transport token, a secure transport, an algorithm suite for performing cryptographic operations, etc. A nested policy expression can be used to enumerate such dependent behaviors.

What is a nested policy expression? A nested policy expression is a policy expression that is a child element of a policy assertion element. A nested policy expression further qualifies the behavior of its parent policy assertion.

In the example below, the child Policy element is a nested policy expression and further qualifies the behavior of the sp:TransportBinding policy assertion. The sp:TransportToken is a nested policy assertion of the sp:TransportBinding policy assertion. The sp:TransportToken assertion requires the use of a specific transport token and further qualifies the behavior of the sp:TransportBinding policy assertion (which already requires the use of transport-level security for protecting messages).

Transport Security Policy Assertion

 

<sp:TransportBinding>

  <Policy>

    <sp:TransportToken>

      <Policy>

        <sp:HttpsToken RequireClientCertificate=”false” />

      </Policy>

    </sp:TransportToken>

    <sp:AlgorithmSuite>

      <Policy>

        <sp:Basic256Rsa15 />

      </Policy>

    </sp:AlgorithmSuite>

    …

  </Policy>

</sp:TransportBinding>

The sp:AlgorithmSuite is a nested policy assertion of the sp:TransportBinding policy assertion. The sp:AlgorithmSuite assertion requires the use of the algorithm suite identified by its nested policy assertion (sp:Basic256Rsa15 in the example above) and further qualifies the behavior of the sp:TransportBinding policy assertion.

Setting aside the details of using transport-level security, Web service developers, like Tony, can use a policy-aware client that recognizes this policy assertion and engages transport-level security and its dependent behaviors automatically. That is, the complexity of security usage is absorbed by a policy-aware client and hidden from these Web service developers.

2.8 Referencing Policy Expressions

Contoso has numerous Web service offerings that provide different kinds of real-time quotes and book information on securities such as GetRealQuote, GetRealQuotes, and GetExtendedRealQuote. To accommodate the diversity of Contoso’s customers, Contoso supports multiple WSDL bindings for these Web services. Contoso provides consistent ways to interact with their services and wants to represent these capabilities and requirements consistently across all of their offerings without duplicating policy expressions multiple times. How? It is simple – a policy expression can be named and referenced for re-use.

A policy expression may be identified by a URI and referenced for re-use as a standalone policy or within another policy expression. There are two mechanisms to identify a policy expression: the wsu:Id and Name attributes. A PolicyReference element can be used to reference a policy expression identified using either of these mechanisms.

Common Policy Expression

 

<Policy wsu:Id=”common”>

  <mtom:OptimizedMimeSerialization wsp:Optional=”true”/>

  <wsap:UsingAddressing />

</Policy>

In the example above, the wsu:Id attribute is used to identify a policy expression. The value of the wsu:Id attribute is an XML ID. The relative URI for referencing this policy expression (within the same document) is #common. If the policy document URI is http://real.contoso.com/policy.xml then the absolute URI for referencing this policy expression is http://real.contoso.com/policy.xml#common. (The absolute URI is formed by combining the document URI, # and the value of the wsu:Id attribute.)

For re-use, a PolicyReference element can be used to reference a policy expression as a standalone policy or within another policy expression. The example below is a policy expression that re-uses the common policy expression above.

PolicyReference to Common Policy Expression

 

<PolicyReference URI=”#common”/>

For referencing a policy expression within the same XML document, Contoso uses the wsu:Id attribute for identifying a policy expression and a URI to this ID value for referencing this policy expression using a PolicyReference element.

The example below is a policy expression that re-uses the common policy expression within another policy expression. This policy expression requires the use of addressing, one of transport- or message-level security for protecting messages and allows the use of optimization.

Secure Policy Expression

 

<Policy wsu:Id=”secure”>

  <All>

    <PolicyReference URI=”#common”/>

    <ExactlyOne>

      <sp:TransportBinding>…</sp:TransportBinding>

      <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

    </ExactlyOne>

  </All>

</Policy>

The Name attribute is an alternate mechanism to identify a policy expression. The value of the Name attribute is an absolute URI and is independent of the location of the XML document where the identified policy expression resides in. As such, referencing a policy expression using the Name attribute relies on additional out of band information. In the example below, the Name attribute identifies the policy expression. The URI of this policy expression is http://real.contoso.com/policy/common.

Common Policy Expression

 

<Policy>

  <mtom:OptimizedMimeSerialization wsp:Optional=”true”/>

  <wsap:UsingAddressing />

</Policy>

The example below is a policy expression that re-uses the common policy expression above.

PolicyReference to Common Policy Expression

 

<PolicyReference URI=”http://real.contoso.com/policy/common”/>

2.9 Attaching Policy Expressions to WSDL

A majority of Contoso’s customers use WSDL for building their client applications. Contoso leverages this usage by attaching policy expressions to the WSDL binding descriptions.

In the example below, the SecureBinding WSDL binding description defines a binding for an interface that provides real-time quotes and book information on securities. (The prefixes wsdl and tns are used here to denote the Web Services Description language XML namespace and target namespace of this WSDL document.) To require the use of security for these offerings, Contoso attaches the secure policy expression in the previous section to this binding description. The WSDL binding element is a common policy attachment point. The secure policy expression attached to the SecureBinding WSDL binding description applies to any message exchange associated with any port that supports this binding description. This includes all the message exchanges described by operations in the RealTimeDataInterface.

Secure Policy Expression Attached to WSDL Binding

 

<wsdl:binding >

  <PolicyReference URI=”#secure” />

  <wsdl:operation >…</wsdl:operation>

  …

</wsdl:binding>

 

In addition to providing real-time quotes and book information on securities, Contoso provides other kinds of data through Web services such as quotes delayed by 20 minutes and security symbols through Web services (for example GetDelayedQuote, GetDelayedQuotes, GetSymbol, and GetSymbols). Contoso does not require the use of security for these services, but requires the use of addressing and allows the use of optimization.

Open Policy Expression Attached to WSDL Binding

 

<wsdl:binding >

  <PolicyReference URI=”#common” />

  <wsdl:operation >…</wsdl:operation>

  …

</wsdl:binding>

In the example above, the OpenBinding WSDL binding description defines a binding for an interface that provides other kinds of data such as quotes delayed by 20 minutes and security symbols. To require the use of addressing and allow the use of optimization, Contoso attaches the common policy expression in the previous section to this binding description. As we have seen in the SecureBinding case, the common policy expression attached to the OpenBinding WSDL binding description applies to any message exchange associated with any port that supports this binding description. This includes all the message exchanges described by operations in the DelayedDataInterface.

As mentioned earlier, providers have the option to convey requirements, such as the use of addressing or security, through word-of-mouth and documentation – as they always have. The absence of policy expressions in a WSDL document does not indicate anything about the capabilities and requirements of a service. The service may have capabilities and requirements that can be expressed as policy expressions, such as the use of addressing, security and optimization. Or, the service may not have such capabilities and requirements. A policy aware client should not conclude anything (other than ‘no claims’) about the absence of policy expressions.

Service providers, like Contoso, can preserve and leverage their investments in WSDL and represent the capabilities and requirements of a Web service as policies. A WSDL document may specify varying behaviors across Web service endpoints. Web service developers, like Tony, can use a policy-aware client that recognizes these policy expressions in WSDL documents and engages behaviors automatically for each of these endpoints. Any complexity of varying behaviors across Web service endpoints is absorbed by a policy-aware client or tool and hidden from these Web service developers.

2.10 Policy Automates Web Services Interaction

As you have seen, Web Services Policy is a simple language that has four elements – Policy, All, ExactlyOne and PolicyReference – and one attribute – wsp:Optional. In practice, service providers, like Contoso, use policy expressions to represent combinations of capabilities and requirements. Web service developers, like Tony, use policy-aware clients that understand policy expressions and engage the behaviors represented by providers automatically. A sizable amount of complexity is absorbed by policy-aware clients (or tools) and is invisible to these Web service developers.

Web Services Policy extends the foundation on which to build interoperable Web services, hides complexity from developers and automates Web service interactions.

3. Advanced Concepts I: Policy Expression

In Section 2, we covered the basics of Web Services Policy language. This is the first advanced section that provides more in-depth materials for Web Services Policy implementers and assertion authors. This section covers the following topics:

  • What is a policy expression?
  • What is the normal form of a policy expression and how to normalize policy expressions?
  • What is the policy data model?
  • How to select a compatible policy alternative?
  • How to attach policy expressions to WSDL constructs?
  • How to combine policies?
  • What are the extensibility points?

3.1 Policy Expression

A policy expression is the XML representation and interoperable form of a Web Services Policy. A policy expression consists of a Policy wrapper element and a variety of child and descendent elements. Child and descendent elements from the policy language are Policy, All, ExactlyOne and PolicyReference. Other child elements of Policy, All and ExactlyOne are policy assertions. (The Policy element plays two roles: wrapper element and operator.) Policy assertions can contain a nested policy expression. Policy assertions can also be marked optional to represent behaviors that may be engaged (capabilities) for an interaction. The optional marker is the wsp:Optional attribute which is placed on a policy assertion element.

Let us take a closer look at Contoso’s policy expression (see below) from the previous section.

Contoso’s Secure Policy Expression

 

<Policy>

  <All>

    <mtom:OptimizedMimeSerialization wsp:Optional=”true”/>

    <wsap:UsingAddressing />

    <ExactlyOne>

      <sp:TransportBinding>…</sp:TransportBinding>

      <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

    </ExactlyOne>

  </All>

</Policy>

The Policy element is the wrapper element. The All and ExactlyOne elements are the policy operators. All other child elements of the All and ExactlyOne elements are policy assertions from domains such as messaging, addressing, security, reliability and transactions.

3.2 Normal Form for Policy Expressions

Web Services Policy language defines two forms of policy expressions: compact and normal form. Up to this point, we have used the compact form. The compact form is less verbose than the normal form. The compact form is useful for authoring policy expressions. The normal form is an intuitive representation of the policy data model. We will look into the policy data model in the next section.

The normal form uses a subset of constructs used in the compact form and follows a simple outline for its XML representation:

Normal Form for Policy Expressions

 

<Policy>

  <ExactlyOne>

    <All>

      <x:AssertionA>…</x:AssertionA>

      <y:AssertionB>…</y:AssertionB>

      …

    </All>

    <All>

      <x:AssertionA>…</x:AssertionA>

      <z:AssertionC>…</z:AssertionC>

      …

    </All>

    …

  </ExactlyOne>

<Policy/>

The normal form consists of a Policy wrapper element and has one child ExactlyOne element. This ExactlyOne element has zero or more All child elements. Each of these All elements has zero or more policy assertions. The PolicyReference element and wsp:Optional attribute are not used in the normal form. And, a nested policy expression in the normal form has at most one policy alternative.

The normal form represents a policy as a collection of policy alternatives and a policy alternative as a collection of policy assertions in a straight-forward manner.

The example below is a policy expression in the normal form. This expression contains two policy alternatives: one that requires the use of transport-level security and the other that requires the use of message-level security for protecting messages.

Transport- or Message-Level Security Policy Expression in Normal Form

 

<Policy>

  <ExactlyOne>

    <All>

      <sp:TransportBinding>…</sp:TransportBinding>

    </All>

    <All>

      <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

    </All>

  </ExactlyOne>

</Policy>

 

A policy expression in the compact form can be converted to the normal form. Web Services Policy language describes the algorithm for this conversion.

Let us re-consider Contoso’s policy expression (see the example below). Contoso requires the use of addressing and either transport- or message-level security and allows the use of optimization. This policy expression is in the compact form and has four policy alternatives for requestors:

(a) Requires the use of addressing and transport-level security
(b) Requires the use of addressing and message-level security
(c) Requires the use of optimization, addressing, and transport-level security and
(d) Requires the use of optimization, addressing, and message-level security.

Contoso’s Secure Policy Expression in Compact Form

 

<Policy wsu:Id=”secure”>

  <All>

    <PolicyReference URI=”#common”/>

    <ExactlyOne>

      <sp:TransportBinding>…</sp:TransportBinding>

      <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

    </ExactlyOne>

  </All>

</Policy>

 

<Policy wsu:Id=”common”>

  <mtom:OptimizedMimeSerialization wsp:Optional=”true”/>

  <wsap:UsingAddressing />

</Policy>

Let us look at the normal form for this policy expression. The example below is Contoso’s policy expression in the normal form. As you can see, the compact form is less verbose than the normal form. The normal form represents a policy as a collection of policy alternatives. Each of the All operators is a policy alternative. There are four policy alternatives in the normal form. These alternatives map to bullets (a) through (d) above.

Contoso’s Policy Expression in Normal Form

 

<Policy>

  <ExactlyOne>

    <All> <!– – - – - – - – - – - – - – Policy Alternative (a) –>

       <wsap:UsingAddressing />

       <sp:TransportBinding>…</sp:TransportBinding>

    </All>

    <All> <!– – - – - – - – - – - – - – Policy Alternative (b) –>

      <wsap:UsingAddressing />

      <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

    </All>

    <All> <!– – - – - – - – - – - – - – Policy Alternative (c) –>

       <mtom:OptimizedMimeSerialization />

       <wsap:UsingAddressing />

       <sp:TransportBinding>…</sp:TransportBinding>

    </All>

    <All> <!– – - – - – - – - – - – - – Policy Alternative (d) –>

       <mtom:OptimizedMimeSerialization />

       <wsap:UsingAddressing />

       <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

    </All>

  </ExactlyOne>

</Policy>

The wsp:Optional attribute, nested policy expression and PolicyReference element are converted to their corresponding normal form. The wsp:Optional attribute converts to two alternatives, one with and the other without the assertion. A policy alternative containing an assertion with a nested policy expression that has multiple policy alternatives converts to multiple policy alternatives where the assertion contains a nested policy expression that has at most one policy alternative.

The PolicyReference element is replaced with its referenced policy expression. Just as other service metadata languages, Web Services Policy does not mandate any specific policy retrieval mechanism. Any combination of any retrieval mechanisms in any order may be used for referencing policy expressions. Example retrieval mechanisms are:

  • Do nothing. A policy expression with the referenced URI is already known to be available in a local cache or chip (embedded systems).
  • Use the referenced URI and retrieve an existing policy expression from the containing XML document: a policy element with an XML ID.
  • Use the referenced URI and retrieve a policy expression from some policy repository (local or remote) or catalog. Policy tools may use any protocols (say Web Services Metadata Exchange) for such metadata retrieval. These protocols may require additional out of band information.
  • Attempt to resolve the referenced URI on the Web. This may resolve to a policy element or a resource that contains a policy element.

If the referenced policy expression is in the same XML document as the reference, then the policy expression should be identified using the wsu:Id (XML ID) attribute and referenced using a URI reference to this XML ID value.

3.3 Policy Data Model

In the previous section, we considered the normal form for policy expressions. As we discussed, the normal form represents a policy as a collection of policy alternatives. In this section, let us look at the policy data model.

Contoso uses a policy to convey the conditions for an interaction. Policy-aware clients, like the one used by Tony (as explained earlier in Section 2), view policy as an unordered collection of zero or more policy alternatives. A policy alternative is an unordered collection of zero or more policy assertions. A policy alternative represents a collection of behaviors or requirements or conditions for an interaction. In simple words, each policy alternative represents a set of conditions for an interaction. The diagram below describes the policy data model.

A policy-aware client uses a policy to determine whether one of these policy alternatives (i.e. the conditions for an interaction) can be met in order to interact with the associated Web Service. Such clients may choose any of these policy alternatives and must choose exactly one of them for a successful Web service interaction. Clients may choose a different policy alternative for a subsequent interaction. It is important to understand that a policy is a useful piece of metadata in machine-readable form that enables tooling, yet is not required for a successful Web service interaction. Why? Web service developers, like Tony, could use the documentation, talk to the service providers, or look at message traces to infer these conditions for an interaction. Developers continue to have these options, as they always had.

As we discussed, a policy assertion identifies a domain specific behavior or requirement or condition. A policy assertion has a QName that identifies its behavior or requirement or condition. In the XML representation, the QName of the assertion element is the QName of the policy assertion. A policy assertion may contain assertion parameters and a nested policy.

The assertion parameters are the opaque payload of an assertion. Parameters carry additional useful pieces of information necessary for engaging the behavior described by an assertion. In the XML representation, the child elements and attributes of an assertion are the assertion parameters.

We considered nested policy expressions in the context of a security usage scenario. Let us look at its shape in the policy data model. In the normal form, a nested policy is a policy that has at most one policy alternative and is owned by its parent policy assertion. The policy alternative in a nested policy represents a collection of dependent behaviors or requirements or conditions that qualify the behavior of its parent policy assertion.

A policy-aware client supports a policy assertion if the client engages the behavior or requirement or condition indicated by the assertion. A policy-aware client supports a policy alternative if the client engages the behaviors represented by all the assertions in the alternative. A policy-aware client supports a policy if the client engages the behaviors represented by at least one of the policy alternatives.

In the previous section, we saw how the normal form of a policy expression represents a policy as a collection of policy alternatives. By policy language design, the normal form of a policy expression directly maps to the policy data model:

  • Each child element of Policy/ExactlyOne/All maps to a policy assertion.
  • Each Policy/ExactlyOne/All element and policy assertions which correspond to its children map to a policy alternative.
  • The Policy/ExactlyOne element maps to a collection of policy alternatives.
  • The Policy wrapper element and policy alternatives which correspond to the Policy/ExactlyOne element map to a policy.

The diagram below describes this mapping from the normal form of a policy expression to the policy data model.

3.4 Compatible Policies

A provider, like Contoso, and a requestor, like Tony’s policy-aware client, may represent their capabilities and requirements for an interaction as policies and want to limit their message exchanges to mutually compatible policies. Web Services Policy defines an intersection mechanism for selecting compatible policy alternatives when there are two or more policies.

The example below is a copy of Contoso’s policy expression (from Section 3.2). As we saw before, Contoso offers four policy alternatives. Of them, one of the policy alternatives requires the use of addressing and transport-level security.

Contoso’s Policy Expression

 

<Policy>

  <ExactlyOne>

    <All> <!– – - – - – - – - -   Contoso’s Policy Alternative (a) –>

       <!– – - – - – - – - – - – - – - – - – Policy Assertion (c1) –>

       <wsap:UsingAddressing />

       <!– – - – - – - – - – - – - – - – - – Policy Assertion (c2) –>

       <sp:TransportBinding>…</sp:TransportBinding>

    </All>

    …

  </ExactlyOne>

</Policy>

Tony’s organization requires the use of addressing and transport-level security for any interaction with Contoso’s Web services. Tony represents these behaviors using a policy expression illustrated in the example below in normal form. This policy expression contains one policy alternative that requires the use of addressing and transport-level security.

Tony’s Policy Expression in Normal Form

 

<Policy>

  <ExactlyOne>

    <All> <!– – - – - – - – - – - – - -  Tony’s Policy Alternative –>

       <!– – - – - – - – - – - – - – - – - – Policy Assertion (t1) –>

      <sp:TransportBinding>…</sp:TransportBinding>

       <!– – - – - – - – - – - – - – - – - – Policy Assertion (t2) –>

      <wsap:UsingAddressing />

    </All>

  </ExactlyOne>

</Policy>

Tony lets his policy-aware client select a compatible policy alternative in Contoso’s policy. How does this client select a compatible policy alternative? It is simple – it uses the policy intersection. That is, Tony’s policy-aware client uses these two policy expressions (Tony’s and Contoso’s) and the policy intersection to select a compatible policy alternative for this interaction. Let us look at the details of policy intersection.

For two policy assertions to be compatible they must have the same QName. And, if either assertion has a nested policy, both assertions must have a nested policy and the nested policies must be compatible. For example, policy assertions (c2) and (t1) have the same QName, sp:TransportBinding. For this discussion, let us assume that these two assertions have compatible nested policies. These two assertions are compatible because they have the same QName and their nested policies are compatible.

Two policy alternatives are compatible if each policy assertion in one alternative is compatible with a policy assertion in the other and vice-versa. For example, policy assertions (c1) and (c2) in Contoso’s policy alternative are compatible with policy assertions (t2) and (t1) in Tony’s policy alternative. Contoso’s policy alternative (a) and Tony’s policy alternative are compatible because assertions in these two alternatives are compatible.

Two policies are compatible if a policy alternative in one is compatible with a policy alternative in the other. For example, Contoso’s policy alternative (a) is compatible with Tony’s policy alternative. Contoso’s policy and Tony’s policy are compatible because one of Contoso’s policy alternative is compatible with Tony’s policy alternative.

For this interaction, Tony’s policy-aware client can use policy alternative (a) to satisfy Contoso’s conditions or requirements.

Similarly, policy intersection can be used to check if providers expose endpoints that conform to a standard policy. For example, a major retailer might require all their supplier endpoints to be compatible with an agreed upon policy.

3.5 Attaching Policy Expressions to WSDL

In Section 2, we looked into how Contoso attached their policy expressions to the WSDL binding element. In addition to the WSDL binding element, a policy expression can be attached to other WSDL elements such as service, port, operation and message. These elements are the WSDL policy attachment points in a WSDL document.

The WSDL attachment points are partitioned (as illustrated below) into four policy subjects: message, operation, endpoint and service. When attached, capabilities and requirements represented by a policy expression apply to a message exchange or message associated with (or described by) a policy subject.

The WSDL service element represents the service policy subject. Policy expressions associated with a service policy subject apply to any message exchange using any of the endpoints offered by that service.

The WSDL port, binding and portType elements collectively represent the endpoint policy subject. Policy expressions associated with an endpoint policy subject apply to any message exchange made using that endpoint.

The WSDL binding/operation and portType/operation elements collectively represent the operation policy subject. Policy expressions associated with an operation policy subject apply to the message exchange defined by that operation.

The WSDL binding/operation/input, portType/operation/input, and message element collectively represent the message policy subject for the input message. The WSDL binding/operation/output, portType/operation/output, and message element collectively represent the message policy subject for the output message. The WSDL binding/operation/fault, portType/operation/fault, and message element collectively represent the message policy subject for the fault message. Policy expressions associated with a message policy subject apply only to that message.

In the example below, the policy expression is attached to an endpoint policy subject.

Contoso’s Policy Expression Attached to WSDL binding Element

 

<wsdl:binding >

  <PolicyReference URI=”#secure” />

  <wsdl:operation >…</wsdl:operation>

  …

</wsdl:binding>

If multiple policy expressions are attached to WSDL elements that collectively represent a policy subject then the effective policy of these policy expressions applies. The effective policy is the combination of the policy expressions that are attached to the same policy subject. For example, the effective policy of an endpoint policy subject is the combination of policy expressions attached to a WSDL port element, policy expressions attached to the binding element referenced by this port, and policy expressions attached to the portType element that is supported by this port. Let us consider how to combine policy expressions in the next section.

Most of the policy assertions are designated for the endpoint, operation, or message policy subject. The commonly used WSDL attachment points are:

Policy Subject Commonly used attachment point (s)
Endpoint binding element
Operation binding/operation element
Message binding/operation/input and
binding/operation/output elements

3.6 Combine Policies

Multiple policy expressions may be attached to WSDL constructs. Let us consider how Contoso could have used multiple policy expressions in a WSDL document. In the example below, there are two policy expressions #common2 and #secure2 attached to the SecureBinding WSDL binding and RealTimeDataPort WSDL port descriptions.

Multiple Policy Expressions Attached to Endpoint Policy Subject

<Policy wsu:Id=”common2″>

  <mtom:OptimizedMimeSerialization wsp:Optional=”true”/>

  <wsap:UsingAddressing />

</Policy>

<Policy wsu:Id=”secure2″>

  <ExactlyOne>

    <sp:TransportBinding>…</sp:TransportBinding>

    <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

  </ExactlyOne>

</Policy>

 

<wsdl:binding >

  <PolicyReference URI=”#secure2″ />

  <wsdl:operation >…</wsdl:operation>

  …

</wsdl:binding>

 

<wsdl:service>

  <wsdl:port binding=”tns:SecureBinding”>

    <PolicyReference URI=”#common2″ />

    …

  </wsdl:port>

</wsdl:service>

As we discussed before, the WSDL port, binding and portType elements collectively represent the endpoint policy subject. In the example above, the #common2 and #secure2 policy expressions attached to the SecureBinding WSDL binding and RealTimeDataPort WSDL port descriptions collectively apply to any message exchange associated with the RealTimeDataPort WSDL port.

As in the example above, multiple policy expressions may be attached to Web service constructs that collectively represent a single policy subject. When there are multiple policy expressions attached to the same policy subject then the effective policy or combination of these policy expressions apply to the associated policy subject.

The effective policy is the combination of two or more policy expressions attached to the same policy subject. The combination of two policy expressions, also known as the merged policy expression, is a new policy expression that combines these two policy expressions using the All policy operator.

The policy expression below is the combination of the two policy expressions attached to the SecureBinding WSDL binding and RealTimeDataPort WSDL port descriptions. The #common2 policy expression has two policy alternatives. The #secure2 policy expression has two policy alternatives. The combination of these two policies is equivalent to Contoso’s secure policy in Section 2 and has four policy alternatives. In other words, the combination of two policies is the cross product of alternatives in these two policies.

Effective Policy of the Endpoint Policy Subject in the Previous Example

<Policy>

  <All>

    <Policy>

      <mtom:OptimizedMimeSerialization wsp:Optional=”true”/>

      <wsap:UsingAddressing />

    </Policy>

    <Policy>

      <ExactlyOne>

        <sp:TransportBinding>…</sp:TransportBinding>

        <sp:AsymmetricBinding>…</sp:AsymmetricBinding >

      </ExactlyOne>

    </Policy>

  </All>

</Policy>

Of course, the above policy expression can be normalized. There are four policy alternatives in the normal form. As we have seen in the policy data model, a policy is an unordered collection of policy alternatives. That is, the order of policy alternatives is insignificant. Therefore, the order of combining these policy expressions is insignificant.

3.7 Extensibility and Versioning

Web Services Policy language is an extensible language by design. The Policy, ExactlyOne, All and PolicyReference elements are extensible. The Policy, ExactlyOne and All elements allow child element and attribute extensibility. The PolicyReference element allows attribute extensibility. Extensions must not use the policy language XML namespace name. A consuming processor processes known attributes and elements, ignores unknown attributes and treats unknown elements as policy assertions.

Web Services Policy language enables simple versioning practices that allow requestors to continue the use of any older policy alternatives in a backward compatible manner. This allows service providers, like Contoso, to deploy new behaviors using additional policy assertions without breaking compatibility with clients that rely on any older policy alternatives.

The example below represents a Contoso version 1 policy expression. This expression requires the use of addressing and transport-level security for protecting messages.

Contoso’s Version 1 Policy Expression

 

<Policy>

  <ExactlyOne>

    <All>

      <wsap:UsingAddressing />

      <sp:TransportBinding>…</sp:TransportBinding>

    </All>

  </ExactlyOne>

</Policy>

Over time, Contoso adds support for advanced behaviors: requiring the use of addressing and message-level security for protecting messages. They added this advanced support without breaking compatibility with requestors that rely on addressing and transport-level security. The example below is Contoso’s version 2 policy expression. In this version, Contoso’s adds a new policy alternative that requires the use of addressing and message-level security. The clients that rely on addressing and transport-level security may continue to interact with Contoso’s using the old policy alternative. Of course, these clients have the option to migrate from using old policy alternatives to new policy alternatives.

Contoso’s Version 2 Policy Expression

<Policy>

  <ExactlyOne>

    <All>

      <wsap:UsingAddressing />

      <sp:TransportBinding>…</sp:TransportBinding>

    </All>

    <All> <!– – - – - – - – - – - – - – - – NEW Policy Alternative –>

      <wsap:UsingAddressing />

      <sp:AsymmetricBinding>…</sp: AsymmetricBinding >

    </All>

  </ExactlyOne>

</Policy>

When Contoso added support for advanced behaviors, they spent time to plan for the continued support for existing clients, the smooth migration from using current to advanced behaviors, and the switch to use only the advanced behaviors in the near future (i.e. sun-setting current behaviors). In this versioning scenario, policy can be used to represent current and advanced behaviors in a non-disruptive manner: no immediate changes to existing clients are required and these clients can smoothly migrate to new functionality when they choose to. This level of versioning support in policy enables the same class of versioning best practices built into WSDL constructs such as service, port and binding.

Let us look at tooling for unknown policy assertions. As service providers, like Contoso, incrementally deploy advanced behaviors, some requestors may not recognize these new policy assertions. As discussed before, these requestors may continue to interact using old policy alternatives. New policy assertions will emerge to represent new behaviors and slowly become part of everyday interoperable interaction between requestors and providers. Today, most tools use a practical tolerant strategy to process new or unrecognized policy assertions. These tools consume such unrecognized assertions and designate these for user intervention. As you would recognize, there is nothing new in this practice. This is similar to how a proxy generator that generates code from WSDL creates code for all the known WSDL constructs and allows Web service developers to fill in code for custom or unknown constructs in the WSDL.

4. Advanced Concepts II: Policy Assertion Design

In the previous section, we covered in-depth materials for Web Services Policy implementers. This is the second advanced section that walks through the dimensions of a policy assertion for assertion authors. This section covers the following topics:

  • What is the role of policy assertions?
  • What are the parts of a policy assertion?
  • When to design policy assertions?
  • What are the guidelines for designing policy assertions?
  • What are the minimum requirements for describing policy assertions?

4.1 Role of Policy Assertions

As you have seen, Web Services Policy is a simple language that has four elements -Policy, All, ExactlyOne and PolicyReference – and one attribute – wsp:Optional. Policy is a flexible language to represent consistent combinations of behaviors using policy operators: Policy, All and ExactlyOne. Policy is an expressive language and capable of representing behaviors from a variety of domains. Let us look for the key parts that unlock this potential.

Service providers combine behaviors for an interaction from domains such as messaging, security, reliability and transactions. To enable clients to engage these behaviors, services require some way to advertise these behaviors. Providers require machine readable metadata pieces that identify these behaviors. A policy assertion is a machine-readable metadata piece that requires the use of a behavior identified by the assertion. Web service developers can use policy-aware clients that recognize these assertions and engage their corresponding behaviors automatically.

Policy assertions are the key parts and play a central role to unlock the potential offered by the Web Services Policy language. Assertions are defined by product designers, protocol authors, protocol implementers and Web service developers.

Policy assertion authors identify behaviors required for Web services interactions and represent these behaviors as policy assertions. By designing policy assertions, assertion authors make a significant contribution to automate Web services interactions and enable advanced behaviors.

4.2 Parts of a Policy Assertion

As we discussed, a policy assertion identifies a domain specific behavior or requirement or condition. A policy assertion has a QName that identifies its behavior or requirement or condition. A policy assertion may contain assertion parameters and a nested policy.

Let us look at the anatomy of a policy assertion from the security domain. The policy expression in the diagram below uses the sp:IssuedToken policy assertion. This assertion illustrates the use of assertion parameters and nested policy.

The sp:IssuedToken element is a policy assertion that identifies the use of a security token – such as SAML token – issued by a third party for protecting messages. A policy assertion is an XML element. The QName of this element represents the behavior identified by this policy assertion.

The sp:IssuedToken policy assertion has three parameters: @sp:IncludeToken, sp:Issuer, and sp:RequestSecurityTokenTemplate.

The sp:IncludeToken attribute is a parameter that contains information on whether a security token should be included in messages or an external reference to the key of this security token should be used. The sp:Issuer parameter is an endpoint reference to a security token issuer. The sp:RequestSecurityTokenTemplate parameter contains the necessary information to request a security token from the specified issuer. Parameters are the opaque payload of a Policy Assertion, carry useful information for engaging the behavior described by an assertion and are preserved through policy processing such as normalize, merge and intersection. Requestors may use policy intersection to select a compatible policy alternative for an interaction. Assertion parameters do not affect the outcome of policy intersection.

For the sp:Issuer policy assertion parameter, the assertion author uses the natural XML structural relationships (the child elements and attributes) and encodes the relationship between an assertion and its parameters in a machine readable form. Assertion parameters may be represented as child XML elements or attributes of an assertion. The policy language allows assertion authors to strongly tie the relationship between an assertion and its parameters using the natural XML structural relationships.

The sp:IssuedToken policy assertion has a nested policy expression. The sp:RequireInternalReference element is a nested policy assertion of the sp:IssuedToken policy assertion. The sp:RequireInternalReference assertion requires the use of an internal reference for referencing the issued token. A nested policy assertion further qualifies a dependent behavior of its parent policy assertion. As mentioned earlier, requestors may use policy intersection to select a compatible policy alternative for an interaction. Nested policy assertions affect the outcome of policy intersection.

The sp:IssuedToken security policy assertion identifies a visible domain specific behavior: the use of a security token – such as SAML token – issued by a third party for protecting messages. This behavior is relevant to a Web service interaction. For the sake of discussion, let us assume that Contoso requires the use of a SAML token issued by a third party. Service providers, like Contoso, must convey this usage and all the necessary information to obtain this security token for Web service developers. This is a key piece of metadata for a successful interaction with Contoso’s Web services.

4.3 When to Design Policy Assertions?

As we illustrated in the previous section, requiring the use of a security token issued by a third party is represented as a policy assertion. In simple words, a policy assertion identifies a domain specific behavior:

  • That is a requirement
  • That is relevant to an interoperable Web service interaction
  • That is relevant to an interaction that involves two or more Web service participants
  • That applies to its associated policy subject such as service, endpoint, operation and message.

Given that interoperability and automation are the motivations, policy assertions that represent opt-in, shared and visible behaviors are useful pieces of metadata. Such assertions enable tooling and improve interoperability. The key to understanding when to design policy assertions is to have clarity on the characteristics of a behavior represented by a useful policy assertion: opt-in, shared and visible.

Opt-in behavior

An opt-in behavior refers to a requirement that providers and requestors must deliberately choose to engage for a successful web service interaction. Examples of such behaviors are the use of optimization, message-level security, reliable messaging and atomic transaction. Policy assertions are not necessary to interoperate on widespread assumed behaviors. An example of an assumed behavior is the use of UTF-8 or UTF-16 text encoding for XML messages.

Shared behavior

A shared behavior refers to a requirement that is relevant to an interoperable Web service interaction and involves two or more participants. If an assertion only describes one participant’s behavior (non-shared behavior) then the assertion is not relevant to an interoperable interaction. Non-shared behaviors do not add any value for tooling or interoperability. An example of a non-shared behavior is the use of logging or auditing by the provider.

Requestors may use the policy intersection to select a compatible policy alternative for a Web service interaction. If an assertion only describes one participant’s behavior then this assertion will not be present in the other participants’ policy and the policy intersection will unnecessarily produce false negatives.

Visible behavior

A visible behavior refers to a requirement that manifests on the wire. Web services provide interoperable machine-to-machine interaction among disparate systems. Web service interoperability is the capability of disparate systems to exchange data using common data formats and protocols such as messaging, security, reliability and transaction. Such data formats and protocols manifest on the wire. Providers and requestors only rely on these wire messages that conform to such formats and protocols for interoperability. If an assertion describes a behavior that does not manifest on the wire then the assertion is not relevant to an interoperable interaction.

For example, say an assertion describes the privacy notice information of a provider and there is an associated regulatory safeguard in place on the provider’s side. Such assertions may represent business or regulatory level metadata but do not add any value to interoperability.

If an assertion has no wire- or message-level visible behavior, then the interacting participants may require some sort of additional non-repudiation mechanism to indicate compliance with the assertion. Introducing an additional non-repudiation mechanism adds unnecessary complexity to processing a policy assertion.

4.4 Guidelines for Designing Assertions

The policy language allows assertion authors to invent their own XML dialects to represent policy assertions. The policy language builds on natural XML nesting and leverages XML Schema validation. The policy language relies only on the QName of the policy assertion XML element. Everything else is left for the policy assertion authors to design. The policy language offers plenty of options to assertion authors such as independent assertions, dependent assertions, nested policies and assertion parameters.

The description of a policy assertion should identify a single domain specific behavior in an objective manner and answer the following questions:

  • What is the behavior? (In the previous section, we discussed the characteristics of a behavior represented by a useful policy assertion.)
  • What are the assertion parameters?
  • Are there any dependent behaviors, and how are they represented?
  • What is the assertion’s QName and XML information set representation?
  • What is the policy subject of this behavior?
  • What are the attachment points?

As you would have expected, the policy assertion design is more than a technical design. Given that interoperability and automation are the motivations, policy assertion design is a business process to reach agreements with relevant stakeholders for interoperability and tooling. Setting aside the business aspects of the design, the rest of this section walks through a few tradeoffs or dimensions to consider and provides technical guidelines for designing policy assertions.

4.4.1 Optional Behaviors

A policy assertion identifies a domain specific behavior that is a requirement relevant to a Web Service interaction. Policy assertions can be marked optional using the wsp:Optional attribute marker to represent behaviors that may be engaged (capabilities) for an interaction. It is important to note that behavior (policy assertion) and optional representation (wsp:Optional attribute) are distinct ideas of the Web Services Policy language. Conflating these distinct ideas unnecessarily disrupts scenarios that depend on the policy intersection: if an assertion indicates an optional behavior and this assertion is not present in the other participants’ policy then the policy intersection will unnecessarily produce false negatives.

Best practice: use the wsp:Optional attribute to indicate optional behaviors.

4.4.2 Assertion vs. assertion parameter

Policy assertion parameters are the opaque payload of an assertion. Parameters carry additional useful information for engaging the behavior described by an assertion and are preserved through policy processing such as normalize, merge and policy intersection. Requestors may use policy intersection to select a compatible policy alternative for an interaction. Assertion parameters do not affect the outcome of policy intersection.

In the example below, sp:Body and sp:Header elements are the two assertion parameters of the sp:SignedParts policy assertion (this assertion requires the parts of a message to be protected). These two parameters identify the parts of a wire message that should be protected. These parameters carry additional useful information for engaging the behavior that is irrelevant to compatibility tests.

Policy Assertion with Assertion Parameters

<Policy>

  <sp:SignedParts>

    <sp:Body />

    <sp:Header />

  </sp:SignedParts>

  …

</Policy>

Best practice: represent useful (or additional) information necessary for engaging the behavior represented by a policy assertion as assertion parameters.

4.4.3 Leveraging Nested Policy

As we have seen before, a nested policy expression further qualifies the dependent behaviors of its parent policy assertion. When we consider nested policy there is always two or more policy assertions involved. The following design questions below can help you to determine when to use nested policy expressions:

Are these assertions designed for the same policy subject?
Do these assertions represent dependent behaviors?

If the answers are yes to both of these questions then leveraging nested policy expressions is a good idea. Keep in mind that a nested policy expression participates in the policy intersection algorithm. If a requestor uses policy intersection to select a compatible policy alternative then the assertions in a nested policy expression play a first class role in the outcome. There is one caveat to watch out for: policy assertions with deeply nested policy can greatly increase the complexity of a policy and should be avoided when they are not needed.

Best practice: represent dependent behaviors that apply to the same policy subject using nested policy assertions.

4.4.4 Minimal approach

How big should an assertion be? How many assertion parameters should the assertion enumerate? How many dependent behaviors should the assertion enumerate? It is always good to start with a simple working policy assertion that allows extensibility. As your design work progresses, you may add more parameters or nested policy assertions to meet your interoperability needs.

Best practice: start with a simple working assertion that allows extensibility.

4.4.5 QName and XML Information Set representation

As mentioned before, Web Services Policy language allows assertion authors to invent their own XML dialects to represent policy assertions. The policy language relies only on the policy assertion XML element QName. This QName is unique and identifies the behavior represented by a policy assertion. Assertion authors have the option to represent an assertion parameter as a child element (by leveraging natural XML nesting) or an attribute of an assertion. The general guidelines on when to use XML elements versus attributes apply.

The syntax of an assertion can be represented using an XML outline (plus an XML schema document). If the assertion has a nested policy expression then the assertion XML outline can enumerate the nested assertions that are allowed.

Best practice: use a unique QName to identify the behavior and provide an XML outline (plus an XML schema document) to specify the syntax of an assertion.

4.4.6 Policy subject and attachment points

A behavior identified by a policy assertion applies to the associated policy subject. If a policy assertion is to be used with WSDL, policy assertion authors must specify a WSDL policy subject. What is the policy subject of this behavior?

  • If the behavior applies to any message exchange using any of the endpoints offered by a service then the subject is the service policy subject.
  • If the behavior applies to any message exchange made using an endpoint then the subject is the endpoint policy subject.
  • If the behavior applies to any message exchange defined by an operation then the subject is the operation policy subject.
  • If the behavior applies to an input message then the subject is the message policy subject – similarly for output and fault message policy subjects.

For a given WSDL policy subject, there may be several attachment points. For example, there are three attachment points for the endpoint policy subject: the port, binding and portType element. Policy assertion authors should identify the relevant attachment point when defining a new assertion. To determine the relevant attachment points, authors should consider the scope of the attachment point. For example, an assertion should only be allowed in the portType element if the assertion reasonably applies to any endpoint that ever references that portType. Most of the known policy assertions are designed for the endpoint, operation or message policy subject. The commonly used attachment points for these policy subjects are outlined in Section 3.7 – Attaching Policy Expressions to WSDL.

The service policy subject is a collection of endpoint policy subjects. The endpoint policy subject is a collection of operation policy subjects and etc. As you can see, the WSDL policy subjects compose naturally. It is quite tempting to associate the identified behavior to a broader policy subject than to a fine granular policy subject. For instance, it is convenient to attach a supporting token assertion (defined by the Web Services Security Policy specification) to an endpoint policy subject instead of a message policy subject. For authoring convenience, an assertion author may allow the association of an assertion to multiple policy subjects. If an assertion is allowed to be associated with multiple policy subjects then the assertion author has the burden to describe the semantics of multiple instances of the same assertion attached to multiple policy subjects at the same time. The best practice is to choose the most granular policy subject that the behavior applies to.

Best practice: specify a policy subject, choose the most granular policy subject that the behavior applies to and specify a preferred attachment point.

4.4.7 Versioning behaviors

Over time, there may be multiple equivalent behaviors emerging in the Web Service interaction space. Examples of such multiple equivalent behaviors are WSS: SOAP Message Security 1.0 vs. 1.1 and WS-Addressing August 2004 version vs. WS-Addressing W3C Recommendation. These equivalent behaviors are mutually exclusive for an interaction. Such equivalent behaviors can be modeled as independent assertions. The policy expression in the example below requires the use of WSS: SOAP Message Security 1.0.

Message-level Security and WSS: SOAP Message Security 1.0

<Policy>

  <sp:Wss10>…</sp:Wss10>

</Policy>

The policy expression in the example below requires the use of WSS: SOAP Message Security 1.1. These are multiple equivalent behaviors and are represented using distinct policy assertions.

Message-level Security and WSS: SOAP Message Security 1.1

<Policy>

  <sp:Wss11>…</sp:Wss11>

</Policy>

 

Best practice: use independent assertions for modeling multiple equivalent behaviors.

4.5 Describing Policy Assertions

Thus far, we walked through the dimensions of a policy assertion and guidelines for authoring policy assertions. Let us look at what are the minimum requirements for describing policy assertions in specifications:

  1. Description must clearly and completely specify the syntax (plus an XML Schema document) and semantics of a policy assertion.
  2. If there is a nested policy expression, description must declare it and enumerate the nested policy assertions that are allowed.
  3. A policy alternative may contain multiple instances of the same policy assertion. Description must specify the semantics of parameters and nested policy (if any) when there are multiple instances of a policy assertion in the same policy alternative.
  4. If a policy assertion is to be used with WSDL, description must specify a WSDL policy subject – such as service, endpoint, operation and message.

5. Conclusion

Service providers use Web Services Policy to represent combinations of behaviors (capabilities and requirements). Web service developers use policy-aware clients that understand policy expressions and engage the behaviors represented by providers automatically. These behaviors may include security, reliability, transaction, message optimization, etc. Web Services Policy is a simple language, hides complexity from developers, automates Web service interactions, and enables secure, reliable and transacted Web Services.

Appendix A – Security Considerations

This appendix describes the security considerations that service providers, requestors, policy authors, policy assertion authors, and policy implementers need to consider when exposing, consuming and designing policy expressions, authoring policy assertions or implementing policy.

Information Disclosure Threats

A policy is used to represent the capabilities and requirements of a Web Service. Policies may include sensitive information. Malicious consumers may acquire sensitive information, fingerprint the service and infer service vulnerabilities. These threats can be mitigated by requiring authentication for sensitive information, by omitting sensitive information from the policy or by securing access to the policy. For securing access to policy metadata, policy providers can use mechanisms from other Web Services specifications such as WS-Security and WS-MetadataExchange.

Spoofing and Tampering Threats

If a policy expression is unsigned it could be easily tampered with or replaced. To prevent tampering or spoofing of policy, requestors should discard a policy unless it is signed by the provider and presented with sufficient credentials. Requestors should also check that the signer is actually authorized to express policies for the given policy subject.

Downgrade Threats

A policy may offer several alternatives that vary from weak to strong set of requirements. An adversary may interfere and remove all the alternatives except the weakest one (say no security requirements). Or, an adversary may interfere and discard this policy and insert a weaker policy previously issued by the same provider. Policy authors or providers can mitigate these threats by sun-setting older or weaker policy alternatives. Requestors can mitigate these threats by discarding policies unless they are signed by the provider.

Repudiation Threats

Malicious providers may include policy assertions in its policy whose behavior cannot be verified by examining the wire message from the provider to requestor. In general, requestors have no guarantee that a provider will behave as described in the provider’s policy expression. The provider may not and perform a malicious activity. For example, say the policy assertion is privacy notice information and the provider violates the semantics by disclosing private information. Requestors can mitigate this threat by discarding policy alternatives which include assertions whose behavior cannot be verified by examining the wire message from the provider to requestor. Assertion authors can mitigate this threat by not designing assertions whose behavior cannot be verified using wire messages.

Denial of Service Threats

Malicious providers may provide a policy expression with a large number of alternatives, a large number of assertions in alternatives, deeply nested policy expressions or chains of PolicyReference elements that expand exponentially (see the chained sample below; this is similar to the well-known DTD entity expansion attack). Policy implementers need to anticipate these rogue providers and use a configurable bound with defaults on number of policy alternatives, number of assertions in an alternative, depth of nested policy expressions, etc.

Chained Policy Reference Elements

<Policy wsu:Id=”p1″>

  <PolicyReference URI=”#p2″/ >

  <PolicyReference URI=”#p2″/>

</Policy>

<Policy wsu:Id=”p2″ >

  <PolicyReference URI=”#p3″/>

  <PolicyReference URI=”#p3″/>

</Policy>

<Policy wsu:Id=”p3″ >

  <PolicyReference URI=”#p4″/>

  <PolicyReference URI=”#p4″/>

</Policy>

<!– Policy/@wsu:Id p4 through p99 –>

<Policy wsu:Id=”p100″ >

  <PolicyReference URI=”#p101″/>

  <PolicyReference URI=”#p101″/>

</Policy>

 

<Policy wsu:Id=”p101″ >

  <mtom:OptimizedMimeSerialization />

</Policy>

Malicious providers may provide a policy expression that includes multiple PolicyReference elements that use a large number of different internet addresses. These may require the consumers to establish a large number of TCP connections. Policy implementers need to anticipate such rogue providers and use a configurable bound with defaults on number of PolicyReference elements per policy expression.

General XML Considerations

Implementers of Web services policy language should be careful to protect their software against general XML threats like deeply nested XML or XML that contains malicious content.

Appendix B – Acknowledgements

This document has been developed as a result of joint work with many individuals and teams, including: Paul Cotton, Colleen Evans, Kirill Gavrylyuk, Martin Gudgin, Ram Jeyaraman, Andrew Layman, Jonathan Marsh, Jeffrey Schlimmer, Jorgen Thelin, and Kyle Young.

Appendix C – XML Namespaces

Table 1 lists XML namespaces that are used in this document. The choice of any namespace prefix is arbitrary and not semantically significant.

Table 1: Prefixes and XML Namespaces used in this specification.

Prefix XML Namespace Specification(s)
  http://schemas.xmlsoap.org/ws/2004/09/policy [WS-Policy, WS-PolicyAttachment]
mtom http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization [WS-OptimizedSerializationPolicy]
soap http://www.w3.org/2003/05/soap-envelope [SOAP 1.2]
sp http://schemas.xmlsoap.org/ws/2005/07/securitypolicy [WS-SecurityPolicy]
wsa http://www.w3.org/2005/08/addressing/wsdl [WS-Addressing]
wsap http://www.w3.org/2006/05/addressing/wsdl [WS-AddressingPolicy]
wsdl http://schemas.xmlsoap.org/wsdl/ [WSDL 1.1]
wsp http://schemas.xmlsoap.org/ws/2004/09/policy [WS-Policy, WS-PolicyAttachment]
wss http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd [WS-Security 2004]
wst http://schemas.xmlsoap.org/ws/2005/02/trust [WS-Trust]
wsu http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd [WS-Security 2004]

Appendix D – References

[MTOM]

M. Gudgin, et al, “SOAP Message Transmission Optimization,” January 2005. (See http://www.w3.org/TR/2005/REC-soap12-mtom-20050125/.)

[SOAP 1.1]

D. Box, et al, “Simple Object Access Protocol (SOAP) 1.1,” May 2000. (See http://www.w3.org/TR/2000/NOTE-SOAP-20000508.)

[SOAP 1.2]

M. Gudgin, et al, “SOAP Version 1.2 Part 1: Messaging Framework,” June 2003. (See http://www.w3.org/TR/2003/REC-soap12-part1-20030624/.)

[XOP]

M. Gudgin, et al, “XML-binary Optimized Packaging,” January 2005. (See http://www.w3.org/TR/2005/REC-xop10-20050125/.)

[WS-Addressing]

M. Gudgin, et al, “Web Services Addressing 1.0 – Core,” May 2006. (See http://www.w3.org/TR/2006/REC-ws-addr-core-20060509/.)

[WS-AddressingPolicy]

M. Gudgin, et al, “Web Services Addressing 1.0 – WSDL Binding,” May 2006. (See http://www.w3.org/TR/2006/CR-ws-addr-wsdl-20060529/. The latest version of this specification is available at http://www.w3.org/TR/ws-addr-wsdl/.)

[WS-MetadataExchange]

K. Ballinger, et al, “Web Services Metadata Exchange (WS-Metadata Exchange),” September 2004. (See http://schemas.xmlsoap.org/ws/2004/09/mex/.)

[WSDL 1.1]

E. Christensen, et al, “Web Services Description Language (WSDL) 1.1,” March 2001. (See http://www.w3.org/TR/2001/NOTE-wsdl-20010315.)

[WS-Policy]

S. Bajaj, et al, “Web Services Policy Framework (WS-Policy),” March 2006. (See http://schemas.xmlsoap.org/ws/2004/09/policy.)

[WS-PolicyAttachment]

S. Bajaj, et al, “Web Services Policy Attachment (WS-PolicyAttachment),” March 2006. (See http://schemas.xmlsoap.org/ws/2004/09/policy.)

[WS-Security 2004]

A. Nadalin, et al, “Web Services Security: SOAP Message Security 1.0 (WS-Security 2004),” March 2004. (See http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0.pdf.)

[WS-SecurityPolicy]

G. Della-Libera, et al, “Web Services Security Policy Language (WS-SecurityPolicy),” July 2005. (See http://schemas.xmlsoap.org/ws/2005/07/securitypolicy.)

[WS-Trust]

S.Anderson, et al, “Web Services Trust Language (WS-Trust),” February 2005. (See http://schemas.xmlsoap.org/ws/2005/02/trust.)

Choosing the Most Specific Method – Tricky Method Overloading

Let’s start with looking at a code-segment and try to think of the output/error, it would produce when compiled/executed and subsequently we’ll discuss the behavior of code.


public class NullTest {

   public static void method(Object obj){
     System.out.println("method with param type - Object");
   }

   public static void method(String obj){
     System.out.println("method with param type - String");
   }

   public static void main(String [] args){
     method(null);
   }
}

So, what do you expect as the output here? Before thinking about the output, do you really expect the code to compile successfully? Well… yeah, the code will compile and run fine as opposed to anyone who might have sensed an ambiguity here – we’ll see the reason soon.

Since the methods are overloaded, the resolution will be done at compile-time only. Which method do you see being bind here – the one with parameter type ‘Object’ or the one with parameter type ‘String’ and why? Of course, the compiler can’t bind two methods with one call, so on what basis would it pick the most suitable? Which method would be picked, is evident from the output given below:-


method with param type - String


Any guesses for why a special treatment is being given to 'String' here? Well... it's not actually for 'String' class specifically, but any sub-class would get a preference over the super class in such a situation. But, why? Because JLS (Section: 15.12.2.5) allows this. It clearly says:

"If more than one member method is both accessible and applicable to a method invocation, it is necessary to choose one to provide the descriptor for the run-time method dispatch. The Java programming language uses the rule that the most specific method is chosen."

As you easily deduce that the compiler should be able to pick 'the most specific', failing which it will throw a compile-time error. Let's understand it with the below code-segment which doesn't compile because the compiler can't pick 'the most specific' here.


public class NullTest {

   public static void method(Object obj){
     System.out.println("method with param type - Object");
   }

   public static void method(String str){
     System.out.println("method with param type - String");
   }

   public static void method(StringBuffer strBuf){
     System.out.println("method with param type - StringBuffer");
   }

   public static void main(String [] args){
     method(null); //... compile-time error!
   }
}

Why is the compiler not able to pick ‘the most specific’ here – because both String and StringBuffer are are sub-classes of the Object class, but without being in the same inheritance hierarchy. For finding ‘the most specific’ method, the compiler needs to find a method having the parameter type, which is a sub-class of the parameter types of all other overloaded methods.

This holds true for overloaded methods having more than one parameters as well. The compiler would pick ‘the most specific’ by looking which method is having at least one of its parameter types as a clear sub-class of the corresponding parameter type and other parameter types being either the same or clear sub-classes, in all other overloaded methods. If it can find one, good, otherwise it will throw a compile-time error. For example:


public class NullTest {

 public static void method(Object obj, Object obj1){
   System.out.println("method with param types - Object, Object");
 }

 public static void method(String str, Object obj){
   System.out.println("method with param types - String, Object");
 }

 public static void main(String [] args){
   method(null, null);
 }
}

Output

method with param types - String, Object


In this case the compiler can easily pick 'the most specific' as the method having parameter types (String, Object) as the other overloaded method is having its parameter types as (Object, Object) - clearly 'String' is a subclass of 'Object' and the other parameter is of same type, so the method with parameter types (String, Object) can be picked with ease. But, the below code would throw a compile-time error as none of the methods satisfy the condition for being picked as 'the most specific' method.


public class NullTest {

 public static void method(Object obj, String obj1){
   System.out.println("method with param types - Object, String");
 }

 public static void method(String str, Object str1){
   System.out.println("method with param types - String, Object");
 }

 public static void main(String [] args){
   method(null, null); //... compile-time error!
 }
}

Difference between Dynamic Binding & Static Binding in Java

Dynamic Binding or Late Binding Dynamic Binding refers to the case where compiler is not able to resolve the call and the binding is done at runtime only. Let’s try to understand this.

Suppose we have a class named ‘SuperClass’ and another class named ‘SubClass’ extends it. Now a ‘SuperClass’ reference can be assigned to an object of the type ‘SubClass’ as well.

If we have a method (say ‘someMethod()’) in the ‘SuperClass’ which we override in the ‘SubClass’ then a call of that method on a ‘SuperClass’ reference can only be resolved at runtime as the compiler can’t be sure of what type of object this reference would be pointing to at runtime. …

SuperClass superClass1 = new SuperClass();

SuperClass superClass2 = new SubClass();

superClass1.someMethod(); // SuperClass version is called superClass2.someMethod(); // SubClass version is called ….

Here, we see that even though both the object references superClass1 and superClass2 are of type ‘SuperClass’ only, but at run time they refer to the objects of types ‘SuperClass’ and ‘SubClass’ respectively.

Hence, at compile time the compiler can’t be sure if the call to the method ‘someMethod()’ on these references actually refer to which version of the method – the super class version or the sub class version. Thus, we see that dynamic binding in Java simply binds the method calls (inherited methods only as they can be overriden in a sub class and hence compiler may not be sure of which version of the method to call) based on the actual object type and not on the declared type of the object reference.

Static Binding or Early Binding If the compiler can resolve the binding at the compile time only then such a binding is called Static Binding or Early Binding. All the instance method calls are always resolved at runtime, but all the static method calls are resolved at compile time itself and hence we have static binding for static method calls. Because static methods are class methods and hence they can be accessed using the class name itself (in fact they are encourgaed to be used using their corresponding class names only and not by using the object references) and therefore access to them is required to be resolved during compile time only using the compile time type information. That’s the reason why static methods can not actually be overriden. 

 Similarly, access to all the member variables in Java follows static binding as Java doesn’t support (in fact, it discourages) polymorphic behavior of member variables.

For example:-

class SuperClass{ … public String someVariable = “Some Variable in SuperClass”; … }

class SubClass extends SuperClass{ … public String someVariable = “Some Variable in SubClass”; … }

… …

SuperClass superClass1 = new SuperClass();

SuperClass superClass2 = new SubClass();

System.out.println(superClass1.someVariable);

 System.out.println(superClass2.someVariable); …

Output:-

Some Variable in SuperClass

 Some Variable in SuperClass

We can observe that in both the cases, the member variable is resolved based on the declared type of the object reference only, which the compiler is capable of finding as early as at the compile time only and hence a static binding in this case. Another example of static binding is that of ‘private’ methods as they are never inherited and the compile can resolve calls to any private method at compile time only.

It is not always necessary to override hashcode and equals. But if you think you need to override one, then you need to override both of them. Let’s analyze what would happen if we override one but not the other and we attempt to use a Map.
Say we have a class like this and that two objects of MyClass are equal if their importantField is equal (with hashCode and equals generated by eclipse)
public class MyClass {

private final String importantField;
private final String anotherField;

public MyClass(final String equalField, final String anotherField) {
this.importantField = equalField;
this.anotherField = anotherField;
}

public String getEqualField() {
return importantField;
}

public String getAnotherField() {
return anotherField;
}

@Override
public int hashCode() {
final int prime = 31;
int result = 1;
result = prime * result
+ ((importantField == null) ? 0 : importantField.hashCode());
return result;
}

@Override
public boolean equals(final Object obj) {
if (this == obj)
return true;
if (obj == null)
return false;
if (getClass() != obj.getClass())
return false;
final MyClass other = (MyClass) obj;
if (importantField == null) {
if (other.importantField != null)
return false;
} else if (!importantField.equals(other.importantField))
return false;
return true;
}

}
 

Override only hashCode

 
Imagine you have this
MyClass first = new MyClass(“a”,”first”);
MyClass second = new MyClass(“a”,”second”);

If you only override hashCode then when you call

myMap.put(first,someValue)

 it takes first, calculates its hashCode and stores it in a given bucket. Then when you call

myMap.put(first,someOtherValue)

 it should replace first with second as per the Map Documentation because they are equal (according to our definition).
But the problem is that equals was not redefined, so when the map hashes second and iterates through the bucket looking if there is an object k such that second.equals(k) is true it won’t find any as second.equals(first) will be false.
Override only equals


If only equals is overriden, then when you call

myMap.put(first,someValue)

first will hash to some bucket and when you call

myMap.put(first,someOtherValue)

it will hash to some other bucket. So, although they are equal, as they don’t hash to the same bucket (different hashCode) the map can’t realize it and both of them stay in the map.
Hope it was clear

You must override hashCode() in every class that overrides equals(). Failure to do so will result in a violation of the general contract for Object.hashCode(), which will prevent your class from functioning properly in conjunction with all hash-based collections, including HashMap, HashSet, and Hashtable.

Introduction to JAXP

Chapter 1

Introduction to JAXP

The Java API for XML Processing (JAXP) is for processing XML data using applications written in the Java programming language. JAXP leverages the parser standards Simple API for XML Parsing (SAX) and Document Object Model (DOM) so that you can choose to parse your data as a stream of events or to build an object representation of it. JAXP also supports the Extensible Stylesheet Language Transformations (XSLT) standard, giving you control over the presentation of the data and enabling you to convert the data to other XML documents or to other formats, such as HTML. JAXP also provides namespace support, allowing you to work with DTDs that might otherwise have naming conflicts. Finally, as of version 1.4, JAXP implements the Streaming API for XML (StAX) standard.

Designed to be flexible, JAXP allows you to use any XML-compliant parser from within your application. It does this with what is called a pluggability layer, which lets you plug in an implementation of the SAX or DOM API. The pluggability layer also allows you to plug in an XSL processor, letting you control how your XML data is displayed.

The JAXP APIs

The main JAXP APIs are defined in the javax.xml.parsers package. That package contains vendor-neutral factory classes, SAXParserFactory, DocumentBuilderFactory, and TransformerFactory, which give you a SAXParser, a DocumentBuilder, and an XSLT transformer, respectively. DocumentBuilder, in turn, creates a DOM-compliant Document object.

The factory APIs let you plug in an XML implementation offered by another vendor without changing your source code. The implementation you get depends on the setting of the javax.xml.parsers.SAXParserFactory, javax.xml.parsers.DocumentBuilderFactory, and javax.xml.transform.TransformerFactory system properties, using System.setProperties() in the code, <sysproperty key="..." value="..."/> in an Ant build script, or -DpropertyName="..." on the command line. The default values (unless overridden at runtime on the command line or in the code) point to Sun’s implementation.

Overview of the Packages

The SAX and DOM APIs are defined by the XML-DEV group and by the W3C, respectively. The libraries that define those APIs are as follows:

  • javax.xml.parsers: The JAXP APIs, which provide a common interface for different vendors’ SAX and DOM parsers.
  • org.w3c.dom: Defines the Document class (a DOM) as well as classes for all the components of a DOM.
  • org.xml.sax: Defines the basic SAX APIs.
  • javax.xml.transform: Defines the XSLT APIs that let you transform XML into other forms.
  • javax.xml.stream: Provides StAX-specific transformation APIs.

The Simple API for XML (SAX) is the event-driven, serial-access mechanism that does element-by-element processing. The API for this level reads and writes XML to a data repository or the web. For server-side and high-performance applications, you will want to fully understand this level. But for many applications, a minimal understanding will suffice.

The DOM API is generally an easier API to use. It provides a familiar tree structure of objects. You can use the DOM API to manipulate the hierarchy of application objects it encapsulates. The DOM API is ideal for interactive applications because the entire object model is present in memory, where it can be accessed and manipulated by the user.

On the other hand, constructing the DOM requires reading the entire XML structure and holding the object tree in memory, so it is much more CPU- and memory-intensive. For that reason, the SAX API tends to be preferred for server-side applications and data filters that do not require an in-memory representation of the data.

The XSLT APIs defined in javax.xml.transform let you write XML data to a file or convert it into other forms. As shown in the XSLT section of this tutorial, you can even use it in conjunction with the SAX APIs to convert legacy data to XML.

Finally, the StAX APIs defined in javax.xml.stream provide a streaming Java technology-based, event-driven, pull-parsing API for reading and writing XML documents. StAX offers a simpler programming model than SAX and more efficient memory management than DOM.

Simple API for XML APIs

The basic outline of the SAX parsing APIs is shown in Figure 1-1. To start the process, an instance of the SAXParserFactory class is used to generate an instance of the parser.

Figure 1-1 SAX APIs

The SAX APIs

The parser wraps a SAXReader object. When the parser’s parse() method is invoked, the reader invokes one of several callback methods implemented in the application. Those methods are defined by the interfaces ContentHandler, ErrorHandler, DTDHandler, and EntityResolver.

Here is a summary of the key SAX APIs:

SAXParserFactory
A SAXParserFactory object creates an instance of the parser determined by the system property, javax.xml.parsers.SAXParserFactory.

SAXParser
The SAXParser interface defines several kinds of parse() methods. In general, you pass an XML data source and a DefaultHandler object to the parser, which processes the XML and invokes the appropriate methods in the handler object.

SAXReader
The SAXParser wraps a SAXReader. Typically, you do not care about that, but every once in a while you need to get hold of it using SAXParser‘s getXMLReader() so that you can configure it. It is the SAXReader that carries on the conversation with the SAX event handlers you define.

DefaultHandler
Not shown in the diagram, a DefaultHandler implements the ContentHandler, ErrorHandler, DTDHandler, and EntityResolver interfaces (with null methods), so you can override only the ones you are interested in.

ContentHandler
Methods such as startDocument, endDocument, startElement, and endElement are invoked when an XML tag is recognized. This interface also defines the methods characters() and processingInstruction(), which are invoked when the parser encounters the text in an XML element or an inline processing instruction, respectively.

ErrorHandler
Methods error(), fatalError(), and warning() are invoked in response to various parsing errors. The default error handler throws an exception for fatal errors and ignores other errors (including validation errors). This is one reason you need to know something about the SAX parser, even if you are using the DOM. Sometimes, the application may be able to recover from a validation error. Other times, it may need to generate an exception. To ensure the correct handling, you will need to supply your own error handler to the parser.

DTDHandler
Defines methods you will generally never be called upon to use. Used when processing a DTD to recognize and act on declarations for an unparsed entity.

EntityResolver
The resolveEntity method is invoked when the parser must identify data identified by a URI. In most cases, a URI is simply a URL, which specifies the location of a document, but in some cases the document may be identified by a URN – a public identifier, or name, that is unique in the web space. The public identifier may be specified in addition to the URL. The EntityResolver can then use the public identifier instead of the URL to find the document-for example, to access a local copy of the document if one exists.

A typical application implements most of the ContentHandler methods, at a minimum. Because the default implementations of the interfaces ignore all inputs except for fatal errors, a robust implementation may also want to implement the ErrorHandler methods.

SAX Packages

The SAX parser is defined in the packages listed in Table 1-1.

Table 1-1 SAX Packages
Packages Description
org.xml.sax Defines the SAX interfaces. The name org.xml is the package prefix that was settled on by the group that defined the SAX API.
org.xml.sax.ext Defines SAX extensions that are used for doing more sophisticated SAX processing-for example, to process a document type definition (DTD) or to see the detailed syntax for a file.
org.xml.sax.helpers Contains helper classes that make it easier to use SAX-for example, by defining a default handler that has null methods for all the interfaces, so that you only need to override the ones you actually want to implement.
javax.xml.parsers Defines the SAXParserFactory class, which returns the SAXParser. Also defines exception classes for reporting errors.

Document Object Model APIs

Figure 1-2 shows the DOM APIs in action.

Figure 1-2 DOM APIs

DOM APIs

You use the javax.xml.parsers.DocumentBuilderFactory class to get a DocumentBuilder instance, and you use that instance to produce a Document object that conforms to the DOM specification. The builder you get, in fact, is determined by the system property javax.xml.parsers.DocumentBuilderFactory, which selects the factory implementation that is used to produce the builder. (The platform’s default value can be overridden from the command line.)

You can also use the DocumentBuilder newDocument() method to create an empty Document that implements the org.w3c.dom.Document interface. Alternatively, you can use one of the builder’s parse methods to create a Document from existing XML data. The result is a DOM tree like that shown in Figure 1-2.


Note – Although they are called objects, the entries in the DOM tree are actually fairly low-level data structures. For example, consider this structure: <color>blue</color>. There is an element node for the color tag, and under that there is a text node that contains the data, blue! This issue will be explored at length in the DOM chapter of this tutorial, but developers who are expecting objects are usually surprised to find that invoking getNodeValue() on the element node returns nothing. For a truly object-oriented tree, see the JDOM API at http://www.jdom.org.


DOM Packages

The Document Object Model implementation is defined in the packages listed in Table 1-2.

Table 1-2 DOM Packages
Package Description
org.w3c.dom Defines the DOM programming interfaces for XML (and, optionally, HTML) documents, as specified by the W3C.
javax.xml.parsers Defines the DocumentBuilderFactory class and the DocumentBuilder class, which returns an object that implements the W3C Document interface. The factory that is used to create the builder is determined by the javax.xml.parsers system property, which can be set from the command line or overridden when invoking the new Instance method. This package also defines the ParserConfigurationException class for reporting errors.

Extensible Stylesheet Language Transformations APIs

Figure 1-3 shows the XSLT APIs in action.

Figure 1-3 XSLT APIs

XSLT APIs

A TransformerFactory object is instantiated and used to create a Transformer. The source object is the input to the transformation process. A source object can be created from a SAX reader, from a DOM, or from an input stream.

Similarly, the result object is the result of the transformation process. That object can be a SAX event handler, a DOM, or an output stream.

When the transformer is created, it can be created from a set of transformation instructions, in which case the specified transformations are carried out. If it is created without any specific instructions, then the transformer object simply copies the source to the result.

XSLT Packages

The XSLT APIs are defined in the packages shown in Table 1-3.

Table 1-3 XSLT Packages
Package Description
javax.xml.transform Defines the TransformerFactory and Transformer classes, which you use to get an object capable of doing transformations. After creating a transformer object, you invoke its transform() method, providing it with an input (source) and output (result).
javax.xml.transform.dom Classes to create input (source) and output (result) objects from a DOM.
javax.xml.transform.sax Classes to create input (source) objects from a SAX parser and output (result) objects from a SAX event handler.
javax.xml.transform.stream Classes to create input (source) objects and output (result) objects from an I/O stream.

Streaming API for XML APIs

StAX is the latest API in the JAXP family, and provides an alternative to SAX, DOM, TrAX, and DOM for developers looking to do high-performance stream filtering, processing, and modification, particularly with low memory and limited extensibility requirements.

To summarize, StAX provides a standard, bidirectional pull parser interface for streaming XML processing, offering a simpler programming model than SAX and more efficient memory management than DOM. StAX enables developers to parse and modify XML streams as events, and to extend XML information models to allow application-specific additions. More detailed comparisons of StAX with several alternative APIs are provided in Chapter 5, Streaming API for XML, in Comparing StAX to Other JAXP APIs.

StAX Packages

The StAX APIs are defined in the packages shown in Table 1-4.

Table 1-4 StAX Packages
Package Description
javax.xml.stream Defines the XMLStreamReader interface, which is used to iterate over the elements of an XML document. The XMLStreamWriter interface specifies how the XML should be written.
javax.xml.transform.stax Provides StAX-specific transformation APIs.

Creating RestFul Web services

MyEclipse Logo
 

Developing REST Web Services Tutorial

Version 7.0 or later required

Table of Contents

download the latest MyEclipse versionhelp and support
 

1. Introduction

This document will outline the process of developing a REST web service, deploying it to the internal MyEclipse Tomcat server and testing it with the REST Web Services Explorer. The REST features in MyEclipse are based on Jersey, which is the reference implementation for JAX-RS, the Java API for RESTful Web Services. We will be creating a simple web service which we will use to maintain a list of customers.

MyEclipse also supports developing SOAP web services using JAX-WS; for folks needing to develop and deploy WebSphere JAX-RPC or WebSphere JAX-WS web services, please take a look at MyEclipse Blue Edition.

Additional resources covering web service creation using JAX-WS and JAX-RPC are included in the Resources section of this document.

 

2. System Requirements

This tutorial was created with MyEclipse 7.0. If you are using another version of MyEclipse (possibly newer), most of these screens and instructions should still be very similar.

If you are using a newer version of MyEclipse and notice portions of this tutorial looking different than the screens you are seeing, please let us know and we will make sure to resolve any inconsistencies.

3. Creating the REST Web Service Project

To get started we will create a simple Web Service Project by selecting Web Service Project from the new toolbar menu:


Alternatively, invoke the wizard using File > New > Other > MyEclipse > Java Enterprise Projects > Web Service Project.

Name the project restdemo and select REST (JAX-RS) from the list of frameworks.

Click Next to move to page 2 of the wizard. On this page you can specify the path at which the services will be available, the name of the corresponding JAX-RS servlet and libraries which you wish to add to your project. For this project the defaults are fine, so click Finish to create the project.


JAX-RS servlet generated in web.xml

Note: Instead of creating a new project, you may also add REST capabilities to any existing Java EE 5 Web project. From the project’s context menu, select MyEclipse > Add REST Capabilities…

 

4. Creating the REST Web Service

4.1 Creating the Customer entity

To start, create a simple Customer class with id, name and address fields; this class represents the Customer entity we will be managing with our web service. Use the File > New > Class wizard, put Customer in the Name field, com.myeclipseide.ws in the Package field and Finish the wizard. Replace the contents of the generated class with the following code:

package com.myeclipseide.ws;import javax.xml.bind.annotation.XmlRootElement;

@XmlRootElement
public class Customer {

  private int id;
  private String name;
  private String address;

  public int getId() {
    return id;
  }

  public void setId(int id) {
    this.id = id;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public String getAddress() {
    return address;
  }

  public void setAddress(String address) {
    this.address = address;
  }

}

In this tutorial, we will be using XML as the serialization format, i.e. we will send and receive Customer entities from the web service using XML.The @XMLRootElement annotation on the Customer class is a JAXB annotation which allows JAXB to convert this entity from Java to XML and back. It is possible to annotate the fields and methods within the class to customize the serialization, but for our tutorial the JAXB defaults are fine.

4.2 Creating the CustomersResource class, the core of our web service

  1. Select the restdemo project and invoke the new web service wizard from the toolbar:

    Make sure the Project combo displays the restdemo project and the REST (JAX-RS) framework is selected. Select Create new Java bean and click Next.

  2. Fill out this page as shown in the following screenshot:
    • The URL path field indicates the path at which this resource can be reached, for this tutorial, we will use customers as this resource manages our customer list. The resource will thus be hosted at “/customers”.
    • Singleton lifecycle ensures that only one instance of this class will created by Jersey per web-application.
    • The Consumes and Produces combos can be used to specify the default mime type(s) of data which this resource can accept and generate. These values can be overridden by individual methods in the class. As mentioned above, we will be serializing to XML, so we use the application/xml mime type.
  3. Click the Add button in the above dialog to add the method that will fetch a list of customers. Fill out the wizard that pops up like so and click Finish.
    • The HTTP method combo can be used to specify what type of HTTP request this method will respond to; in this case, we wish to respond to an HTTP GET request.
    • The Method Signature preview will be updated as you make changes to the page, giving you an idea of what your method will look like once generated.
  4. Click the Add button again to add a method that will return details of a specific customer.
    • The URL path field specifies the path at which this method can be reached, relative to the containing resource.
      In this case we specify {id}, which means this resource method can be reached at /customers/{id}. The curly braces denote a URI variable. These variables are substituted at runtime in order for a resource to respond to a request based on the substituted URI.
    • Click Add to add a method parameter which can be directly edited in the table. Since we need the value of the id variable, we use the PathParam annotation to map it to the cId parameter.
  5. Finally, add a method which allows us to add a new customer to our list.
    • In this case, we’re responding to a POST request and expect application/xml input which would be deserialized into the customer parameter.
    • The customer parameter is an Entity parameter (unannotated) and is mapped directly from the message body of the incoming request.
    • We also override the default application/xml output specified by the CustomersResource class and specify text/html instead.
  6. After adding those 3 methods, your wizard should now look like this:

    Click Finish to generate the CustomersResource class, you will see a class with stubbed out resource methods as shown below:

    package com.myeclipseide.ws;import java.util.List;

    import javax.ws.rs.Consumes;
    import javax.ws.rs.GET;
    import javax.ws.rs.POST;
    import javax.ws.rs.Path;
    import javax.ws.rs.PathParam;
    import javax.ws.rs.Produces;

    import com.sun.jersey.spi.resource.Singleton;

    @Produces("application/xml")
    @Path("customers")
    @Singleton
    public class CustomersResource {

      @GET
      public List<Customer> getCustomers() {
        throw new UnsupportedOperationException("Not yet implemented.");
      }

      @GET
      @Path("{id}")
      public Customer getCustomer(@PathParam("id"int cId) {
        throw new UnsupportedOperationException("Not yet implemented.");
      }

      @POST
      @Path("add")
      @Produces("text/plain")
      @Consumes("application/xml")
      public String addCustomer(Customer customer) {
        throw new UnsupportedOperationException("Not yet implemented.");
      }
    }

  7. We must now provide implementations for the methods created by the above wizard. In a real application, at this point we would probably wire in a database using JPA or Hibernate to help manage our customer list, but a simple in-memory map is sufficient for this tutorial.Our implementation is simple; when a customer is received by our service, we give the entity a counter based id and add it to our map. Retrieving a customer from this map by id and providing a list of customers is straightforward as you can see below. You may copy this implementation into your class; observe that the class and method signatures have not changed, all we’re doing is fleshing out the generated stubs with an implementation of our service. We also add a single customer to the list for demonstration purposes.
    package com.myeclipseide.ws;import java.util.ArrayList;
    import java.util.List;
    import java.util.TreeMap;

    import javax.ws.rs.Consumes;
    import javax.ws.rs.GET;
    import javax.ws.rs.POST;
    import javax.ws.rs.Path;
    import javax.ws.rs.PathParam;
    import javax.ws.rs.Produces;

    import com.sun.jersey.spi.resource.Singleton;

    @Produces("application/xml")
    @Path("customers")
    @Singleton
    public class CustomersResource {

      private TreeMap<Integer, Customer> customerMap = new TreeMap<Integer, Customer>();

      public CustomersResource() {
        // hardcode a single customer into the database for demonstration
        // purposes
        Customer customer = new Customer();
        customer.setName("Harold Abernathy");
        customer.setAddress("Sheffield, UK");
        addCustomer(customer);
      }

      @GET
      public List<Customer> getCustomers() {
        List<Customer> customers = new ArrayList<Customer>();
        customers.addAll(customerMap.values());
        return customers;
      }

      @GET
      @Path("{id}")
      public Customer getCustomer(@PathParam("id"int cId) {
        return customerMap.get(cId);
      }

      @POST
      @Path("add")
      @Produces("text/plain")
      @Consumes("application/xml")
      public String addCustomer(Customer customer) {
        int id = customerMap.size();
        customer.setId(id);
        customerMap.put(id, customer);
        return "Customer " + customer.getName() " added with Id " + id;
      }
    }

    Note: You can invoke the the JAX-RS Method wizard directly for any class in a REST web service project by using the Add REST Method… context menu action. Right-click in the Java editor to bring up the context menu and select Add REST Method… from the MyEclipse submenu.

5. Deploying & Testing the Web Service

5.1 Deploying & Running the restdemo Project

The fastest way to deploy our web service is to deploy our web project using the Run As or Debug As action of MyEclipse Server Application. We can do that by right-clicking on our project, going down to Debug As (or Run As) and selecting MyEclipse Server Application:

If you have multiple server connectors configured, MyEclipse will ask you which one you want to use, for the purpose of this tutorial select MyEclipse Tomcat. If you don’t have any connectors configured, MyEclipse Tomcat will be used automatically for you to deploy your project to and then run.

Now MyEclipse will perform the following steps for you automatically:

  1. Package our web project, and deploy it in Exploded format to the application server
  2. Start the application server for us, loading our web project

The MyEclipse Web Browser will popup and show you the default index.jsp page of our web app, we don’t actually need this because we aren’t testing a web page, so you can close this view.

5.2 Testing the Web Service with the REST Web Services Explorer (PRO Only)

The easiest way to test our web service is to use the REST Web Services explorer. Since the explorer is available only to MyEclipse Professional subscribers, if you are MyEclipse Standard subscriber, please follow the instructions in section 5.3.

  1. Right-click the restdemo project and select Test with REST Web Services Explorer from the MyEclipse submenu as shown below:

    Note: If you deployed restdemo to an application server other than MyEclipse Tomcat, the WADL URL used in the explorer may contain an incorrect port, preventing the explorer from loading your WADL file. Correct the port and click the go button to proceed.

    You may also open the REST Web Services Explorer using the drop down from the main eclipse toolbar. In this case, you need to manually enter the path of a WADL file in the address bar before proceeding.

  2. Expand the customers node and select {id}. In the id field on the right, enter 0 and click Test. In the Raw View tab, observe the lone customer we have in our map being returned in XML.
  3. Let’s add a customer to our list. Expand select add under the customers node. In the content area on the right, paste the following and click Test:
    <customer>
        <name>Bill Adama</name>
        <address>Vancouver, Canada</address>
    </customer>
    The response should now say: Customer Bill Adama added with Id 1

  4. Select the customers node and click Test. The two customers in our list are returned by the service in XML.

5.3 Testing the Web Service Using a Standard Browser

  1. Open http://localhost:8080/restdemo/services/customers/0 in your browser to see the first customer in XML.
  2. To add a customer to our list, we need to send customer data to the service via an HTTP POST request. You could use a Firefox extension like Poster to make the request as shown below.
  3. Open http://localhost:8080/restdemo/services/customers in your browser to get a list of all customers in XML.

Note: If you deployed restdemo to an application server other than MyEclipse Tomcat, you may need to correct the port in the above links depending on your application server.

6. Resources

In this section we want to provide you with additional links to resources that supplement the topics covered in this tutorial. While this is not an exhaustive list, we do make an effort to point to the more popular links that should provide you with diverse, high-quality information.

 

About MessageContext

A little bit about Message Context in JAX-WS

Sometimes, Invoking Web Services require exchange of additional information or metadata (not captured in SOAP message). This metadata forms the context of message exchange and may in-turn change the way the message is processed. JAX-WS Specification defines some standard properties to describe the metadata and also provides a standard way to manipulate or exchange such information. I will briefly describe how such metadata is exchanged between various parts of the application and then go over the common usage of the standard properties defined by JAX-WS.

A client application can configure metadata through request context and response context of the BindingProvider ( instance of proxy or Dispatch). The request and response contexts are of type java.util.Map<String,Object> and are obtained using getRequestContext and getResponseContext methods of the BindingProvider. The following example shows how you can access/update request and response context.

Map requestContext = ((BindingProvider)stub).getRequestContext();
requestContext.put(BindingProvider.ENDPOINT_ADDRESS_PROPERTY,"http://example.com/webservices/service1");
Map responseContext = ((BindingProvider)stub).getResponseContext();
Integer responseCode = (Integer) responseContext.get(MessageContext.HTTP_RESPONSE_CODE);

MessageContext is a bag of properties to hold the metadata during the message exchange. The data from the request context is used to initialize the message context of the outbound message before invoking the handlers. This MessageContext is available to the all handlers in the handler-chain through which they can share processing related state. The contents of the message context are used to initialize the response context for an inbound message after invoking any handlers. The following example shows how one can access message context in a handler.

Handler {
    boolean handleMessage(SOAPMessageContext smc) {
        Boolean outbound = smc.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
        SOAPMessage sm = smc.getMessage();
        ............
    }
}

JAX-WS also defines ways to exchange context from client to the service endpoint implementation using the protocol binding in use. In SOAP/HTTP, some of this information goes in the HTTP Headers or in the SOAP Message. The client or handler can also use SOAP headers to exchange additional information.

This metadata for each invocation is accessible to the endpoint implementation through WebServiceContext. The server runtime will inject the WebServiceContext on any field marked with @Resource. getMessageContext method of WebServiceContext provides access to message context The following example shows the way to obtain message context in endpoint implementation.

@Resource 
WebServiceContext wsContext;

@WebMethod
public String echoHello(String msg) {
    MessageContext context = wsContext.getMessageContext();
    Map requestHeaders = (Map) context.get(MessageContext.HTTP_REQUEST_HEADERS) ;
    .......
}

As mentioned earlier, JAX-WS defines standard properties in BindingProvider and MessageContext that form the metadata. Most of the properties are self-explanatory by their name. Below, I list these standard properties as described in the JAX-WS specification. Refer to the API Javadoc for these two classes MessageContext and BindingProvider for more information. Some of the properties are applicable to outgoing message and the rest are applicable to incoming message. Properties on the BindingProvider are used to configure the client binding through request context. Properties set on request context of a BindingProvider (proxy) will be applied to all invocations using that proxy unless modified between invocations. The properties on response context hold the values for the last invocation. Listed below are the standard properties defined by JAX-WS.

BindingProvider Properties

ENDPOINT_ADDRESS_PROPERTY (Type: java.lang.String): This holds the target service endpoint address. This is generally used to set endpoint address on a Dispatch instance or to modify the endpoint address of the proxy.

SESSION_MAINTAIN_PROPERTY (Type: java.lang.Boolean): This boolean property is used by the client to indicate whether or not it wants to participate in a session with a service endpoint. If this property is set to true, the service client indicates that it wants the session to be maintained. If set to false, the session is not maintained. The default value for this property is false.

USERNAME_PROPERTY (Type: java.lang.String) and PASSWORD_PROPERTY (Type: java.lang.String): These properties are used for HTTP basic authentication.

SOAPACTION_USE_PROPERTY (Type: java.lang.Boolean): This property controls whether or not SOAPAction is to be used. The default value of this property is false indicating that the SOAPAction is not used.

SOAPACTION_URI_PROPERTY (Type: java.lang.String): Indicates the SOAPAction URI, if the javax.xml.ws.soap.http.soapaction.use property is set to true.

These above soap action properties are generally used for Dispatch clients. In case of proxy, by default, the soap action uri for a operation in the wsdl binding definition would determine its usage.

MessageContext Properties

MESSAGE_OUTBOUND_PROPERTY (Type: boolean): Specifies the message direction, true for outbound messages, false for inbound. This is used in handlers to determine if the processing is on a outbound or inbound message.

INBOUND_MESSAGE_ATTACHMENTS (Type: java.util.Map): A map of attachments to an inbound message. The key is the MIME Content-ID, value is a DataHandler for the attachment data. This property can be used to process the attachments in inbound message.

OUTBOUND_MESSAGE_ATTACHMENTS (Type: java.util.Map): A map of attachments to an outbound message. The key is the MIME Content-ID, value is a DataHandler for the attachment data. This property can be used on a proxy to send attachments not described through WSDL Mime binding.

The following properties are specific to HTTP protocol and are available only in HTTP based bindings.

HTTP_REQUEST_METHOD (Type: java.lang.String): Holds the name of the HTTP method with which this request was made, for example, GET, POST, or PUT.

HTTP_REQUEST_HEADERS (Type: java.util.Map): Holds a map of the HTTP headers for the request message.

QUERY_STRING (Type: String): Property for the HTTP Query String for the request message.

PATH_INFO (Type: String) : Extra path information associated with the request URL . This is the path information following the base url path but precedes the query string. QUERY_STRING and PATH_INFO properties are generally used with REST style clients, where the endpoint address is same and only the query string varies between each invocation.

HTTP_RESPONSE_CODE (Type: java.lang.Integer ) : Holds HTTP response status code for the last invocation.

HTTP_RESPONSE_HEADERS (Type: java.util.Map>) : Holds a map of the HTTP response headers.

These properties are specific to endpoints with HTTP based binding and running inside a servlet container.

SERVLET_CONTEXT (Type: javax.servlet.ServletContext): This property contains the ServletContext object belonging to the web application that contains the web endpoint.

SERVLET_REQUEST (Type: javax.servlet.http.HttpServletRequest ): This property holds the HTTPServletRequest object associated with the request currently being served.

SERVLET_RESPONSE (Type: javax.servlet.http.HttpServletResponse): This property holds the HTTPServletResponse object associated with the request currently being served.

These following properties are not mandatory and might be present only if the binding has information about WSDL metadata.

WSDL_DESCRIPTION (Type: java.net.URI): A resolvable URI that may be used to obtain access to the WSDL for the endpoint.

WSDL_SERVICE (Type: javax.xml.namespace.QName ): The name of the Service being invoked.

WSDL_PORT (Type: javax.xml.namespace.QName ): The name of the port to which the current message was received.

WSDL_INTERFACE (Type: javax.xml.namespace.QName ): The name of the port type to which the current message belongs.

WSDL_OPERATION (Type: javax.xml.namespace.QName ) :The name of the WSDL operation to which the current message belongs. The namespace is the target namespace of the WSDL definitions element.

In addition to these standard properties, User can define application specific properties in the message context to share state between client application and handlers, and handlers can insert this information as SOAP headers to convey the same information to service endpoint implementation.

In conclusion, JAX-WS provides you an easier and standard way to share the metadata across. Check out the latest JAX-WS 2.0 Reference Implementation and try it yourself. JAX-WS 2.0 sources are available on jax-ws project and binaries on GlassFish. I hope this is useful for developers – Your comments are most welcome.

Jax-ws Handlers

Handlers are interceptors that can be easily plugged into the Java API for XML-Based Web Services (JAX-WS) 2.0 runtime environment to do additional processing of inbound and outbound messages. JAX-WS defines two types of handlers: protocol handlers and logical handlers. Protocol handlers are specific to a protocol such as SOAP. They can access or change any part of the message, including protocol-specific parts such as the message header. Logical handlers are protocol-agnostic. They cannot change any protocol-specific parts of a message. Logical handlers act only on the payload of the message.

This tip shows you how to write a SOAP protocol handler and a logical handler for use with JAX-WS. Handler Basics.

Handler Basics

SOAP handlers are generally used to process SOAP-specific information, such as SOAP headers. For example, a SOAP Handler can process security headers in a message and pass the request to the endpoint if the message has the required credentials. Logical handlers are commonly used if the processing does not need access to SOAP headers, for validation of the payload, and with Representational State Transfer (“REST”) style web services. In addition, logical handlers can use Java API for XML Binding (JAXB) for processing the payload. If you have the JAXBContext object, it’s simple to alter something in a message with a logical handler. You can get the JAXB objects and call Java methods on them rather than dealing with Source objects or SOAPMessage objects using the SOAP with Attachments API for Java (SAAJ) in a SOAP handler.

Handlers are invoked with a message context, which provides methods that the handler uses to access and modify inbound or outbound messages. The message context also has properties that the handler can process. These properties can be used to communicate additional information or metadata that is not specified in the message. The additional information can be exchanged between a handler and service implementation or between a handler and a web service client. (For more information about message context in JAX-WS, see the article A little bit about Message Context in JAX-WS.)

SOAP handlers extend javax.xml.ws.handler.soap.SOAPHandler. The JAX-WS specification defines the SOAPHandler class for SOAP binding. When a SOAP handler is invoked, a SOAPMessageContext object is specified in the request. The SOAPMessageContext object provides methods to access a SOAPMessage (the class for SOAP messages). Specifically, the method getMessage() in SOAPMesageContext retrieves the SOAPMessage. After getting a SOAPMessage, you can use SAAJ to manipulate it.

Logical handlers extend javax.xml.ws.handler.LogicalHandler. They provide access to the message context and the message payload. If you use SOAP over HTTP for the message exchange, the content of the SOAP body forms the payload. If you use XML over HTTP, the XML content of the primary part of the message forms the payload. When a logical handler is invoked, a LogicalMessageContext object is specified in the request. The method getMessage() in LogicalMessageContext returns a LogicalMessage. The LogicalMessage represents a protocol-neutral XML message and contains methods that provide access to the payload of the message.

The following figure illustrates the relationship between the message contexts, the objects they can be used to retrieve, and the parts of a message those objects cover.
Image

Logical handlers can coexist with SOAP handlers in a handler chain. During runtime, the handler chain is reordered so that for an outbound message the logical handlers execute before the SOAP handlers. For an inbound message, the SOAP handlers execute before the logical handlers.

The following figure shows how logical and SOAP handlers are invoked during a request and response.
Image

Writing a SOAP Message Handler

Let’s look at a simple SOAP handler. A sample package (http://java.sun.com/developer/EJTechTips/download/ttjun2006handler.zip) accompanies this tip. Download the sample package and extract its contents. You’ll see two source files. One of them, SOAPLoggingHandler, is a SOAP handler that logs calls to a web service. Here’s a code snippet from SOAPLoggingHandler:

   public class SOAPLoggingHandler implements 
    SOAPHandler<SOAPMessageContext> {
   ... 
   
      public boolean handleMessage(SOAPMessageContext smc) {
          logToSystemOut(smc);
          return true;
      }
       
      public boolean handleFault(SOAPMessageContext smc) {
          logToSystemOut(smc);
          return true;
      }
       
      public void close(MessageContext messageContext) {
      }
      
   ...  

Like all SOAP handlers, SOAPLoggingHandler implements the SOAPHandler interface. Notice that SOAPLoggingHandler also implements three methods: handleMessage(), handleFault(), and close(). The SOAPHandler interface is a subinterface of the Handler interface. The handleMessage(), handleFault(), and close() methods are the three methods defined in the Handler interface, and should be implemented in all basic handlers. Here’s how the methods are used:

  • handleMessage() is called for normal processing of inbound and outbound messages.
  • handleFault is called when a message contains a protocol fault.
  • close( ) is called after the completion of message processing by all handlers for each web service invocation, that is, after the completion of a SOAP method exchange pattern (or “MEP”).

The logging is done in the handler’s logToSystemOut() method that both the handleMessage() and handleFault() methods call:

    private void logToSystemOut(SOAPMessageContext smc) {
        Boolean outboundProperty = (Boolean)
            smc.get (MessageContext.MESSAGE_OUTBOUND_PROPERTY);
        
        if (outboundProperty.booleanValue()) {
            out.println("\nOutbound message:");
        else {
            out.println("\nInbound message:");
        }
        
        SOAPMessage message = smc.getMessage();
        try {
            message.writeTo(out);
            out.println("");   
        catch (Exception e) {
            out.println("Exception in handler: " + e);
        }
    }

Notice that the logToSystemOut() method accesses a SOAPMessageContext property, MESSAGE_OUTBOUND_PROPERTY, and uses a SOAPMessageContext method, getMessage(). The value of MESSAGE_OUTBOUND_PROPERTY indicates the message direction. A value of true means that the message is outbound. A value of false indicates an inbound message. Based on the property value, logToSystemOut() prints either “Outbound message” or “Inbound message.” It then uses getMessage() to get the SOAP message, and prints it.

Writing a Logical Message Handler

As its name suggests, the LogicalLoggingHandler file in the sample package is a logical message handler. Like the SOAPLoggingHandler, it logs calls to a web service. Here’s a code snippet from LogicalLoggingHandler:

   public class LogicalLoggingHandler implements 
    LogicalHandler<LogicalMessageContext> {
   ...
   
       public boolean handleMessage
        (LogicalMessageContext context) {
           return processMessage(context);
       }
       
       public boolean handleFault
        (LogicalMessageContext context) {
           return processMessage(context);
       }
       
       public void close(MessageContext context) {
           // Clean up Resources
       }

Like all logical handlers, LogicalLoggingHandler implements the LogicalHandler interface. And like all handlers it implements the handleMessage(), handleFault(), and close() methods.

The logging is done in the handler’s processMessage() method that both the handleMessage() and handleFault() methods call:

   private boolean processMessage
    (LogicalMessageContext context) {
       Boolean outboundProperty = (Boolean)
          context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);
   
          if (outboundProperty) {
              out.println("\nOutbound message:");
          else {
              out.println("\nInbound message:");
          }
          LogicalMessage lm = context.getMessage();
          Source payload = lm.getPayload();
   
          // Process Payload Source
          printSource(payload);
          // ....
          
          // If the payload is modified, 
          // Do lm.setPayload(source) to be safe. Without it, 
          // behavior may vary on the kind of source returned in 
          // lm.getPayload().
          // See LogicalMessage JavaDoc for more details.
          // lm.setPayload(modifiedPayload);
          return true;

The processMessage() method accesses and manipulates the message payload using the logical message context for the logical handler. It calls the LogicalMessage method, getPayload(), to get the payload of the message. The payload is returned as a Source object.

Notice the commented out portion of processMessage(). In some cases, you might need to call the LogicalMessage method, setPayload(), after a modification is made to the payload. The source returned by getPayload() depends on the JAX-WS runtime. If the returned source is DOMSource, a modification to the encapsulated DOM tree changes the message payload in place. In that case, there is no need to subsequently call setPayload(). However, other types of returned source provide only read access to the message. In those cases, you need to call setPayload() after any modifications.

You can also pass a JAXBContext object in the call to getPayload(), to get the payload as a JAXB object. Here’s an example:

   LogicalMessage lm = context.getMessage();
   Object jaxbObject = lm.getPayload(jaxbContext);
   // Modify JAXB Object
   lm.setPayload(modifiedJaxbObject,jaxbContext);

Note that there is no connection between the returned object and the message payload — to change the payload, you need to call setPayload().

Handlers are flexible to plug-in and can be a powerful addition to your application. For another JAX-WS handler example, see “Handler example using JAXWS 2.0″ in Stephen DeMilla’s blog (http://blogs.sun.com/roller/page/sdimilla?entry=implementing_handlers_using_jaxws_2)