How It Works

Retrieval of Policies

Policies are associated with policy subjects. In the web services context, there are four different subjects:

• Service
• Endpoint
• Operation
• Message

Using WSDL 1.1, the policy-subject association usually takes the form of xml element attachment: a wsp:Policy element is attached to a WSDL element such as wsdl:port Ythe wsp prefix denotes the http://www.w3.org/2006/07/ws-policy namespace). Similary, wsp:PolicyReference elements can be attached to a wsdl element. In that case, the actual wsp:policy element may reside outside of the wsdl). Note that subjects do not correspond to wsdl elements directly. Rather, they map to a set of wsdl elements (see below). For example wsdl:port, wsdl:portType and wsdl:binding elements together describe the endpoint as a subject.

Another form of associating policies with policy subjects is external attachment: wsp:PolicyAttachment elements, which can reside in arbitrary locations, explicitly specify the subject(s) they apply to in their AppliesTo child element.

In CXF, elements attached to a wsdl element are available as extensors in the service model representation of that wsdl element: wsp:Policy and wsdp:PolicyReference elements can be obtained through the service model as extensors of type UnknownExtensibilityElement with matching element names (note that these attached elements are not parsed when the service model is built).
Policies attached to their subject through xml element attachment in WSDL 1.1 can therefore be obtained through the service model associated with an endpoint/an operation.

<bean class="org.apache.cxf.ws.policy.attachment.external.ExternalAttachmentProvider">
    <constructor-arg ref="cxf"/>
    <property name="location" value="org/apache/cxf/systest/ws/policy/addr-external.xml"/>
</bean>

Note that PolicyAttachments are extensible w.r.t. the type of domain expressions. Domain expressions are used to identify entities such as endpoints, operations or messages with which a policy can be associated:

<wsp:PolicyAttachment>
    <wsp:AppliesTo> 
        <x:DomainExpression/> +
    </wsp:AppliesTo>
    (<wsp:Policy>...</wsp:Policy> | <wsp:PolicyReference>...</wsp:PolicyReference>)
</wsp:PolicyAttachment>

Currently, CXF supports domain only domain expressions of type wsa:EndpointReferenceType: This allows to associate the policies or policy references in an attachment with an endpoint (by means of matching the endpoint's address with that in the EndpointReferenceType element).
Support for other types of domain expressions can be plugged in by implementing the DomainExpressionBuilder interface and adding a corresponding bean to your configuration file (all DomainExpressionBuilder instances loaded that way will automatically register with the DomainExpressionBuilder and thus be considered in the process of parsing PolicyAttachment elements).

Now that the framework knows where to look for wsp:Policy, it parses the elements and creates runtime presentations for them. This is where AssertionBuilders come into play: Child elements of a wsp:Policy element that are not in the wsp namespace are considered to be assertions. The framework will use its AssertionBuilderRegistry to find an AssertionBuilder registered for the element type in question and in that case proceed to build an Assertion object (or else throw a PolicyException).

Computation of Effective Policies

As mentioned above, policies are associated with policy subjects. With WSDL 1.1, the effective policy for a subject is the aggregation, or the merge, of the policies attached to the wsdl elments representing that subject:
The effective policy for a service subject is the merge of all policies applying to the wsdl:service element.
The effective policy for an endpoint subject is the merge of all policies applying to the wsdl:port, wsdl:portType and wsdl:binding elements.
The effective policy for an operation subject is the merge of all policies applying to the wsdl:portType/wsdl:operation and wsdl:binding/wsdl:operation elements.
The effective policy for a (input | output | fault) message subject is the merge of all policies applying to the wsdl:message, (wsdl:portType/wsdl:operation/wsdl:input | wsdl:portType/wsdl:operation/wsdl:output | wsdl:portType/wsdl:operation/wsdl:fault) and (wsdl:binding/wsdl:operation/wsdl:input | wsdl:binding/wsdl:operation/wsdl:output | wsdl:binding/wsdl:operation/wsdl:fault).

Additional aggregation takes place to determine the effective policy of an endpoint:
The effective policy for a service is the effective policy for the service subject.
The effective policy for an endpoint is the merge of the effective policies for the service subject and the endpoint subject.
The effective policy for an operation is the merge of the effective policies for the service subject, the endpoint subject and the operation subject.
The effective policy for a (input | output | fault) message is the merge of the effective policies for the service subject, the endpoint subject, the operation subject and the message subject.

It is also obvious that the above aggregation process can be quite resource intense. Effective policies for messages and endpoints are therefore cached by the framework for future reference. The entity that manages the cache of effective policies is the PolicyEngine.

At the same time of computing the effective policy for an endpoint or a message, the framework chooses one of the effective policy's alternatives. Currently, the first alternative that in principle can be supported by interceptors (i.e. for which there is a PolicyInterceptorProvider) or by the conduit/destination is chosen. This choice, along with the set of interceptors (obtained from the PolicyInterceptorProviders in the PolicyInterceptorProviderRegistry), is cached along with the actual effective message or endpoint policy in the form of an EffectivePolicy or EffectiveEndpointPolicy object. In the case of an effective endpoint policy, interceptors are chosen in such a way that the assertions in the chosen alternative of the effective endpoint policy can be supported, but also any assertion in any alternative of any of the operation and message specific policies. This is necessary in situations where the underlying message is not yet know, for example on the server onbound path: Once an alternative has been chosen for the effective policy of the server's endpoint we know which assertions must definitely be supported, regardless the underlying message/operation. Additional interceptors that are necessary to support the assertions that only appear in specific operation or input message policies are added pre-emptively. Note that this relies on interceptors being coded defensively - good practice anyway but especially so for interceptors returned by PolicyInterceptorProviders!

On-the-fly Provision of Interceptors

The policy framework, when activated (by loading the PolicyEngine and setting its "enabled" attribute to true), installs a couple of interceptors at bus level which execute early on in their respective interceptor chains:

Their main function is to add interceptors that are required to support the effective policy of the underlying message - even if that policy is not yet known at this point (because the operation is not yet known).
In case where the effective message policy is known, the assertions of its selected alternative are inserted into the message in the form of an AssertionInfoMap. This way subsequent interceptors need not be concerned about the details of obtaining the effective mssage policy (obtaining the PolicyEngine, knowing which of its API methods to use and how to obtainaing the corresponding parameters for the call) but can simply pick up the AssertionInfoMap from the message and from that obtain a collection of assertions that they can understand.
Where the effective message policy is not known, not only the assertions for the selected altervive in the effective endpoint policy are made available to the message, but all assertions in assertion in all alternative of all of the operation and message specific policies as well. Not all of them will be asserted at the end of the chain, but that is fine if it turns out they do not actually apply to the undelying message - which at that point is known.

Verification