cxf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache CXF Documentation > WS-Policy Framework Overview
Date Wed, 06 Apr 2011 17:57:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=CXF20DOC&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/CXF20DOC/WS-Policy+Framework+Overview">WS-Policy
Framework Overview</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~dkulp">Daniel
Kulp</a>
    </h4>
        <br/>
                         <h4>Changes (7)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-unchanged" >The WS-Policy framework provides infrastructure
and APIs that allow CXF users and developers to use WS-Policy.  <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">It
is compliant with the November 2006 draft publications of the [Web Services Policy 1.5 - Framework|http://www.w3.org/TR/2006/WD-ws-policy-20061117/]
and  <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">It
is compliant with the [Web Services Policy 1.5 - Framework|http://www.w3.org/TR/2007/REC-ws-policy-20070904/]
and  <br></td></tr>
            <tr><td class="diff-changed-lines" >[Web Services Policy 1.5 - <span
class="diff-deleted-words"style="color:#999;background-color:#fdd;text-decoration:line-through;">Attachment|http://www.w3.org/TR/2006/WD-ws-policy-attach-20061117/]</span>
<span class="diff-added-words"style="background-color: #dfd;">Attachment|http://www.w3.org/TR/2007/REC-ws-policy-attach-20070904/]</span>
specifications. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>The framework consists
of a core runtime and APIs that allow developers to plug in support for their own domain assertions:
<br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >* verification that one of the effective
policy&#39;s alternatives is indeed supported. <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">Policy
operations such as merge and normalisation (but not intersection) are based on [Apache Neethi|http://ws.apache.org/commons/neethi/index.html].
<br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">Policy
operations such as merge, normalisation, and intersection are based on [Apache Neethi|http://ws.apache.org/commons/neethi/index.html].
<br></td></tr>
            <tr><td class="diff-unchanged" > <br>h2. APIs <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" >h3. AssertionBuilder <br> <br></td></tr>
            <tr><td class="diff-deleted-lines" style="color:#999;background-color:#fdd;text-decoration:line-through;">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. <br>{code:java} <br>public interface AssertionBuilder { <br>
  // build an Assertion object from a given DOM element <br>   Assertion build(Element
element); <br>  // return the schema type names of assertions understood by this builder
<br>  Collection&lt;QName&gt; getSupportedTypes(); <br>  // return an
Assertion object that is compatible with the specified assertions <br>  Assertion buildCompatible(Assertion
a, Assertion b); <br>} <br>{code} <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">The
AssertionBuilder API is an interface from Neethi. <br></td></tr>
            <tr><td class="diff-unchanged" > <br>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: <br></td></tr>
            <tr><td class="diff-snipped" >...<br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <p>The WS-Policy framework provides infrastructure and APIs that allow CXF users
and developers to use WS-Policy. </p>

<p>It is compliant with the <a href="http://www.w3.org/TR/2007/REC-ws-policy-20070904/"
class="external-link" rel="nofollow">Web Services Policy 1.5 - Framework</a> and
<br/>
<a href="http://www.w3.org/TR/2007/REC-ws-policy-attach-20070904/" class="external-link"
rel="nofollow">Web Services Policy 1.5 - Attachment</a> specifications.</p>

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

<h2><a name="WS-PolicyFrameworkOverview-Core"></a>Core</h2>

<p>The core is responsible for:</p>

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


<p>Policy operations such as merge, normalisation, and intersection are based on <a
href="http://ws.apache.org/commons/neethi/index.html" class="external-link" rel="nofollow">Apache
Neethi</a>.</p>

<h2><a name="WS-PolicyFrameworkOverview-APIs"></a>APIs</h2>

<h3><a name="WS-PolicyFrameworkOverview-AssertionBuilder"></a>AssertionBuilder</h3>

<p>The AssertionBuilder API is an interface from Neethi.</p>

<p>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:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
{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
</pre>
</div></div>
<p>along with the <a href="/confluence/display/CXF20DOC/WS-SecurityPolicy" title="WS-SecurityPolicy">WS&#45;SecurityPolicy</a>
defined assertions.</p>

<p>They are all based on generic Assertion implementations (PrimitiveAssertion, NestedPrimitiveAssertion,
JaxbAssertion) that developers can parameterize or extend when developing their own assertions,
see <a href="/confluence/display/CXF20DOC/Developing+Assertions" title="Developing Assertions">Developing
Assertions</a>.</p>

<h3><a name="WS-PolicyFrameworkOverview-PolicyInterceptorProvider"></a>PolicyInterceptorProvider</h3>

<p>This API is used to automatically engage interceptors required to support domain
specific assertions at runtime, thus simplifying interceptor configuration a lot.</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> <span class="code-keyword">interface</span>
PolicyInterceptorProvider <span class="code-keyword">extends</span> InterceptorProvider
{
  <span class="code-comment">// <span class="code-keyword">return</span>
the schema types of the asssertions that can be supported
</span>  Collection&lt;QName&gt; getAssertionTypes()
}
</pre>
</div></div>
<p>Currently, CXF supports PolicyInterceptorProvider implementations for the following
assertion types:</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-xml">
{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
</pre>
</div></div>
<p>along with the <a href="/confluence/display/CXF20DOC/WS-SecurityPolicy" title="WS-SecurityPolicy">WS&#45;SecurityPolicy</a>
defined assertions.</p>

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

<h2><a name="WS-PolicyFrameworkOverview-InteractionwiththeFramework"></a>Interaction
with the Framework</h2>

<p>Components interact with the policy framework mainly in order to:</p>
<ol>
	<li>retrieve the assertions pertaining to the underlying message (at least the ones
known to the component) so the component can operate on the message accordingly</li>
	<li>confirm that the assertions pertaining to the underlying message are indeed supported.</li>
</ol>


<p>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: </p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">import</span> org.apache.neethi.Assertion;

<span class="code-keyword">public</span> class AssertionInfo {
  ...
  <span class="code-keyword">public</span> <span class="code-object">boolean</span>
isAsserted() {...}
  <span class="code-keyword">public</span> void setAsserted(<span class="code-object">boolean</span>
asserted) {...}
  <span class="code-keyword">public</span> Assertion getAssertion() {...}
}
</pre>
</div></div>

<p>The WS-Addressing and WS-RM interceptors are examples for this style of intercation.
 </p>

<p>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: <br/>
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. <br/>
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.</p>

<p>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.):</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java"> 
<span class="code-keyword">public</span> <span class="code-keyword">interface</span>
PolicyEngine {
    ...
    EndpointPolicy getClientEndpointPolicy(EndpointInfo ei, 
        Conduit conduit);    
    EndpointPolicy getServerEndpointPolicy(EndpointInfo ei, 
        Destination destination); 
}

<span class="code-keyword">public</span> <span class="code-keyword">interface</span>
EndpointPolicy {
    ...
    Policy getPolicy(); 
    Collection&lt;Assertion&gt; getChosenAlternative();
}
</pre>
</div></div>

<p>To perform step 2. they implement the Assertor interface (namely its assertMessage
method):</p>
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<pre class="code-java">
<span class="code-keyword">public</span> class Assertor {
  ...
  <span class="code-keyword">public</span> <span class="code-object">boolean</span>
canAssert(QName name);
  <span class="code-keyword">public</span> void assertMessage(Message message);
}
</pre>
</div></div> 

<p>An example for policy aware conduits and destinations in CXF are the HTTP conduit
and destination. They do support assertions of element type HTTPClientPolicy and HTTPServerPolicy
respectively.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/WS-Policy+Framework+Overview">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=51291&revisedVersion=16&originalVersion=15">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/CXF20DOC/WS-Policy+Framework+Overview?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message