WS-Policy Framework Overview

The WS-Policy framework provides infrastructure and APIs that allow CXF users and developers to use WS-Policy.

It is compliant with the November 2006 draft publications of the Web Services Policy 1.5 - Framework and
Web Services Policy 1.5 - Attachment specifications.

The framework consists of a core runtime and APIs that allow developers to plug in support for their own domain assertions:

Core

The core is responsible for:

retrieval of policies from different sources (wsdl documents, external attachment documents)
computation of effective policies for service, endpoint, operation and message subjects
on-the-fly provision of interceptors based on the effective policies for a particular message
verification that one of the effective policy's alternative is indeed supported.

Policy operations such as merge and normalisation (but not intersection) are based on Apache Neethi.

APIs

AssertionBuilder

The AssertionBuilder API is a concept from Neethi, slightly modified to avoid the dependency on the Axis object model, and extended to include support for domain specific behaviour of intersection and comparison of assertions.

public interface AssertionBuilder {
   // build an Assertion object from a given DOM element
   Assertion build(Element element);
  // return the schema type names of assertions understood by this builder
  Collection<QName> getSupportedTypes();
  // return an Assertion object that is compatible with the specified assertions
  Assertion buildCompatible(Assertion a, Assertion b);
}

AssertionBuilder implementations are loaded dynamically and register themselves with the AssertionBuilderRegistry, which is available as a Bus extension. Currently, CXF supports AssertionBuilder and Assertion implementations for the following assertion types:

  {http://schemas.xmlsoap.org/ws/2005/02/rm/policy}RMAssertion
  {http://www.w3.org/2007/01/addressing/metadata}Addressing, {http://www.w3.org/2007/01/addressing/metadata}AnonymousResponses, {http://www.w3.org/2007/01/addressing/metadata}NonAnonymousResponses
  {http://cxf.apache.org/transports/http/configuration}client, {http://cxf.apache.org/transports/http/configuration}server

They are all based on generic Assertion implementations (PrimitiveAssertion, NestedPrimitiveAssertion, JaxbAssertion) that developers can parameterize or extend when developing their own assertions.

PolicyInterceptorProvider

This API is used to automatically engage interceptors required to support domain specific assertions at runtime, thus simplifying interceptor configuration a lot.

public interface PolicyInterceptorProvider extends InterceptorProvider {
  // return the schema types of the asssertions that can be supported
  Collection<QName> getAssertionTypes()
}

Currently, CXF supports PolicyInterceptorProvider implementations for the following assertion types:

  {http://schemas.xmlsoap.org/ws/2005/02/rm/policy}RMAssertion
  {http://www.w3.org/2007/01/addressing/metadata}Addressing, {http://www.w3.org/2007/01/addressing/metadata}AnonymousResponses, {http://www.w3.org/2007/01/addressing/metadata}NonAnonymousResponses

In addition, there is an API to refine domain expression(s) (xml elements describing policy subjects within a policy scope) in policy attachments. There is currently only one working implementation for EndpointReferenceType domain expressions (matching over the address). Another implementation, using XPath expressions, is in work.

Interaction with the Framework

Components interact with the policy framework typically to

retrieve the assertions pertaining to the underlying message (i.e. the ones known to the component) so the component can operate on the message accordingly
confirm that the assertions pertaining to the underlying message are indeed supported.

Like most other CXF features, the policy framework is itself largely interceptor based. Thus, most interaction with the framework is indirect through the Message object: Policy interceptors make AssertionInfo objects available as a message property to subsequently executing, policy-aware interceptors like the WS-Addressing and WS-RM interceptors. These interceptors extract the AssertionInfo objects from the Message, allowing them to performs steps 1. and 2. above:

import org.apache.neethi.Assertion;

public class AssertionInfo {
  ...
  public boolean isAsserted() {...}
  public void setAsserted(boolean asserted) {...}
  public Assertion getAssertion() {...}
}

Conduits and destinations may also want to assert their capabilities. However they cannot normally wait for Assertion information being made available to them via the Message object:
Conduits may have to perform some initialisation before actually sending a message. Although they may still exhibit message specific behaviour (for example, apply message specific receive timeouts), decisions made during the initialisation phase may limit their capability to do so.
And Destinations cannot normally exhibit message or operation specific behaviour at all. But they may still be able to support assertions in the effective endpoint's policy; and have their behaviour configured to some extent by such assertions.
In the absence of a Message object, destinations and conduits can obtain information about the assertions in the effective policy for the endpoint directly from the PolicyEngine, which is available as a bus extension. This is the runtime component of the policy framework that performs the retrieval of policy information, the computation of effective policies as well as the caching of the results of such operations. It is what the policy interceptors themselves use to obtain that type of information before making it available to other interceptors (or the conduit in its send method) in the form of AssertionInfo objects.

An example for conduit/destination based assertion are the HTTP conduit and destination, which support assertions of element type HTTPClientPolicy and HTTPServerPolicy resp..

Child pages