Geertjan's Blog

  • December 5, 2005

Soap Must Understand?! Aaaaaargh!

Geertjan Wielenga
Product Manager
While rewriting a Sun Education course ("DWS-4487: Developing Secure Java Web Services") to use NetBeans IDE, I must've come across every single unparseably bizarre error that the tiny warped minds of developers have conceived of. The one that takes the cake, as far as I'm concerned, is this one:

Exception in thread "main" javax.xml.rpc.soap.SOAPFaultException: SOAP must understand error
at com.sun.xml.rpc.client.StreamingSender._raiseFault(StreamingSender.java:528)
at com.sun.xml.rpc.client.StreamingSender._send(StreamingSender.java:307)
at auctionsystem.client.AddAuctionUserServiceSEI_Stub.addUser(AddAuctionUserServiceSEI_Stub.java:79)
at auctionsystem.client.AddAuctionUserClient.main(Unknown Source)
Java Result: 1
BUILD SUCCESSFUL (total time: 4 seconds)

You see what it says?! "SOAP must understand error". How on earth is one to know what that means? The answer is simple and immediate—Google. That's where I spent many many hours, until I came across this response, by my web service colleague Rico Cruz (who, with his colleague Peter Williams, helped out the NetBeans J2EE team a lot in the 4.1 release, by providing web service functionality, in co-operation with other developers here in Prague). The thing with Google is that you can really be led up the garden path (and never find your way back), which is what I did a couple of times, but this is Rico's advice:

The SOAP "must understand" error may be indicative of an unhandled SOAP security header at the receiving end (i.e. the web service). Make sure that you have configured the SOAP message handlers at web service end correctly.

I confess that I spent a while avoiding this solution. ("Configure a SOAP message handler? Really? Sounds tough." I thought.) But then I got stuck in and remembered my earlier praise song to message handlers (here). Using the New Message Handler wizard, I generated the template code, and then added this little snippet (googled from elsewhere):

if(shd != null){
Iterator iter = shd.extractAllHeaderElements();
SOAPHeaderElement el = (SOAPHeaderElement)iter.next();
System.out.println("Extracted header: " + el.getElementName().getQualifiedName());

What's important is the "extractAllHeaderElements()" method. This detaches the element objects from the SOAP header which, apparently, is exactly what is needed when you're using web service security mechanisms such as those provided by <xwss:Sign> elements and <xwss:Encrypt> elements. Once I'd added the snippet above to the generated message handler, and configured it to insert it in all the web services involved in the security framework, the "SOAP must understand" error disappeared.

Join the discussion

Comments ( 7 )
  • A. Sundararajan Monday, December 5, 2005
    May be, the developer could have used "mustUnderstand" (the same way as used in the spec.) rather than "must understand"??
  • Geertjan Monday, December 5, 2005
    That would have helped... but even then, its quite a jump from there to extracting the header via a message handler. To me, the most useful error message would have been: "Unable to extract header."
  • Mythili Wednesday, April 5, 2006
    I have the exact same problem and adding the handler made the error go away. However, I am not sure this is the right solution. All this message handler is doing is throwing away the WS-Security headers at the receiving end(web service end). Is this what we want to do? I thought the mesage handler would get added implicitly (when you do the wscompile -security and provide the SecurityEnvironmentHandler) and also do the correct SOAP header handling. We should not have to provide this handler ourselves. But for some reason, the wscompile is not producing the right handler. Comments?
  • Geertjan Wednesday, April 5, 2006
    Hi Mythili, yeah, it's weird. Maybe an issue should be created somewhere for this.
  • Geertjan Monday, April 10, 2006
    By the way, I didn't know that wscompile could create a handler for you.
  • Mario Wednesday, June 11, 2008

    I am trying to get around this. As Myrthili said, the problem with adding the MessageHandler is that you are simply ignoring the error. If you're signing the message then you don't check the signature (though things seem to "just work" nothing is happening). However, if you're encrypting the message content the message becomes illegible on the server side (unless of course your MessageHandler decrypts it). Have you not found another solution? (And no, the answer isn't "use JAX-WS", since I am currently TEACHING the DWS-4487 to a customer that's still running on AppServer 8)

  • Java Developer Tuesday, February 3, 2009

    How to add MessageHandler to solve "Must Understand" error?

Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.