Web services Policy - Why, What & How

Archived Content
This article is provided for historical perspective only, and may not reflect current conditions. Please refer to relevant product page for more up-to-date product information and resources.
  • By wso2 wso2
  • 23 Jan, 2006


Web services allow two applications to communicate in a platform independent manner across the web. Web services use an XML based inter-networking protocol as a means of communication which provides cross platform capabilities. For instance, its quite possible for a Web service written using the Indigo Web service engine to communicate with Apache Axis Web service engine without any problem.

If you need to consume or use a Web service, there is some essential information users need to know, such as the names of the methods available for execution in that particular web service, format of the messages it takes as its argument, and format of the messages it sends as the result, if any. Further more, user needs to know the URLs at which the web service is hosted and what the binding protocols are to access it.

Web service Description Language (WSDL) is designed to provide that sort of information to users. It provides basic information needed to successfully integrate two web services.

Motivation behind WS Policy

As user requirements get complex with value added features like encryption or reliability, information other than what is provided in the WSDL is necessary for two web services to inter operate successfully.

For instance, a user needs to find out whether Web services (WS) Security is mandatory for a particular web service, and if so, he must then determine the type of security tokens that this service is capable of processing, and what its preferences are. Thereafter user needs to know whether the messages must be singed or not, before sending them to the service. If it must be signed, then user needs to know which parts to be singed and which tokens to be used for digital signature. Once this is known the user must also find out whether the messages are to be encrypted, and if so which algorithms to use for encryption.

Until now there was no way to express such information except via documentation, direct inquires, For example via email between user &author etc. Addressing this issue WS Policy defines a general framework which can be used and extended by other WS specifications to convey these other information which are essential for successful consumption or use of webservices.

WS Policy Attachment

WS Policy Attachment defines a generic way to say that a particular policy is applicable for a particular policy subject. For instance, a WS Policy attachment will provide a way to define two separate policies' input and output messages of a particular operation of a Web service.

WS Commons/Policy Framework

XML is widely represented as Document Object Model (DOM) as it provides a convenient way to present and manipulate XML at runtime. Likewise policy information must be represented in a manner in which it can be made use of during runtime. WS-commons/Neethi does just that. In other words, it provides a convenient model to represent and manipulate any policy information at runtime.

In this ws-commons/policy framework a requirement is viewed as an assertion. An assertion can be of two types.

  1. Primitive Assertion - This is a domain specific requirement. One needs domain-specific knowledge to process a primitive assertion. Primitive assertion need not be atomic. It might contain several complex policies as its children. The only speciality of primitive assertions is that they isolate any domain specific knowledge from the general framework. In other words, they act as wrappers to make the policy framework independent from any other domain.
  2. Composite Assertion - This contains a set of requirements and implicit knowledge on how these requirements should be met. There are two types of composite assertions.
    1. AND type composite assertions require all their children terms be met
    2. where as XOR type composite assertions require exactly one child term be met.

    Another composite assertion called POLICY exists. Its rather an extension of AND composite type where the logic is almost the same except it should always be the grand parent of any other composite / primitive assertion.

Lets consider an example.

Say we have two configuration requirements,

  1. Value of the Property X should always be A.
  2. Setting the Property Y is optional.

Lets represent this using the policy object model we have:


Code Sample on how to create Policy Model from an existing PolicyDocument.

This ws-commons/policy provides you a class called PolicyReader from which you can create a Policy object feeding a policy document as an InputStream. Since policy document is nothing more than a bunch of XML, depending on the mechanism it uses to process XML, PolicyReader provides two implementations of its own.

One depends on Axis2-OM (Axis2 Object Model). This is known to be very efficient as it uses XML PullParsing as its underlying mechanism to process XML input. the Second one depends on DOM (Document Object Model) as its underlying mechanism to process XML input.

<code sample>

String fileName = “/home/sanka/.../policy.xml";
PolicyReader prdr = PolicyFactory.getPolicyReader(PolicyFactory.OM_POLICY_READER); // use
// if you want to use DOM impl instead
InputStream fis = new FileInputStream(fileName);
Policy policy = prdr.readPolicy(fis);


Likewise ws-commons/policy provides a class called PolicyWriter which can be used to serialize any policy object. PolicyWriter.writePolicy(..) takes the policy object as its first argument and an OutputStream as the second argument to which the policy object is being written as its being serialized.


PolicyWriter pwtr = PolicyFactory.getPolicyWriter(PolicyFactory.StAX_POLICY_WRITER);
Policy policy1 = ... ;
pwtr.writePolicy(policy1, System.out);


WS Policy Specification

WS Policy specification define policy operations to manipulate policies. WS-Commons/Policy framework support all these operations which are extremely useful when trying to do complex policy manipulations. Lets have a brief look at these policy operations:

  • Policy Normalization:

This is a process of converting a policy consisting of a number of elements in random order to a standard format. This conversion preserve the logic of original policy making life very much easier by giving us a standard format to deal with. Hence policy normalization becomes an extremely useful operation.

Normalized format is such that POLICY can have exactly one XOR term which represents the policy alternatives. XOR can have zero or more AND terms which are the policy alternatives of the policy. Any AND can contain zero or more primitive terms as its children terms.

  • Policy Intersection:

This is a process of isolating any policy alternatives of two policies which both parties understand. This is very useful when a web client wants to interact with a web service. First, client must see whether there are any policy alternatives available when intersecting its policy against the server policy. If any policy alternatives exist it must choose one of them. If no alternatives are found client cannot interact with the server.

The way to calculate the intersect is somewhat interesting. An alternative from the first policy is compared with a policy alternative taken from the second policy. If all the domains of primitive assertions of first alternative is the same as all the domains of primitive assertions of second alternative, we create a new policy alternative with all the primitive assertions of both alternatives. Likewise all possible alternatives are constructed and included in the resultant policy.

  • Policy Merge

Policy Merge is the process of creating a single policy from two policies with all possible alternatives which both parties agree on. It is understood that if you take any alternative from the merged policy, it satisfies at least one policy alternative of each party. Its an extremely useful operation specially on the server-side. For instance, the entire system have a single policy and each service hosted in this system may contain its own policy. When you ask for the policy of a service hosted in this system, you should be giving the merged policy of service policy and server policy. Another name for this merged policy is effective policy for the service.

We calculate an alternative of the merged policy by including all children terms of a single policy alternative of one policy and all children terms of a single policy alternative of the other policy. All possible alternatives which can be constructed in this manner is included in the resultant policy.


Ability to interoperate across different Web service platforms has been a star feature of Axis2. In order to achieve this to the highest level additional information about Web service configurations such as security configurations, reliability configurations etc is required by the Web service client. WS Policy provides a common syntax to express such information in a machine-readable way. The general framework it provides can be used or extended by other Web services specifications to express their configurations in a standardized machine-readable format. It enables two Web services infrastructures to exchange configuration information and configure themselves which ensure their interoperability. Automating this entire process serves as the ultimate task and hence brings that much importance to WS-Policy and its implementations.


About Author

  • wso2 wso2
  • wso2