This document explains the changes you may have to make to migrate from Apache SOAP v2.1 to Apache SOAP v2.2.
We previously used a home grown solution for achieving XML parser independence. However, given the release of a Java standard mechanism for doing that, we have now switched over to using JAXP. What does this mean for you? It means that if you had any code that used XMLParserLiaison then you will have to change that code. Luckily, the changes are simple: the differences between v1.2 and v1.3 of the "messaging" sample, shows you exactly what to do!
Sometimes this change may show up even if you don't have any code that directly uses XMLParserLiaison. If you are seeing that, please recompile your code with the v2.2 jar in your classpath and the problem should go away.
We now support maintaining HTTP sessions. The "addressbook2" sample shows an example of how to use it.
The session support is on by default. If you were interacting with any "session" scoped HTTP services with a certain behavior, you may now see a different behavior as the code now correctly maintains HTTP sessions. If you want to turn off HTTP session support, you need to create your own SOAPHTTPConnection object, set the sesssion maintenance property to false and set the transport propert of the call to that SOAPHTTPConnection:
Call call = new Call (); SOAPHTTPConnection shc = new SOAPHTTPConnection (); shc.setMaintainSession (false); call.setSOAPTransport (shc); // now make calls with "call"
Having session support on the client side finally means that Apache SOAP can be used to implement stateful Web services without having user intervention to manage that.
A common question with Apache SOAP v2.1 was how an RPC service author could access "environmental" information such as the HTTPSession object or HTTP headers. The v2.1 answer was that you had to write a custom provider to do that. As of v2.2, there's a better, simpler way.
The RPCJavaProvider (the provider that runs all RPC style services) now has the following behavior: when searching for the method in the target class to call to process the service request, if a method with a matching signature is not found, then a second search is done. The second search looks for a method with an additional (first) argument of type org.apache.soap.rpc.SOAPContext (please see the API docs for the details of that class). If found, then an instance of SOAPContext is passed to the service handler class.
Having access to the incoming SOAPContext gives you a lot of freedom: you can access the following via the "getProperty" method:
If the original SOAP request was in the SOAP Attachments form, then you can get at unreferenced MIME parts using the "getBodyPart" methods.
NOTE: SOAPContext is a read-only object: do not use any of the set<FOO> methods!
NOTE: Using this feature makes your service implementation class bound to Apache SOAP. Use it with care!
If you are running into other migration issues please check the FAQs at http://xml.apache.org/soap/faq.