Page History

The WS-Policy framework in CXF provides infrastructure and APIs that allows 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.

Core

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

Core

The core which is responsible for:

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

The core uses Apache Neethi to provide the functionality of policy merging and normalisation, but comes with its own implementation of policy intersection.

APIs

The framework also defines APIs that allow developers to add pluggable support for their own domain assertions. These are:

Policy operations such as merge, normalisation, and intersection are based on Apache Neethi.

APIs

AssertionBuilder

The AssertionBuilder API is a concept an interface from Neethi, slightly modified so as to avoid the dependency on the Axis object model and extended in order to support domain specific behaviour of intersecting and comparing such assertions.

...

public interface AssertionBuilder {
   // build an Assertion object from a given xml 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 are automatically registered 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

along with the WS-SecurityPolicy defined assertions.

They are all based on generic Assertion implementations (PrimitiveAssertion, NestedPrimitiveAssertion, JaxbAssertion) that developers can parameterize or extend when developing their own assertions, see Developing AssertionsAssertionBuilder implementations are loaded dynamically and register themselves with the AssertionBuilderRegistry, which is available as a Bus extension.

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

along with the WS-SecurityPolicy defined assertions.

In addition, the framework offers 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 implementation for EndpointReferenceType domain expressions (matching over the address). Another implementation, using XPath expressions, is in work.

Interaction with

...

the Framework

Components interact A component's interaction with the policy framework typically consists mainly in order to:

1. retrieving retrieve the assertions pertaining to the underlying message (i.e. at least the ones known to the component) so the component can operate on the message accordingly
2. confirmation confirm that the assertions pertaining to the underlying message could are indeed be supported by component. The framework itself is, as most

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 (stateful representations of assertions) available to subsequently executing, policy-aware interceptors

...

by inserting them into the Message object. Extracting the AssertionInfo objects from the Message allows interceptors to perform steps 1. and 2. above:

import org.apache.neethi.Assertion;

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

The WS-Addressing and WS-RM interceptors

...

are examples for this style of intercation.

Somtimes, Conduits and destinations also want to assert their capabilities. But they cannot normally wait for Assertion information being made available to them via the Message object:
Conduits may exhibit message specific behaviour (for example, apply message specific receive timeouts), but 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 both may still be able to support assertions in the effective endpoint's policy.

Their interaction with the policy framework therefore typically involves the PolicyEngine through which they obtain the effective policy for the underlying endpoint (for step 1.):

 
public interface PolicyEngine {
    ...
    EndpointPolicy getClientEndpointPolicy(EndpointInfo ei, 
        Conduit conduit);    
    EndpointPolicy getServerEndpointPolicy(EndpointInfo ei, 
        Destination destination); 
}

public interface EndpointPolicy {
    ...
    Policy getPolicy(); 
    Collection<Assertion> getChosenAlternative();
}

To perform step 2. they implement the Assertor interface (namely its assertMessage method):

public class Assertor {
  ...
  public boolean canAssert(QName name);
  public void assertMessage(Message message);
}

An example for policy aware conduits and destinations in CXF are the HTTP conduit and destination. They do Some components needs to integrate more tightly with the policy framework however: this is the case when a conduit or a destination want to participate in the assertion process. An example for this is the HTTP conduit and destination, which support assertions of element type HTTPClientPolicy and HTTPServerPolicy . These obtain the Assertion information pertaining to the current message exchange from the PolicyEngine (which is also available as a bus extension), to perform step 1respectively.