Re: Handling mustUnderstand Headers

From: Bobby Bissett - Javasoft <Robert.Bissett_at_Sun.COM>
Date: Tue, 07 Oct 2003 09:54:52 -0400

> This is an RI thing right?

Well, in a way: currently, our implementation supports SOAP 1.1, so the
only special actor is the "next" one. I think I misspoke earlier -- if
the attribute is left out of the message, then it is intended for the
ultimate recipient as you wrote. If actors are left out of the config
files when generating handlers, then the "next" actor is assumed for the
handlers. So it's always there for the handlers, but it's not assumed in
the message. (I think we're getting on track...)

> I guess what I wanted was to have a handler and
> the endpoint to act together as 'ultimate receiver', so that the handler
> handles the 'no actor' headers and the endpoint does the message
> processing.

Since the handler does get the entire message in the MessageContext
object, you can have your handler examine all the headers and process
them and just leave the body for the endpoint if you'd like. All of the
actor/role/mustUnderstand concepts are used for determining whether or
not processing should continue, but once the handler gets the message it
can play with the whole thing. As long as you're controlling both parts
of the server app (intermediaries and endpoint), you can make them work
together however you'd like.

> If I add a handler for a specific actor I need do
> nothing in the handler to remove any mustUnderstand headers so long as I
> explicitly return that header's QName from the getHeaders call,

Really, you should detach those elements as well according to the SOAP
spec if they're targeted at a header that says it understands them. It
just may be that there are cases where doing the wrong thing in a
handler (leaving "actor" header elements in the message) doesn't cause

> [in the context of response handlers being called for errors]
> Except that again the processing of 'actor' headers is different from
> 'next' headers. 'Actor' headers never even get into the processing
> chain if I have no handler declared as processing them.

Yes, my mistake about the targetting was confusing. "Actor" headers,
including headers targetted at the "next" actor, will definitely cause a
check to see if they are understood or not (when MU=1), but the whole
message is still sent into the handler chain. So even if nothing is
targeted at a handler chain, the message will still go through it (i.e.,
you may want your handlers to do something with the body of the message).

> It seems to me that the processing is inconsistent. What I think it
> should do (but what do I know) is this:

Or maybe just my email was inconsistent, heh heh. Here is what happens
when a message comes in and a handler chain exists. First, there is a
check to see if a MustUnderstand fault should be thrown. If not, then
the message is given to the handler chain. This isn't exactly how the
code is written, but here is the case that results in a fault:

A header element is explicitly targetted at some role, including the
"next" role, and it has mustUnderstand=1. If the chain includes this
role, and it does not understand this header type, then an fault is
thrown. If any of those conditions is not met, then the message is

In terms of code, the handler chain iterates through each of its roles,
makes a SOAPHeader.examineMustUnderstandHeaderElements(actor) call to
get headers, and checks them against the list of understood headers.
Sorry about the confusion I caused with where "next" pops up and where
it doesn't.

> This means that (logically)
> <handlerChains>
> <chain runAt="server" roles=" urn:uri" >
> <handler className="com.develop.SimpleHandler"/>
> </chain>
> <chain runAt="server" >
> <handler className="com.develop.SimpleHandler"/>
> </chain>
> </handlerChain>
> is the same as
> <handlerChains>
> <chain runAt="server" roles=" urn:uri
>" >
> <handler className="com.develop.SimpleHandler"/>
> </chain>
> </handlerChain>

Yes, *logically* speaking that is correct. Of course, the implementation
would throw an error that you have two chains on the server (I just want
to be explicit about that!), but setting the roles to "foo" would be the
same as setting them to both "foo" and "next" for the handler.

You may be right that the schema could be more correct, but the error
checking is done at the actual parsing stage instead of validating
against the schema. Though documented, the schema is still really more
of an internal document.