XFire

Home
Bug/Issue Reporting
Download
FAQ
Get Involved
License
News
Stack Comparison
Support
User's Guide
XFire Team

M5

Javadocs
Reports

M6-SNAPSHOT

Javadocs
Reports

Developers

Developer Space
CVS
Building
Architecture
Interesting Projects
Release Process

Handlers can be used to do all sorts of things with XFire. They can process the SOAP Body or they can process a particular header and take action based on it. To write a handler just extend the AbstractHandler class:

import org.codehaus.xfire.MessageContext;
import org.codehaus.xfire.handler.AbstractHandler;

public class YourHandler extends AbstractHandler
{
    public void invoke(MessageContext context)
    {
        // Do some processing...
    }
}

Handlers can be registered with a Service or a Transport. On both Services and Transports you can stick a handler in a request or response pipeline:

Servic s = ...;

// Do this to add a handler to the incoming flow
s.addInHandler(new YourHandler());

// Do this to add a handler to the outgoing flow
s.addOutHandler(new YourHandler());

// Do this to add a handler to the faultflow
s.addFaultHandler(new YourHandler());

Processing SOAP Headers

If you are using the "mustUnderstand" feature of SOAP you must tell XFire which QNames you can handle:

import org.codehaus.xfire.MessageContext;
import org.codehaus.xfire.handler.AbstractHandler;

public class YourHandler extends AbstractHandler
{
    ....
    public QName[] getUnderstoodHeaders()
    {
        return new QName[] { new QName("YourHeader", "urn:your:header:ns") };
    }
}

Writing an Authentication Handler

Often you will want to authenticate use of your service based on particular Headers in the SOAP Message. Say for example we have a header like the following:

<AuthenticationToken xmlns="urn:yourapp:authentication">
  <Username>test</Username>
  <Password>123</Password>
</AuthenticationToken>

We can easily write a Handler to process this information.

import org.codehaus.xfire.MessageContext;
import org.codehaus.xfire.handler.AbstractHandler;
import org.codehaus.yom.Element;

public class AuthenticationHandler extends AbstractHandler
{
    private final static String TOKEN_NS = "urn:yourapp:authentication";

    public void invoke(MessageContext context)
        throws XFireFault
    {
        if (context.getRequestHeader() == null)
        {
            throw new XFireFault("Request must include company authentication token.", 
                                 XFireFault.SENDER);
        }

        Element token = context.getRequestHeader().getFirstChildElement("AuthenticationToken", TOKEN_NS);
        if (token == null)
        {
            throw new XFireFault("Request must include authentication token.", 
                                 XFireFault.SENDER);
        }
        
        String username = token.getFirstChildElement("Username", TOKEN_NS).getValue();
        String password = token.getFirstChildElement("Password", TOKEN_NS).getValue();

        try
        {
            // Do some authentication....
            ....

            // we've authenticated, now put the Company object in the context
            context.setProperty(COMPANY_KEY, company);
        }
        catch (Exception e)
        {
            throw new XFireFault("Invalid username/password.", XFireFault.SENDER);
        }
    }
}