Page History

Wiki Markup
There are several steps involved in developing your domain specific assertions, these are:

...


# Implementing the Assertion and AssertionBuilder interfaces

...


# Registering the AssertionBuilder with the AssertionBuilderRegistry

...


# Providing runtime support for the Assertion - in form of an interceptor or inside a conduit or a destination.

...



They are outlined in some more detail below:

...



h2. Implementing the Assertion

...

Implementing the AssertionBuilder Interface

Registering the AssertionBuilder with the AssertionBuilderRegistry

Implementing a Policy-Aware Interceptor

This is the easiest way of providing runtime support for an Assertion, and essentially consist in steps 1. and 2. described in Interaction with the Framework:

Code Block

java

 Interface

You can chose to implement the Assertion interface from scratch, or decide to use or possible extend 
one of the existing Assertion impelementations:

h3. PrimitiveAssertion

This represents an assertion without any child elements (in particular a nested Policy element) or attributes, such as for example the AnonymousResponses or NonAnonymousResponses assertions in the addressing metadata namespace http://www.w3.org/2007/01/addressing/metadata . Its equal and normalize methods are trivial, and there should be no need to extend this class.

h3. NestedPrimitiveAssertion

This represents an assertion without any attributes, but with one mandatory nested Policy child, such as in the Addressing assertions in the addressing metadata namespace. Again, in the absence of attributes and child elements other than a nested Policy, there is no need to extend this class.

h3. JaxbAssertion<T>

This represents an assertion described by a schema (T is the mapped Java class). The RM assertion as well as the assertions used in the HTTP module are extensions of this class.
Although equal and normalize are not abstract, you probably want to overwrite these methods.

h2. Implementing the AssertionBuilder Interface

Building an Assertion of the corresponding type is quite straightforward (in the case of JaxbAssertions you can extend the JaxbAssertionBuilder: it takes care of creating a JAXB context etc.). The implementation of buildCompatible however needs some consideration if your assertion represents an element with attributes and/or child elements. 

h2. Registering the AssertionBuilder with the AssertionBuilderRegistry

Simply add a bean for your AssertionBuilder to the cxf-* file on your module, or the application's custom cfg file.

h2. Implementing a Policy-Aware Interceptor

This is the easiest way of providing runtime support for an Assertion. Steps 1. and 2. mentioned in [Interaction with the Framework|WS-Policy Framework Overview#Interaction with the Framework] can typically be coded as follows:
{code:java}
import org.apache.cxf.ws.policy.AssertionInfoMap;

class MyPolicyAwareInterceptor {
   static final QName assertionType = new QName("http://mycompany.com}", "MyType"});
   public void handleMessage(Message message) {

      // get AssertionInfoMap
       org.apache.cxf.ws.policy.AssertionInfoMap aim = message.get(org.apache.cxf.ws.policy.AssertionInfoMap.class);
       Collection<AssertionInfo ais> = aim.get(assertionType );

       // extract Assertion information
       for (AssertionInfo ai : ais) {
           org.apache.neethi.Assertion a = ai.getAssertion();
           MyAssertionType ma = (MyAssertionType)a;
          // digest ....
       }

       // process message ...
            // express support

       for (AssertionInfo ai : ais) {
           ai.setAsserted(...);
       }          }
}

...

{code} 

h2. Implementing a Policy-Aware Conduit/Destination

h3. Registering the Known Assertions Types

Your conduit/destination must make it known to the policy framework that it can support assertions of a certian type by implement the canAssert method from the Assertor interface:

class MyPolicyAwareConduit implements Assertor {
    static final QName MYTYPE = new QName("http://mycompany.com}", "MyType"});

    public boolean canAssert(QName name) {
        return MTYPE.equals(name);
    }
}

h3. Initialisation
Conduits/Destinations have access to the EndpointInfo object in their their constructors, and, assuming they have access to the bus also, can therefore at this point access the effective policy for the endpoint as follows:
{code:java}
class MyPolicyAwareConduit {
    static final QName assertionType = new QName("http://mycompany.com}", "MyType"});
    ...

    void init() {
        PolicyEngine engine = bus.getExtenation(PolicyEngine.class);
        if (null != engine && engine.isEnabled()) {
        EffectiveEndpointPolicy ep = engine.getEndpointPolicy(endpoint, this);
        Collection<Assertion> as = ep.getChosenAlternative();
        for (Assertion a : as) {
            if (assertType.equals(a.getName()) {
                // do something with it ...
            }
       }
       ... 
    }
}
{code}
and similarly for a Destination. 

h3. Policy-Aware Message Sending

In Conduit.send(Message message), the effective message policy is known. The conduit can obtain the assertions (in the chosen alternative of the effective message policy) from the message in the same way as an interceptor does. Moreover, the conduit can at the same time record whether or not if can actually support these assertions, but can also defer this until called upon by one of the verifying policy interceptors. 

h3. Supporting Assertions

As described in [Verification|How it works#Verification] Conduit and Destinations are asked at in the POST_STREAM or PRE_INVOKE phases by the verifying policy interceptors if they could support the assertions they understand. For this purpose, Conduit and Destination implement the assertMessage method from the Assertor interface. In the case of the HTTPConduit, which also has a data member that is of the same type as the (mapped Java class of the) assertion, all assertions chosen alternative of the message policy are supported provided their data is compatible with the this data member. On the inbound path, simply all HTTPClientPolicy assertions are asserted as effectively their sematics does not mandate any specific action on the inbound message.
Similary, on its inbound path,  the HTTPDestination asserts all HTTPServerPolicy assertions that are equal to the HTTPServerPolicy assertion configured for the destination, and all assertions of that thype on the outbound path.

Child pages

Versions Compared

Old Version 7

New Version 8

Key

Implementing the AssertionBuilder Interface

Registering the AssertionBuilder with the AssertionBuilderRegistry

Implementing a Policy-Aware Interceptor