Page History

...

• Service
• Endpoint
• Operation
• Message

Note that subjects do not correspond to wsdl elements directly. Rather, they map to a set of wsdl elements that are used to compute the effective policy for a subject (see below). For example wsdl:port, wsdl:portType and wsdl:binding elements together describe the endpoint as a subject.

Using WSDL 1.1, the policy-subject association usually takes the form of xml element attachment, i.e. : a wsp:Policy (or wsp:PolicyReference) element, with wsp as prefix for 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, is ). Similary, wsp:PolicyReference elements can be attached to a WSDL element such as wsdl:port (in case of a PolicyReference the actual policy wsdl element. In that case, the actual wsp:policy element may reside outside of the wsdl).
Alternatively, policies can be attached to their subjects by external attachment, i.e. by means of wsdpNote 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.

The location of documents containing PolicyAttachment documents however on the other hand needs to be made known to the framework. You can do this This can easily be done through configuration:

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

The location of the document containing PolicyAttachments is specified in the form of a classpath resource or URL. You can specifify any Any number of external attachment providers can be specified.

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:

...

Now that the framework knows where to look for wsp:Policy and wsp:PolicyReference elements, 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 identifies the element as an assertionare 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.

Note that multiple sources can be used to supply policies applying to the same subject. In the case of the endpoint subject for example, the wsdl:port element may have multiple wsp:Policy child elements. An additional external provider may contain multiple wsp:PolicyAttachment elements in which the AppliesTo children identify the underlying endpoint as the target subject. Both the Policies attached to the port element as well as that appear in the matching PolicyAttachment elements will contribute to the effective policy of the endpoint subject.

Althoguh it would not be the normal use case, it is important to keep in mind that this complex aggregation process makes it possible for an effective policy to have multiple assertion elements of the same type in the same alternative. It is NOT the case that these different assertions overwrite each other. These may or may not be compatible with each other - a decision that cannot be made by the framework alone but which needs the involvement of the assertion builder.

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