Page History

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:

...

• 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.

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

...

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);
}

an interface from Neethi.

AssertionBuilder AssertionBuilder implementations are loaded dynamically and register themselves 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 Assertions.

PolicyInterceptorProvider

...

{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, there is the framework offers 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.

...

Components interact with the policy framework typically mainly in order to:

1. 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. 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 (stateful representations of assertions) available as a message property to subsequently executing, policy-aware interceptors like the WS-Addressing and WS-RM interceptorsby inserting them into the Message object. Extracting the AssertionInfo objects from the Message allows these 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 may also want to assert their capabilities. However But 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), 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 they both 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 .

Their interaction with the policy framework therefore typically involves the PolicyEngine through which they obtain 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. 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 An example for conduit/destination based assertion are the HTTP conduit and destination, which support assertions of element type HTTPClientPolicy and HTTPServerPolicy resp.respectively.