Apache-SOAP User's FAQ

This FAQ is based on the questions and answers that appear on the Apache-SOAP User's Mailing List.
It is currently maintained by Jonathan Chawke, and was last modified on Sat 15-Mar-2003 12:27 GMT.
Corrections and suggestions for new questions are always welcome.

Hot Topics
This section answers questions that have been appearing frequently on the mailing list.
1.1  Help! I'm getting this error: "Element must contain a:'faultcode' element"
1.2  Help! I'm getting this error: "Unable to resolve namespace URI for 'xsd'".
1.3  Help! I'm getting this error: "Unable to resolve target object.." when I try to invoke a method on my SOAP service.
1.4  Help! I got this error message: "Fault String = org.w3c.dom.Node: method getNamespaceURI() java/lang/String; not found"
1.5  Help! The Samples won't work. Every time I run a sample client I get this response: "Fault String = java.lang.NoSuchMethodError"
1.6  Help! I'm getting this error: "Exception in thread "main" java.lang.NoSuchMethodError at org.apache.soap.util.xml.QName.<init>(QName.java:80)"
1.7  Help! I'm getting this error: "Exception in thread "main" java.lang.AbstractMethodError at org.apache.soap.util.xml.QName.<init>(QName.java:80)"
1.8  I think I have an XML parser library problem. How can I determine exactly which library is being used by Apache SOAP?
1.9  How can I view the 'raw' XML data that is exchanged between a SOAP client and server?
1.10  I can't get SOAP working with Tomcat 4 (Catalina). Help!
General
This section answers general questions.
2.1  Where can I get help on SOAP issue XYZ?
2.2  Where can I find mailing list archives for the soap-user mailing list?
2.3  I'm just getting started with SOAP. Where can I find a tutorial on SOAP programming?
2.4  Are there any other SOAP FAQs available?
2.5  Where can I download the SOAP specification document(s)?
2.6  Are there any good books on SOAP?
2.7  What other SOAP implementations are available?
2.8  What is meant by the phrase 'SOAP is a wire-level protocol'?
2.9  How does SOAP compare with other XML protocols?
2.10  How do I use TcpTunnel and TcpTunnelGUI?
2.11  How do I use SOAP over SSL?
2.12  How do I use SOAP over SMTP?
2.13  What products are available that will let me use ASP or Perl as SOAP client?
2.14  I'd like to write a SOAP client as a Java applet. Are there any 'tiny' SOAP client libraries I could use?
2.15  Where do I find nightly builds of the POP3 and SMTP beans?
2.18  Is there a way to generate SOAP stub/skeleton code from a deployment descriptor?
2.19  Is there a way to generate SOAP deployment descriptor from IDL?
2.20  Is there any way of specifying a timeout for a SOAP method invocation?
2.22  Are there any ISP's that will host SOAP applications?
2.24  Help! I got the following error message: "SOAP Service Manager: Unable to read 'DeployedServices.ds': assuming fresh start"
2.28  How do I tell my Apache SOAP client to use a proxy server?
2.29  How do I perform Proxy Authentication with my Apache SOAP client?
2.30  My Apache SOAP service needs to make connections to other Internet sites. How do I configure my SOAP service to use a proxy server?
2.31  Are there any commercially ready servlet containers which will support Apache SOAP clients ?
2.32  Where can I find a list of public SOAP services that are available on the Internet?
2.34  What tools are available that use Apache SOAP?
2.36  How do I restrict access to the Apache SOAP administration client?
2.38  How can I get the IP address of a client that is using my SOAP Service?
2.40  Can a client programmatically deploy a SOAP service?
2.41  I'd like to deploy multiple services using a single deployment descriptor file. Is this possible?
2.42  Will Apache SOAP support JAXM when it's ready?
2.43  Will Apache SOAP support JAX-RPC?
Installation
This section helps resolve questions which arise when installing Apache SOAP in a particular application server environment.
3.1  What jar files do I need to provide for Apache-SOAP clients?
3.2  How do I install Apache-SOAP on Tomcat 3.x?
3.3  Can I install Apache-SOAP 2.1 on Tomcat 4.0?
3.4  How do I install Apache-SOAP on Bea WebLogic 5.1?
3.5  How do I install Apache-SOAP on Bea WebLogic 6.0?
3.6  How do I install Apache-SOAP on Bea WebLogic 6.1 beta?
3.7  How do I install Apache-SOAP on Resin?
3.8  How do I install Apache-SOAP on IBM WebSphere?
3.9  How do I install Apache-SOAP on Bluestone?
3.10  How do I install Apache-SOAP on Orion?
3.11  How do I install Apache-SOAP on Apache-JServ?
3.12  How do I install Apache-SOAP on iPlanet Web Server?
3.13  How do I install Apache-SOAP on iPlanet Application Server?
3.14  How do I install Apache-SOAP on Unify's ServletExec?
3.16  How do I install Apache-SOAP on Oracle 8i Application Server?
3.18  How do I install Apache-SOAP on Borland Application Server (BAS) 4.5?
Troubleshooting
This section answers general troubleshooting queries.
4.2  Help! Visual Age can't compile SOAP - it says I'm missing package com.ibm.xmi.job.*
4.3  Help! My client sees error message: "SOAP-ENV:Server.BadTargetObjectURI"
4.5  Help! I try to run my SOAP client I get this message: "Unsupported response content type "text/html", must be: "text/xml". Response was: HTTP Error 405 - Method Not Allowed".
4.7  Help! I'm using Tomcat+SOAP on Linux. When I try to access the SOAP admin page, Tomcat crashes and I see this message: "HotSpot Virtual Machine Error, Unexpected Signal 11"
4.8  I am running the SOAP TunnelGui on Red Hat Linux 7.0. Sometimes the client hangs for the HTTP response to arrive. What's wrong?
4.9  Help! I just upgraded Apache-SOAP. When I run the service manager I get the following error: "javax.servlet.ServletException: Cannot create bean of class org.apache.soap.server.ServiceManager"
4.10  Help! Apache won't integrate with IIS: it says that the message content type should be text/xml but it is read as text/xml. What do I do?
4.11  Help! I'm getting this error: "java.io.InvalidClassException: org.apache.soap.server.DeploymentDescriptor; Local class not compatible"
4.13  I'm getting an error telling me that class 'XMLParserLiason' is not found. What is wrong?
4.14  Help! I'm getting this error message: "Unable to retrieve PropertyDescriptor for property 'checkMustUnderstands' of class 'class org.apache.soap.server.DeploymentDescriptor'.
4.15  Help! I'm getting this error: "BSF Error: Unable to load language: javascript". I'm using bsf 2.2 and js.jar from rhino14R3.zip.
4.17  Help! I'm getting this error: "Caught SOAPException <SOAP-ENV:Client>: Error opening socket:connection refused"
4.18  Help! I'm getting this error when I run one of the MIME samples: "Error parsing response: javax.mail.MessagingException: Missing start boundary"
4.19  Help! I'm getting this error: "java.lang.NoClassDefFoundError: javax/xml/transform/TransformerException"
4.20  I'm getting a segmentation fault when I try to run SOAP on Red Hat. What's wrong?
Design and Architecture Issues
This section aims to provide some opinions and suggestions on design and architecture issues.
5.2  Can a SOAP server maintain session between multiple client invocations?
5.3  What is an actor?
5.4  Can Apache-SOAP handle large (multiple megabyte) files?
5.5  What is the best way to send a large file (multiple megabytes) with a soap request?
5.6  How do I add a file attachment to a SOAP response using MIME?
5.9  Is it possible to pass parameters to the constructor in a SOAP application ?
5.10  How do I write a SOAP service that maintains state across a session?
5.12  Is it possible to perform more than one invocation in a single SOAP request?
5.13  I would like to write a SOAP service method that returns a DOM Document (org.w3c.dom.Document). How do I do this?
5.15  I would like to pass a DOM Element as a parameter to a method. How do I do this?
5.16  What is the performance difference (if any) between SOAP and RMI? Are there any benchmark test results available?
5.17  I am writing a SOAP service which returns a set of data. Is it better to return this data in an object, or as an XML data structure?
5.18  Are Apache SOAP calls synchronous or asynchronous?
5.19  What is the 'best' way of sending XML data using SOAP?
5.20  Does Apache SOAP use SAX or DOM for parsing/representation of XML?
5.21  How does SOAP compare with CORBA?
5.22  Is it possible to compress Apache SOAP data packets?
SOAP and Namespaces
This section discusses namespace issues.
6.1  What are all these SOAP Namespaces?
6.2  Do I need to use namespaces on my XML data?
6.3  What are all those namespace prefixes in my SOAP messages? Won't they keep validation from working?
SOAP and Serialization
This section discusses serialization issues.
7.1  How do I send user defined java objects using SOAP?
7.2  What are the different SOAP encoding styles? Which should I use?
7.3  How do you serialize java.util.Date objects?
7.7  How can I make a SOAP call which serializes both an xml literal and a string?
WSDL
This section answers Web Services Description Language (WSDL) questions.
8.1  Where can I find the WSDL specification document?
8.2  Does Apache SOAP use WSDL?
8.3  How can I generate a WSDL file for my SOAP service?
8.4  How can I generate Java code from an existing WSDL file?
8.5  Is there a command-line utility that I can use to generate WSDL stub and skeleton files?
8.6  Is there a tool that can validate WSDL?
8.7  Is there a command-line utility that I can use to generate a WSDL File?
8.8  Any one know is there any open source UDDI server implementation? (the UDDI4J server is locked into DB2)
8.9  Is there a tool that can be used to parse WSDL files?
8.10  Where should I place my WSDL files?
8.11  Where can I find out about how WSDL and UDDI work together?
8.12  Where can I find out more about UDDI?
8.13  The WSTK proxygen tool generates a class that requires a URL parameter in the constructor. What should I use?
8.14  Is there a simple tool which allows you to test a SOAP service using WSDL?
8.15  Is there a Java API for parsing and manipulating WSDL files?
SOAP and .NET
This section answers questions which arise when integrating with Microsoft's .NET platform.
9.1  Does Apache SOAP work with Microsoft SOAP?
9.2  How do I Access a Apache SOAP Service using a Microsoft SOAP (VB) Client?
9.3  How do I Access a Microsoft SOAP Service using an Apache SOAP Client?
9.4  Help! My Apache SOAP Client cannot connect to a .NET service - the server says it expects 'text/xml' and doesn't understand "text/xml; charset=utf-8".
9.5  Where can I find information about interoperating between an MS SOAP client and an Apache SOAP service?
9.6  How do I Access a Apache SOAP Service using a Microsoft .NET (Beta 2) Client?
9.7  Is there a mailing list for Microsoft SOAP users?
9.8  Where can I find an example of how to use the low-level MS SOAP API?
9.9  How do I maintain sessions between Apache-SOAP and MS SOAP?
9.10  How do I exchange complex types between Apache-SOAP and MS SOAP?

Questions and Answers

1. Hot Topics

1.1 Help! I'm getting this error: "Element must contain a:'faultcode' element"
This is probably due to a bug in some newer releases of Xerces (e.g. 1.3.1). Try using Xerces 1.4.3, 1.2.3 or 1.3.0 instead (on both the client AND the server) - have a look on http://xml.apache.org/dist/xerces-j/. You should also make sure that xerces.jar is the FIRST entry in your classpath.

1.2 Help! I'm getting this error: "Unable to resolve namespace URI for 'xsd'".
Ensure that:
(a) You are using Xerces 1.4.4, 1.4.3, 1.2.3 or 1.3.0 (but NOT 1.3.1) - on both the client and the server (if both are using Apache-SOAP).
(b) xerces.jar is the FIRST entry in your CLASSPATH, as described in the Apache-SOAP installation instructions.
(c) There is ONLY ONE version of xerces.jar in your CLASSPATH.
(d) There are no other XML parsers in your classpath. Some people have experienced this problem due to an early version of the JAXP package hiding in JAVA_HOME/jre/lib/ext.

1.3 Help! I'm getting this error: "Unable to resolve target object.." when I try to invoke a method on my SOAP service.
This is a classpath problem. Ensure that your SOAP service class is included in the classpath. For example, if your class is called HelloServer and it is in directory /foo/, then make sure that /foo/ is in your Tomcat classpath when it launches.

1.4 Help! I got this error message: "Fault String = org.w3c.dom.Node: method getNamespaceURI() java/lang/String; not found"
The most likely cause of this problem is a DOM level 1/level 2 issue.
SOAP uses DOM level 2, and you may have DOM level 1 classes (i.e. another XML parser library) included earlier in the classpath. People often find another XML parser hiding in JAVA_HOME\jre\lib\ext.
Ensure that:
(a) You are using Xerces 1.4.3, 1.2.3 or 1.3.0 (but NOT 1.3.1).
(b) xerces.jar is the FIRST entry in your CLASSPATH, as described in the Apache-SOAP installation instructions.
(c) There is ONLY ONE version of xerces.jar in your CLASSPATH.

1.5 Help! The Samples won't work. Every time I run a sample client I get this response: "Fault String = java.lang.NoSuchMethodError"
Ensure that:
(a) You have deployed the sample service you want to use.
(b) Xerces.jar is the very first entry in your classpath (set this in tomcat.bat or tomcat.sh as per the SOAP installation instructions).
(c) There are no other XML parsers in your classpath. Some people have experienced this problem due to an early version of the JAXP package hiding in JAVA_HOME/jre/lib/ext.
(d) The sample classes are in the server's CLASSPATH.

1.6 Help! I'm getting this error: "Exception in thread "main" java.lang.NoSuchMethodError at org.apache.soap.util.xml.QName.<init>(QName.java:80)"
The most likely cause of this problem is that you have more than one xml parser library (jar) in your classpath. Finding the other xml library can be tricky. Note that the JVM looks in two places BEFORE it looks at classpath. It finds "Bootstrap" classes and "Extension" classes first. $JAVA_HOME/jre/lib/ext is where the extension classes live.
People often find another XML parser hiding in JAVA_HOME\jre\lib\ext.
Libraries to look for include: xml.jar, xsltc.jar. The solution is to delete these jars (or move them to a directory that isn't included in the classpath).
Note also that JRun users got around this problem by adding the xerces jar to the JRun classpath in <jrun>/lib/global.properties:
jrun.classpath=c:/myjars/xerces.jar;..

1.7 Help! I'm getting this error: "Exception in thread "main" java.lang.AbstractMethodError at org.apache.soap.util.xml.QName.<init>(QName.java:80)"
See Question 1.6 above.

1.8 I think I have an XML parser library problem. How can I determine exactly which library is being used by Apache SOAP?
Matt Duftler has kindly provided a JSP page can tell you whether a JAXP-compliant parser is being found, what package the implementing classes of the org.w3c.dom interfaces are from, and whether the org.w3c.dom interfaces being resolved are namespace-aware. The JSP file is available here: http://marc.theaimsgroup.com/?l=soap-user&m=99669938017194&w=2. Note that SOAP 2.2 (or newer) is required.

1.9 How can I view the 'raw' XML data that is exchanged between a SOAP client and server?
There are a couple of tools which you can use to do this:
(1) TcpTunnel (textual interface) / TcpTunnelGui (graphical interface), which are both provided with the standard Apache SOAP distribution. See http://xml.apache.org/soap/faq/faq_chawke.html#Q2_10 for more information on how to use these tools.
(2) UtilSnoop, described as its author as 'somewhat more user friendly' than TcpTunnelGui. It's available at http://www.lanw.com/books/javasoap/.
(3) Iona's XMLBus product seems to include a similar tool called the 'SOAP Message Spy' - see http://www.xmlbus.com/work/.

1.10 I can't get SOAP working with Tomcat 4 (Catalina). Help!
You probably need to do two things:
(1) Modify your catalina.bat (or catalina.sh on Unix) file to include the soap libs in your classpath.
(2) Catalina's class loader operates different that Tomcat 3, so you need to put soap.jar in the WEB-INF of the application's directory under a 'lib' sub-dir.
For more detailed instructions, see here: http://marc.theaimsgroup.com/?l=soap-user&m=100802546024930&w=2.

2. General

2.1 Where can I get help on SOAP issue XYZ?
Try subscribing to the soap user mailing list on http://xml.apache.org/soap/mail.html, or searching the mailing list archives (see "Where can I find mailing list archives for the soap-user mailing list?" for more information).
You could also have a look at some other SOAP FAQs on this list: http://www.SoapRPC.com/faqs/.

2.2 Where can I find mailing list archives for the soap-user mailing list?
Try: http://marc.theaimsgroup.com/?l=soap-user&r=1&w=2 or: http://archive.covalent.net/.

2.3 I'm just getting started with SOAP. Where can I find a tutorial on SOAP programming?
Try these links:
http://www-106.ibm.com/developerworks/library/ws-peer2/
http://www.soapuser.com/client2.html
http://www.soapuser.com/server1.html
http://www.perfectxml.com/articles/xml/hellosoap.asp
http://www.soapwebservices.com/articles/what_is_soap.asp (shockwave flash presentation)
http://www.javapro.com/upload/free/features/javapro/2001/04apr01/prs0104/prs0104-1.asp
http://docs.pushtotest.com/ ('Additional resources' section)
http://www.soaplite.com/#LINKS
http://soap.manilasites.com/
http://www.xmethods.net/gettingstarted/apache.html

2.4 Are there any other SOAP FAQs available?
Yes, a list of FAQs is available here: http://www.SoapRPC.com/faqs/. You could also look at the SOAP FAQ maintained by Developmentor: http://www.develop.com/soap/soapfaq.htm.

2.5 Where can I download the SOAP specification document(s)?
SOAP 1.1 is here: http://www.w3.org/TR/SOAP.
There are also some other SOAP-related specs in this list: http://www.w3.org/TR/.

2.6 Are there any good books on SOAP?
See http://www.soaprpc.com/books/.

2.7 What other SOAP implementations are available?
A good list of SOAP implementations is available here: http://directory.google.com/Top/Computers/Programming/Internet/Web_Services/SOAP/Implementations/
and here: http://www.soap-wrc.com/webservices/default.asp
and here: http://www.soapware.org/directory/4/implementations

2.8 What is meant by the phrase 'SOAP is a wire-level protocol'?
A Wire level protocol is a protocol for Cross machine component interaction. DCOM, RMI and CORBA are popular wire level protocols. SOAP is a new technology which brings about cross machine, cross language and cross platform interoperability. You can learn more about this from the following sites:
http://www.w3.org/TR/SOAP/
http://www.javaworld.com/javaworld/jw-03-2001/jw-0330-soap.html
http://www.msdn.microsoft.com/soap

2.9 How does SOAP compare with other XML protocols?
See 'XML Protocol Comparisons', produced by the W3C: http://www.w3.org/2000/03/29-XML-protocol-matrix.

2.10 How do I use TcpTunnel and TcpTunnelGUI?
For a short answer, see http://marc.theaimsgroup.com/?l=soap-user&m=98628744413873&w=2. There is also a great article on IBM's developerWorks site: http://www-106.ibm.com/developerworks/webservices/library/ws-peer3/?dwzone=ws.

2.11 How do I use SOAP over SSL?
See the Apache-SOAP SSL FAQ: http://xml.apache.org/websrc/cvsweb.cgi/xml-soap/java/docs/install/FAQ_Tomcat_SOAP_SSL.html

2.12 How do I use SOAP over SMTP?
See the Apache-SOAP and SMTP FAQ, available at http://xml.apache.org/soap/faq/faq_chawke_smtp.html, and in the soap user mail archives: http://marc.theaimsgroup.com/?l=soap-user&m=98692249417026&q=p3.

2.13 What products are available that will let me use ASP or Perl as SOAP client?
See http://www.soap-wrc.com/webservices/default.asp and also http://www.soaprpc.com/software for lists of SOAP libs/packages. A popular Perl implementation is SOAP::Lite - available at http://www.soaplite.com/.

2.14 I'd like to write a SOAP client as a Java applet. Are there any 'tiny' SOAP client libraries I could use?
Consider using SoapRMI for your client. It is 183KB (including full XML parser) and is available here: http://www.extreme.indiana.edu/soap/rmi/download/. For more details about its design, see: http://www.extreme.indiana.edu/soap/.
You could also consider using IBM's 'Web Services Development Environment' http://www.alphaworks.ibm.com/tech/wsde (warning: it is a big download). Among other things, it will automatically generate WSDL files from any java class or COM object, create a browser-based client, and deploy your services to Websphere or Apache.
Also have a look at KSoap - a small-footprint SOAP lib for J2ME: http://ksoap.enhydra.org/index.html.
Systinet (formerly Idoox) also provide a JavaScript-based SOAP implementation that enables you to invoke a SOAP request from a browser. The JavaScript support is included in WASP Lite. You can download it from http://www.systinet.com/download.html.

2.15 Where do I find nightly builds of the POP3 and SMTP beans?
You'll find them here: http://www.alphaworks.ibm.com/ab.nsf/.

2.18 Is there a way to generate SOAP stub/skeleton code from a deployment descriptor?
Yes, you can use the IBM alphawork WSTK toolkit: http://www.alphaworks.ibm.com/tech/webservicestoolkit.

2.19 Is there a way to generate SOAP deployment descriptor from IDL?
It might make more sense to transform IDL to WSDL; otherwise you will lose information regarding the syntax of method calls if you directly use the SOAP deployment descriptor.

2.20 Is there any way of specifying a timeout for a SOAP method invocation?
In Apache-SOAP version 2.1 you can set a timeout on the client side by using:
SOAPHTTPConnection shc;
shc = new SOAPHTTPConnection();
shc.setTimeout(5000); //<-- 5 seconds
Call call = new Call();

call.setSOAPTransport(shc);

2.22 Are there any ISP's that will host SOAP applications?
We haven't heard of any yet, but there _are_ ISPs that host servlets and JSP pages, so it's probably just a matter of time:
- http://www.servlets.com/isps/
- http://www.adrenalinegroup.com/jwsisp.html

2.24 Help! I got the following error message: "SOAP Service Manager: Unable to read 'DeployedServices.ds': assuming fresh start"
This message will appear the first time you run SOAP, as the file does not exist and needs to be created for the first time. Don't worry - it is just a warning, not an error.

2.28 How do I tell my Apache SOAP client to use a proxy server?
Here is some sample code to do this:
SOAPHTTPConnection connection = new SOAPHTTPConnection();
connection.setProxyHost("proxy");
connection.setProxyPort(8080);
Call call = new Call(); // prepare the service invocation
call.setSOAPTransport(conn); // use the proxy

2.29 How do I perform Proxy Authentication with my Apache SOAP client?
See the sample code in the weather service client - it shows how to do proxy authentication. Here is some sample code too:
SOAPHTTPConnection connection = new SOAPHTTPConnection();
connection.setProxyHost("proxy");
connection.setProxyPort(8080);
setProxyUserName("username");
setProxyPassword("password");

2.30 My Apache SOAP service needs to make connections to other Internet sites. How do I configure my SOAP service to use a proxy server?
There are at least two ways of doing this:
(1) Dynamically modify your system properties at execution time:
Properties prop = System.getProperties();
prop.put("http.proxyHost","yourProxy.com");
prop.put("http.proxyPort","80");

(2) Let TOMCAT do the proxying for you. If you are using Tomcat as a servlet engine, you can set the environment variable TOMCAT_OPTS as follows:
For a HTTP Proxy:
set TOMCAT_OPTS="-DProxyHost=your.proxy.server -DproxyPort=8080"
For a SOCKS Proxy:
set TOMCAT_OPTS="-DsocksProxyHost=your.socks.server -DsocksProxyPort=1080"

2.31 Are there any commercially ready servlet containers which will support Apache SOAP clients ?
Yes, here is a (probably incomplete) list (in no particular order) of servlet containers that various SOAP-users have used to host Apache-SOAP services:
- Bea WebLogic 6.0 at http://www.bea.com/
- Resin at http://www.caucho.com/
- IBM WebSphere at http://www-4.ibm.com/software/webservers/
- HP Bluestone at http://www.bluestone.com/
- Orion at http://www.orionserver.com/
- iPlanet Application Server at http://www.iplanet.com/
- Borland Application Server at http://www.borland.com/
- ServletExec from Unify at http://www.unify.com/
Note that we are not endorsing any of the above commercial products - just reporting what people have mentioned on the soap-users mailing list. Note that in most cases, a little bit of tweaking is required to get Apache-SOAP working under a given application server.
The good news is that in most (if not all) cases, these teething problems have already been resolved by other SOAP users. See Section 3 of this FAQ for more information.

2.32 Where can I find a list of public SOAP services that are available on the Internet?
Salcentral maintain a searchable list of web services here: http://www.salcentral.com/.
Xmethods have a list here as well: http://www.xmethods.net/.

2.34 What tools are available that use Apache SOAP?
Brought to you by the same folks that brought you UDDI, is the Web Services Definition Language. WSDL is an XML schema that defines documents, in XML format, that describe SOAP services. There is an IBM alphaWorks toolkit that generates Java service client libraries and service handler skeletons from a WSDL document. See the WSDL specification (http://www-106.ibm.com/developerworks/library/w-wsdl.html), and the IBM toolkit (http://www.alphaworks.ibm.com/tech/webservicestoolkit).

2.36 How do I restrict access to the Apache SOAP administration client?
There are a number of possible solutions (none of which are perfect):
- Modify your servlet container's security settings so that only certain IP addresses can access the admin page. If you are running Tomcat with its security manager, you can add an entry for the soap webapp in the .policy file located in the conf directory, and then you can control which IP addresses the webapp will accept connections from.
- Modify the code - see http://soap.manilasites.com/stories/storyReader$13
- Modify your firewall configuration. Some firewalls can filter on URLs, and you could use this to prevent accesses to the admin page (although this wouldn't prevent someone from running the ServiceManagerClient directly).

2.38 How can I get the IP address of a client that is using my SOAP Service?
If you add a SOAPContext Object as first Parameter in the signature of your SOAP-service java-method, a 'SOAPContext' Object is passed to your class, e.g.:
.mymethod(SOAPContext inContext, String inString)

This SOAPContext object gives you access to the HttpSession, HttpRequest, HttpResponse (see java doc for details).
So, your SOAP service method can get the servlet request out of the context object, and then call the getRemoteAddr() method on the service request object:

import javax.servlet.http.*;
....
HttpServletRequest req =
(HttpServletRequest)soapCtx.getProperty(org.apache.soap.Constants.BAG_HTTPSERVLETREQUEST);
String remoteIPAddress = req.getRemoteAddr();

NOTE: this will only work where the client and server are both using the Apache SOAP libraries.

2.40 Can a client programmatically deploy a SOAP service?
Yes, you can do this using org.apache.soap.util.ConfigManager. Have a look here: http://xml.apache.org/soap/docs/apiDocs/org/apache/soap/util/ConfigManager.html#deploy(org.apache.soap.server.DeploymentDescriptor).
Remember that to deploy a service, the service classes must already exist in the classpath on the server. All you are doing here is configuring Apache-SOAP so that it knows about your service.

2.41 I'd like to deploy multiple services using a single deployment descriptor file. Is this possible?
Yes, it is. Have a look here: http://marc.theaimsgroup.com/?l=soap-user&m=100109136124059&w=2.

2.42 Will Apache SOAP support JAXM when it's ready?
There are no plans at present to support JAXM (http://java.sun.com/xml/jaxm/) in Apache SOAP. However, there are plans to provide JAXM support in Axis (http://ws.apache.org/axis/).

2.43 Will Apache SOAP support JAX-RPC?
There are no plans at present to support JAX-RPC (http://java.sun.com/xml/jaxrpc/) in Apache SOAP. However, the Axis (http://ws.apache.org/axis/) developers report that Axis is already moving towards full compliance with the current JAX-RPC draft spec.

3. Installation

3.1 What jar files do I need to provide for Apache-SOAP clients?
For an Apache-SOAP 2.2 deployment, you will need to include the following jars:
- xerces.jar
- soap.jar
- mail.jar
- activation.jar
The Apache-SOAP client-side dependencies are described in more detail on the web-site, in the "Installation" section, under the "Client-Side Instructions" heading. See http://xml.apache.org/soap/docs/ for this information.

3.2 How do I install Apache-SOAP on Tomcat 3.x?
Follow the instructions that are included with the Apache-SOAP distribution. Make sure that you read the instructions carefully as there are a bunch of 'gotchas'.
Xmethods have a good tutorial which includes setup information: http://www.xmethods.net/gettingstarted/apache.html

3.3 Can I install Apache-SOAP 2.1 on Tomcat 4.0?
Catalina (Tomcat 4) uses a different class loading model to the tomcat 3.* series, so if you follow the Tomcat instructions in the soap distribution, when the soap web application is loaded it will not be able to find org.apache.soap.* or the SAX classes needed. However, it should work if you put xerces.jar and soap.jar into the lib directory under WEB-INF under your web application. One SOAP user has provided a detailed description of their working configuration here: http://marc.theaimsgroup.com/?l=soap-user&m=100199111401559&w=2.
Another user (Tom Myers) reports that 'SOAP 2.2 seems to work fine in Tomcat 4.0.1 without touching the catalina.bat startup file; just put your jar files, soap.jar, etc., into your [path-to-catalina]/common/lib
directory'.

3.4 How do I install Apache-SOAP on Bea WebLogic 5.1?
Dion Almaer has written an article about this and it has been included in the distribution. See http://xml.apache.org/websrc/cvsweb.cgi/xml-soap/java/docs/install/weblogic51.html.

3.5 How do I install Apache-SOAP on Bea WebLogic 6.0?
Dion Almaer has written an article about this: http://www.almaer.com/weblogic60.html. There are some additional comments here: http://marc.theaimsgroup.com/?l=soap-user&m=98808422428291&w=2.

3.6 How do I install Apache-SOAP on Bea WebLogic 6.1 beta?
It seems to be more or less the same process as that used for WebLogic 6.0, but there are some (new) gotchas related to JAXP. See http://xml.apache.org/soap/faq/faq-for-WL6.1beta.html [note: when WebLogic 6.1 is released, we will merge this FAQ with the Apache SOAP install docs] and http://marc.theaimsgroup.com/?l=soap-user&m=99270271408539&w=2.

3.7 How do I install Apache-SOAP on Resin?
Under Resin 1.2.3, configure a web app to point to the soap webapp directory (i.e.<path-to-apache-soap>/webapps/soap). See also http://marc.theaimsgroup.com/?l=soap-user&m=99650513909887&w=2.

3.8 How do I install Apache-SOAP on IBM WebSphere?
Apache SOAP has worked under every version of WebSphere from 1.1 to 3.02. It will work out of the box on WebSphere 3.5 with fixpak 2 applied. Wouter Cloetens has provided instructions on using Apache-SOAP with IBM Websphere v1, v2, and v3.0 on http://workspot.net/~zombie/soap/. There are also instructions for WebSphere v3.5 in the Apache-SOAP distribution - see http://xml.apache.org/websrc/cvsweb.cgi/~checkout~/xml-soap/java/docs/install/websphere.html?rev=1.1&content-type=text/html&only_with_tag=MAIN.
Be sure to check the following items:
1. Explicitly set the port number that you have exposed the rpcrouter servlet on. Even if it is default(80), just mention it in the URL as http://aaa.bbb.ccc.ddd:port/soap/servlet/rpcrouter.
2. Verify that xerces is at the start of your path not only by setting it in the App but also in the websphere configuration files (admin.config, setupclient.bat).

3.9 How do I install Apache-SOAP on Bluestone?
The Bluestone people provide a download with instructions and samples: http://gallery.bluestone.com/scripts/SaISAPI.dll/Gallery.class/techDownloads/index.jsp

3.10 How do I install Apache-SOAP on Orion?
Have a look here: http://marc.theaimsgroup.com/?l=soap-dev&m=97678072329144&r=p3.

3.11 How do I install Apache-SOAP on Apache-JServ?
Here are some instructions: http://marc.theaimsgroup.com/?l=soap-user&m=98890652006035&w=2.

3.12 How do I install Apache-SOAP on iPlanet Web Server?
See Erik Onnen's article here: http://marc.theaimsgroup.com/?l=soap-user&m=98753020626284&r=p3.

3.13 How do I install Apache-SOAP on iPlanet Application Server?
See the instructions on the iPlanet.com web site:
http://developer.iplanet.com/appserver/samples/soap/docs/index.html

3.14 How do I install Apache-SOAP on Unify's ServletExec?
See http://marc.theaimsgroup.com/?l=soap-user&m=97741067209680&w=2.

3.16 How do I install Apache-SOAP on Oracle 8i Application Server?
According to the Oracle folks, SOAP should work under the latest production release of Oracle 8i, which is Oracle 8.1.7. Earlier releases of Oracle 8i (e.g 8.1.6) seem to be more awkward: the JVM bundled with 8.1.6 has a bug that affects Xerces. See here for more information: http://marc.theaimsgroup.com/?l=soap-user&m=98200304522497&w=2.

3.18 How do I install Apache-SOAP on Borland Application Server (BAS) 4.5?
Installation of SOAP on BAS 4.5 is done in 3 steps:
1) Deploy the [soap install dir]/webapps/soap.war using the deploy tool.
2) Edit "[BAS451 install dir]\var\servers\[server name]\adm\properties\ias.config" and add a line like "addpath [xerces install dir]/xerces.jar" at the end of the modifiable section.
3) Add the required libraries either in the appserver or in the webcontainer.

See http://marc.theaimsgroup.com/?l=soap-user&m=99728307503567&w=2. Thanks to
Laurent Letellier and Colin Mondesir for this information.

4. Troubleshooting

4.2 Help! Visual Age can't compile SOAP - it says I'm missing package com.ibm.xmi.job.*
These classes can be downloaded from http://www.alphaworks.ibm.com/aw.nsf/textformula/bc977085639b0fb888256a10006. The missing package is a xmisoap.jar, which contains the following files:
com.ibm.xmi.framework.*
com.ibm.xmi.job.*
com.ibm.xmi.utility.*

4.3 Help! My client sees error message: "SOAP-ENV:Server.BadTargetObjectURI"
The most likely cause of this problem is a classpath error: The class file that implements your service is not in the classpath of
the server.

4.5 Help! I try to run my SOAP client I get this message: "Unsupported response content type "text/html", must be: "text/xml". Response was: HTTP Error 405 - Method Not Allowed".
Check that your client is connecting to port 8080 (i.e. http://localhost:8080/ rather than http://localhost/). You might accidentally be connecting to a web server (e.g. Apache or IIS) instead of your SOAP/Tomcat server.

4.7 Help! I'm using Tomcat+SOAP on Linux. When I try to access the SOAP admin page, Tomcat crashes and I see this message: "HotSpot Virtual Machine Error, Unexpected Signal 11"
This may be related to a JDK 1.3 bug on Linux; try
- Using JDK 1.2
- Using the -server or -client option on the JDK 1.3 JVM

4.8 I am running the SOAP TunnelGui on Red Hat Linux 7.0. Sometimes the client hangs for the HTTP response to arrive. What's wrong?
This problem is due to a combination of the Sun JDK you are using and the glibc packages installed in 7.0. Redhat has a patch for glibc which solves this problem (as well as a ton of others). Here is the
advisory and update: http://www.redhat.com/support/errata/RHBA-2000-079.html.
You should also make sure that the JVM is using the classic
compiler each time. Do this by editing a file called jvm.cfg and
making sure classic is the first available option for the VM. This file
is in $JAVA_HOME/jre/lib.
You might also consider switching to the IBM or Blackdown JDK if you continue to have problems.

4.9 Help! I just upgraded Apache-SOAP. When I run the service manager I get the following error: "javax.servlet.ServletException: Cannot create bean of class org.apache.soap.server.ServiceManager"
Delete the JSP work files that were stored by your JSP server, so that they are re-generated using the new SOAP classes. In the case of tomcat, these should be in a directory that looks like this: $TOMCAT_HOME/work/localhost_8080/%2Fsoap.

4.10 Help! Apache won't integrate with IIS: it says that the message content type should be text/xml but it is read as text/xml. What do I do?
This problem occurs because IIS sends this data:
Content-Type:text/xml; charset=utf-8
But Apache-SOAP sends this data:
Content-Type: text/xml; charset=utf-8
(Note the space after 'Content-Type').
The problem has been fixed - upgrade to v2.2 or later of Apache-SOAP and it should go away.

4.11 Help! I'm getting this error: "java.io.InvalidClassException: org.apache.soap.server.DeploymentDescriptor; Local class not compatible"
The most likely cause of this problem is that you upgraded your JVM. A class that is serialized can only be deserialized with the same version of the JVM. Re-deploy your services using your new JVM and the problem should be solved.

4.13 I'm getting an error telling me that class 'XMLParserLiason' is not found. What is wrong?
The 'org.apache.xalan.xpath.xml.XMLParserLiason' class used to be part of Apache SOAP, but it was discarded when Apache SOAP was made JAXP-compliant (in releases after v2.1). The problem is probably occurring because you are running old code (possibly an old sample?) against a newer version of Apache-SOAP.

4.14 Help! I'm getting this error message: "Unable to retrieve PropertyDescriptor for property 'checkMustUnderstands' of class 'class org.apache.soap.server.DeploymentDescriptor'.
Try using a later version of Xerces such as 1.4 (you're probably using 1.2.* or 1.3.1) and see if the problem goes away. Also, make sure that you have removed all previous versions of Apache SOAP from your classpath.

4.15 Help! I'm getting this error: "BSF Error: Unable to load language: javascript". I'm using bsf 2.2 and js.jar from rhino14R3.zip.
This is a result of a code change that the Mozilla folks made which is not backward-compatible. You have two options:
(a) Upgrade to Rhino 1.5.
(b) Re-compile BSF against rhino14R3. The compiler will flag a line of code - remove the last parameter from the function call on this line and the problem should go away.

4.17 Help! I'm getting this error: "Caught SOAPException <SOAP-ENV:Client>: Error opening socket:connection refused"
The problem is caused by one of the following:
(a) Your SOAP client isn't specifying the right port in the service URL, e.g. It is using http://localhost:80/soap/servlet/rpcrouter but the SOAP service router is listening on port 8080 (i.e. http://localhost:8080/soap/servlet/rpcrouter ).
(b) Your SOAP client isn't specifying the right path in the service URL, e.g. it is using http://localhost:8080/rpcrouter instead of http://localhost:8080/soap/servlet/rpcrouter.
(c) Your application server/servlet container (e.g. Tomcat) isn't running.
(d) If you are using Apache-SOAP in conjunction with a web server (e.g. Apache or IIS), ensure that the web server is also running.

4.18 Help! I'm getting this error when I run one of the MIME samples: "Error parsing response: javax.mail.MessagingException: Missing start boundary"
Ensure that you have added activation.jar and mail.jar to your classpath.
This exception can also be caused by an incorrect HTTP Post Content-Type header. For attachments it should look like this:
Content-Type: multipart/related; boundary=MIME_boundary; type=text/xml; start=some-content-id
If you receive Content-Type: multipart/related then MimeMultipart.parse() hunts for the boundary --null

4.19 Help! I'm getting this error: "java.lang.NoClassDefFoundError: javax/xml/transform/TransformerException"
The javax.xml.transform.TransformerException class is in the xalan library - see http://xml.apache.org/xalan-j/index.html. Ensure that xalan.jar is in your SOAP server's classpath. If you're using an XSLT library other than xalan, make sure the jar defines javax.xml.transform.TransformerException.

4.20 I'm getting a segmentation fault when I try to run SOAP on Red Hat. What's wrong?
Take a look at http://java.sun.com/j2se/1.3/jre/install-linux.html. It describes a bug in java that causes a segmentation fault. The glibc-2.2x libraries don't correctly handle initial stack sizes larger than 6Mb.
There is a workaround: Use "ulimit -s 2048" in bash shell or "limit stacksize 2048" in tcsh to limit the initial thread stack to 2 MB.

5. Design and Architecture Issues

5.2 Can a SOAP server maintain session between multiple client invocations?
Yes! Client-side cookie support was added to Apache SOAP by Sanjiva with the addition of the setMaintainSession function to the SOAPHTTPConnectionclass:
shc = new SOAPHTTPConnection ();
shc.setMaintainSession( true ); // NEW FUNCTION!!
call.setSOAPTransport( shc );
Check out the latest code from CVS and have a look atthe AddressBook2 sample for more details(you'll need to at least get the latest Call.java and SOAPHTTOConnection.java from CVS).
Note that session timeouts can be configured in the servlet container. In the case of Tomcat, this is configured in the SOAP entry in web.xml.

5.3 What is an actor?
Every SOAP message has a primary intended recipient. An actor is a different message recipient that may recieve the message, and possibly modify it, before forwarding it on to either the next actor or the final, intended recipient.
SOAP allows 'Header' entries to be addressed to specific actors with the 'SOAP-ENV:actor' attribute. This attribute contains the URI that uniquely identifies the actor.

5.4 Can Apache-SOAP handle large (multiple megabyte) files?
Yes. People on the soap-user mailing have reported that they have been able to successfully transfer files of up to 20Mb in size using Apache-SOAP.

5.5 What is the best way to send a large file (multiple megabytes) with a soap request?
As a MIME attachment. Note that this will use a lot of memory, because in the current Apache-SOAP implementation, the entire file is read into memory before it is sent. See http://xml.apache.org/soap/docs/guide/attachments.html for more information.

5.6 How do I add a file attachment to a SOAP response using MIME?
See
(a) The documentation - http://xml.apache.org/soap/docs/guide/attachments.html and
(b) The code in the 'mime' folder in the Apache SOAP 'samples' directory.

5.9 Is it possible to pass parameters to the constructor in a SOAP application ?
No, unfortunately it isn't. The SOAP server requires that you have a public no-argument constructor - this is what used to create an instance of your target service provider.
An alternative to parameter passing is to load the information you need from a property file, or to set each parameter after object instantiation.

5.10 How do I write a SOAP service that maintains state across a session?
Both the client and the server have to be modified to use maintain state across a session:

(a) Setting the scope to "Session" tells the server-side to store the target object in the context of the session. You do this in the deployment descriptor (scope="Session").

(b) The client side needs to be told to return the cookies that help the maintain sessions:
// Build the call.
Call call = new Call();
// We require the session to be maintained
SOAPHTTPConnection conn = new SOAPHTTPConnection();
conn.setMaintainSession(true);
call.setSOAPTransport(conn);

See the samples.addressbook2.Main sample code for a detailed example of how to do this.

5.12 Is it possible to perform more than one invocation in a single SOAP request?
No. SOAP v1.1 (see http://www.w3.org/TR/SOAP/), which is what Apache SOAP implements, does not allow that.

5.13 I would like to write a SOAP service method that returns a DOM Document (org.w3c.dom.Document). How do I do this?
You need to return a DOM Element rather than a Document, and you need to specify the use of Literal XML encoding for the return value. The encoding style of a Call return is determined by the encoding style of the Request. DOM Elements use Literal XML encoding. For example, if a service accepts one String Parameter and returns an Element, just set the encoding style for the call to "http://xml.apache.org/xml-soap/literalxml" and the encoding style for the parameter to "http://schemas.xmlsoap.org/soap/encoding". Thus, part of your client code would look like:
...
Call call = new Call();
call.setTargetObjectURI("urn:someservice");
call.setMethodName("callmethod");
call.setEncodingStyleURI( Constants.NS_URI_LITERAL_XML );
String strparam = "joebob";

Vector params = new Vector();
params.addElement( new Parameter( "strparam", String.class,
strparam, Constants.NS_URI_SOAP_ENC ) );

See the GetAllListings() method in the Addressbook sample for a more detailed example of how to control the return encoding style.

5.15 I would like to pass a DOM Element as a parameter to a method. How do I do this?
Try:
params.addElement(new Parameter("name", Element.class, root,
Constants.NS_URI_LITERAL_XML) );
Where
- 'name' is the name of the parameter expected by the SOAP service method.
- 'root' is an object of type 'Element'.

5.16 What is the performance difference (if any) between SOAP and RMI? Are there any benchmark test results available?
There aren't any official benchmark test results available, but some ad hoc testing by SOAP users suggests that RMI is about 5 times faster than an unoptimized SOAP implementation. The XML parser is considered to be the bottleneck in Apache SOAP.
Bear in mind that:
- Apache SOAP implementations will be optimized in the future, and RMI probably won't.
- The common expectation is that eventually, SOAP implementations will provide performance that is comparable to RMI.
- RMI is Java only, SOAP isn't.

5.17 I am writing a SOAP service which returns a set of data. Is it better to return this data in an object, or as an XML data structure?
If the clients consuming the SOAP service are all written in Java, then it is probably easier to return objects. Otherwise you should probably return your data as XML (i.e. as DOM Elements).

5.18 Are Apache SOAP calls synchronous or asynchronous?
If you're using the HTTP transport then the calls are synchronous. If you're using the SMTP transport then calls are asynchronous. A number of people have discussed the need to provide one-way calls over HTTP - see http://marc.theaimsgroup.com/?l=soap-user&w=2&r=1&s=one-way&r=b.

5.19 What is the 'best' way of sending XML data using SOAP?
Unfortunately there isn't a definitive answer (not yet anyway!).
But here's a brief summary of the options:
(a) Send the XML as a string (works ok until the string gets large, at which point performance really degrades)
(b) Send the XML in the body of the Envelope (you need to marshall and unmarshall the data)
(c) Send the XML as an attachment inside a message (you don't need to worry about serialisation or marshalling). See the MIME sample SOAP application for details on how to use attachments.

For more information, have a browse through the archives: http://marc.theaimsgroup.com/?l=soap-user&w=2&r=1&s=Best+way+to+send+XML&r=b.

5.20 Does Apache SOAP use SAX or DOM for parsing/representation of XML?
Apache SOAP uses DOM. Axis, the next generation of Apache SOAP, is based on SAX (and performs significantly better as a result). See here for more information: http://ws.apache.org/axis/.

5.21 How does SOAP compare with CORBA?
See this article on IBM developerWorks: http://www-106.ibm.com/developerworks/webservices/library/ws-arc3/

5.22 Is it possible to compress Apache SOAP data packets?
Neither the SOAP standard (http://www.w3.org/TR/SOAP/), nor the standard distribution of Apache SOAP provide support for compression. However, a number of Apache SOAP users have suggested extensions that might allow data compression. See for example, Robert Schmitt's comments and code: http://marc.theaimsgroup.com/?l=soap-user&m=100229134130643&w=2.

6. SOAP and Namespaces

6.1 What are all these SOAP Namespaces?
SOAP uses a few different namespaces for different elements and attributes depending on the role that the data item in question plays in the message formatting, handling and/or encoding. Looking at the Envelope element of a typical SOAP message, we see the following namespace declarations:
1. xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
2. xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
3. xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
4. xmlns:xsd="http://www.w3.org/1999/XMLSchema"

where 1) is the SOAP Envelope namespace, 2) is the SOAP Encoding namespace, 3) is the XML Schema Instance namespace and 4) is the XML Schema Definition namespace. SOAP defines the first two namespaces and refers to the second two. These namespaces reflect how all data type definitions in SOAP are delegated to XML Schema.
The SOAP Envelope namespace defines the 'Envelope', 'Header' and 'Body' element names and the 'encodingStyle', 'actor' and 'mustUnderstand' attributes.
The SOAP Encoding namespace defines the 'Array' element and the 'arrayType' attribute used to encode 'Vector' and 'Array' java objects. This encoding technique is recommended for any linear list of objects - i.e. Java 2 'Collection' objects can and probably should use this encoding approach.

The XML Schema Instance namespace defines the 'type' attribute, which identifies the data type of an element.

The XML Schema namespace defines several datatypes used as values of the 'xsi:type' attribute. Examples include: 'int', 'String', 'double', and 'ur-type'.

6.2 Do I need to use namespaces on my XML data?
The short answer is yes, but only a little.
The long answer is that the serialization registry is necessarily based on qualified names. Thus, if you are marshalling/unmarshalling Java objects into XML Elements, those element names will have to be namespace qualified.
Although it is technically possible to just use one of the SOAP namespaces, it probably isn't a good idea unless the element name is actually defined in that namespace (i.e. defined by the SOAP specification - see http://www.w3.org/TR/SOAP).
If you already have one or more namespaces, use them. If you need to generate a new namespace, use something like urn://acmecorp.com/whatever/ as the URI when you register an element name. See Serialization below.

6.3 What are all those namespace prefixes in my SOAP messages? Won't they keep validation from working?
The Apache-SOAP library will generate namespace prefixes as needed to make sure that all necessary namespaces are declared. If the same namespace gets declared twice with two different prefixes, the qualified names should still match with any namespace aware software. A qualified name is the combination of the namespace URI plus the local part of the element name (the part after the prefix).
SOAP-ENV:Envelope
...xmlns:acme="urn://acmecorp.com/namespace"...
...
ns3:GetData xmlns:ns3="urn://acmecorp.com/namespace"
/ns3:GetData
...

In this example, the prefix can be "ns3" or "acme". Either way, it refers to the same namespace and, thus, for any local name, the same element or attribute.

7. SOAP and Serialization

7.1 How do I send user defined java objects using SOAP?
You need to map the Java object to a SOAP XML Element name. This is done using an XMLJavaMappingRegistry. Typically, you'll want to use the derived class SOAPMappingRegistry which, among other things, supports primitive types, Array and Vector objects, and the ability to be configured via an XML file (DeploymentDescriptor.xml).

Although not required by the SOAP specification, the Apache library requires that all XML Elements be namespace qualified via the QName utility class. You can use (almost) anything for the QName. You might think of the first piece as a "path", and the second piece as a "SOAP object." You might want to use something like the following:
SOAPMappingRegistry smr = new SOAPMappingRegistry();
MyObjectSerialzier myObjSer = new MyObjectSerialzier();
smr.mapTypes( Constants.NS_URI_SOAP_ENC,
new QName("urn://myown.com/objects/", "MyObject"),
Object.class, myObjSer, myObjSer );

Then, when you deploy the service that you are calling, you must have a mapping entry that looks something like the following:
isd:map encodingStyle = "http://schemas.xmlsoap.org/soap/encoding/"
xmlns:x="urn://myown.com/objects/" qname="x:MyObject"
javaType="com.myown.objects.MyObject"
java2XMLClassName="com.myown.soap.MyObjectSerializer"
xml2JavaClassName="com.myown.soap.MyObjectSerializer"/

On the server side, all of this (the deployment map) basically says that when you have a com.myown.objects.POBean object to return to the caller, you want the SOAP server to use the bean serializer to translate it into a "urn://myown.com/objects/MyObject" SOAP object and send it to the client.

One the client side, all of this (the mapTypes() method) says that when you get a SOAP "urn://myown.com/objects/MyObject" object from the SOAP server, you would like to use the serializer called myObjSer to translate the SOAP object into a Java MyObject object.

The main thing you have to do is make sure that the xmlns and qname values in your deployment descriptor file (or their equivalents in the GUI) match the values you use in your QName object.

Note, that it is often not necessary to write your own Serializer or Deserializer. If your class has a get and a set for each attribute that needs to be marshalled, you can just use the Apache SOAP BeanSerializer class.

7.2 What are the different SOAP encoding styles? Which should I use?
The Apache SOAP library uses the 'SOAP-ENV:encodingStyle' attribute as a lookup qualifier when locating a Serializer for a Java object or a Deserializer for an XML element.
The SOAP specification allows the 'encodingStyle' attribute to hold multiple URIs which denote increasingly general encoding rules. What isn't defined, however, is how a SOAP processor is to determine which encoding style to apply. Consequently, the Apache SOAP library does not support this syntax and will always treat the encodingStyle attribute value as a single URI reference.
1. SOAP Encoding: This encoding style is identified by the SOAP Encoding URI http://schemas.xmlsoap.org/soap/encoding/ and is described fully in Section 5 of the SOAP specification.
2. XMI Encoding
3. Literal XML Encoding

7.3 How do you serialize java.util.Date objects?
Use BeanSerializer. Either add a mapping for date in the deployment xml file or call SOAPMappingRegistry.mapTypes() in your application. A more "correct" DateSerializer is planned that serializes using the ISO date format.
Date objects should be converted to xsd:date (http://www.w3.org/TR/xmlschema-2/#date) or xsd:timeInstant (http://www.w3.org/TR/xmlschema-2/#timeInstant) to be SOAP compliant.
The SOAP spec says, "For simple types, SOAP adopts all the types found in the section Built-in datatypes of the XML Schema Part 2: Datatypes", (http://www.w3.org/TR/SOAP/#_Toc478383514), but not all have been implemented

7.7 How can I make a SOAP call which serializes both an xml literal and a string?
You need to set different encoding styles for your parameters.
Consider the addressbook client parameter creation:
params.addElement(new Parameter("nameToLookup", String.class,
nameToLookup, null));
That Parameter constructor has the following signature:
Parameter(String name, Class type, Object value, String encodingStyleURI);

The last argument doesn't have to be null - you can set it to something like Constants.NS_URI_SOAP_ENC or Constants.NS_URI_LITERAL_XML.

8. WSDL

8.1 Where can I find the WSDL specification document?
The WSDL specification document is available at http://www.w3.org/TR/wsdl.

8.2 Does Apache SOAP use WSDL?
A WSDL document does not actually get used directly by the Apache SOAP API in any way. It is simply an XML grammer that allows non-Apache SOAP client applications to discover the methods and classes available in a SOAP service.

8.3 How can I generate a WSDL file for my SOAP service?
You can use IBM web services toolkit - WSTK - (class
com.ibm.wstk.swrapper.ui.SWrapperGUI) on http://www.alphaworks.ibm.com/tech/wsde, or IBM Web services development environment on http://www.ibm.com/developerworks/webservices.

You could also consider using GLUE, which includes a command line tool for static generation of WSDL: http://www.themindelectric.com/.

The Apache AXIS folks are also working on a tool called java2wsdl. See http://ws.apache.org/axis/ for more information.

SilverStream now provide a product called jBrokerWeb which includes compilers to convert WSDL to Java and vice versa. See http://extend.silverstream.com/workbench/app/jsp/jbrokerweb.jsp for more information.

8.4 How can I generate Java code from an existing WSDL file?
WASP from Systinet (formerly Idoox) includes a tool called WSDLCompiler. It is able to generate Java and JavaScript code from WSDL 1.1. It is available at http://www.systinet.com/ from The Mind Electric includes a tool called 'wsdl2java' which also does this. See http://www.themindelectric.com/.

8.5 Is there a command-line utility that I can use to generate WSDL stub and skeleton files?
Yes - the IBM web services toolkit (http://www.ibm.com/developerworks/webservices/) includes a command-line java application that should do what you want:
.com.ibm.wsdl.Main -?
Note that:
(a) It is in the wsdl.jar library.
(b) Passing in '-?' (without the apostrophes) gets you a list of available commands that the class supports.

8.6 Is there a tool that can validate WSDL?
Yes: Simon Fell has written a Schematron-based validator for SOAP oriented WSDL documents. See here: http://www.pocketsoap.com/wsdl/. Note that the current version only checks the relationships between the various parts of the WSDL, it doesn't really check anything in the schema sections yet. A couple of folks on the schematron mailing list are working on some XSD checking code, and it will be added to the validator when its done.

8.7 Is there a command-line utility that I can use to generate a WSDL File?
Yes - the IBM web services toolkit (WSTK) 2.3 (http://www.ibm.com/developerworks/webservices/) includes a utility called 'wsdlgen'. It is in WSTK_HOME/bin.
See also the Open Source WSDL4J project on http://oss.software.ibm.com/developerworks/projects/wsdl4j/.

8.8 Any one know is there any open source UDDI server implementation? (the UDDI4J server is locked into DB2)
Have a look at the following:
- Systinet (formerly Idoox) WASP http://www.systinet.com/ (not open source, uses JDBC)
- The Mind Electric GLUE http://www.themindelectric.com (not open source, uses JDBC)
- jUUDI, on sourceforge at http://sourceforge.net/projects/uddi/. It's relatively young (i.e. the current release is an alpha), but SOAP users report that the guy running the project is very helpful, and that it looks like the code runs off whichever db platform you want. Ensure you get the code from CVS, not the (tarball) release.
- pUDDIng at http://www.opensorcerer.org/ (UDDI v2.0 on Oracle). The author is talking about adding support for other database platforms.

8.9 Is there a tool that can be used to parse WSDL files?
Yes, IBM have one. The Web Services Description Language for Java Toolkit (WSDL4J) allows the creation, representation, and manipulation of WSDL documents describing services. See http://oss.software.ibm.com/developerworks/projects/wsdl4j/.

8.10 Where should I place my WSDL files?
Put the files in a directory on your web server, and make them available to SOAP clients. Don't forget that to put them in a location where SOAP clients have adequate permissions to download them (you can use your web browser to test downloading/viewing the WSDL file).

8.11 Where can I find out about how WSDL and UDDI work together?
Have a look here: http://www.uddi.org/bestpractices.html

8.12 Where can I find out more about UDDI?
Have a look here: http://www.uddi.org/whitepapers.html

8.13 The WSTK proxygen tool generates a class that requires a URL parameter in the constructor. What should I use?
I'm using the "proxygen" tool in IBM WSTK 2.4 to generate client proxy code from a WSDL file. My problem is that the proxy class it generates requires a URL parameter in the constructor. But I want to create the proxy for an implementation, so the URL should be included in the class. How do I do this?
The generated proxy class has a static field
public static java.net.URL[] _KnownServiceLocations;
In the constructor all known locations found in WSDL will be added to this field. So when you create the proxy object, use the first element of _KnownServiceLocations as the URL.

8.14 Is there a simple tool which allows you to test a SOAP service using WSDL?
Yes, there is a very nice (and freely downloadable) Java application (with GUI) which can generate and interactively test WSDL. For more information, see http://www.sics.se/~hamfors/.

8.15 Is there a Java API for parsing and manipulating WSDL files?
Yes. Anne Thomas Manes reports that there's a new Java API in the works called JWSDL (JSR 110 - see http://www.jcp.org/jsr/detail/110.jsp). It's based on the WSDL4J API developed by IBM. You can obtain a preliminary implementation of JWSDL from IBM (it's part of the WSTK).
Systinet (formerly Idoox) also includes a JWSDL library. You can download Systinet's SOAP implementation (WASP), which includes full support for WSDL, from http://www.systinet.com/.

9. SOAP and .NET

9.1 Does Apache SOAP work with Microsoft SOAP?
Yes, but with a number of 'gotchas'. You need to install a patch to the MS SOAP package. One of the well-known interoperability problems between Apache 2.0 and MS Soap is that MS clients do not send type information with each parameter, and the Apache soap server will reject such requests.
Microsoft now have a useful resource page for interoperability (including articles specifically discussing integration with Apache SOAP): http://www.msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsrvspec/html/globalxmlwebsrvinterop.asp?frame=true.
James Snell has provided a patch adding the typing. It can be found at SOAP-WRC web site (http://www.soap-wrc.com/apache_ms_soap_interop.zip).
Both Apache and Microsoft are working hard to ensure interoperability between their SOAP implementations (in case you don't believe us, have a look here: http://marc.theaimsgroup.com/?l=soap-user&m=98505313219298&w=2).
There are other problems with SOAP interoperability (in general) which are discussed here: http://www-106.ibm.com/developerworks/webservices/library/ws-inter.html.

9.2 How do I Access a Apache SOAP Service using a Microsoft SOAP (VB) Client?
See http://marc.theaimsgroup.com/?l=soap-user&m=98683038702626&w=2.

9.3 How do I Access a Microsoft SOAP Service using an Apache SOAP Client?
See http://support.microsoft.com/directory/article.asp?id=q307279

9.4 Help! My Apache SOAP Client cannot connect to a .NET service - the server says it expects 'text/xml' and doesn't understand "text/xml; charset=utf-8".
There is also a kludgy workaround to allow an Apache-SOAP client to send the request with just "text/xml" in the Content-Type header. See some of the examples, e.g. samples/xmethods/GetTemp.java.
SOAP users have also commented that if you upgrade to MSSoap toolkit 2.0 beta2 (or even rc0), this problem seems to go away.

9.5 Where can I find information about interoperating between an MS SOAP client and an Apache SOAP service?
Have a look here:
http://xml.apache.org/soap/docs/guide/interop.html
http://www-106.ibm.com/developerworks/library/ws-ref3/?n-ws-5241
http://www.perfectxml.com/articles/xml/soapguide.asp

9.6 How do I Access a Apache SOAP Service using a Microsoft .NET (Beta 2) Client?
Microsoft have a 'How To' document here:
http://support.microsoft.com/directory/article.asp?id=q307324.
See also http://support.microsoft.com/directory/article.asp?id=q307318

9.7 Is there a mailing list for Microsoft SOAP users?
The best place for support on the MS toolkits is probably the MS newsgroups:
- microsoft.public.xml.soap
- microsoft.public.xml.soapsdk

9.8 Where can I find an example of how to use the low-level MS SOAP API?
Here is a tutorial which shows how to write a SOAP client using the MS SOAP low-level API: http://www.soapuser.com/client4.html

9.9 How do I maintain sessions between Apache-SOAP and MS SOAP?
Unfortunately, the SOAP specifications don't say anything about session maintenance, so each implementor has done something different. MS-Soap maintains sessions through the 'IHeaderHandler' interface. Apache-SOAP uses cookies.
Currently MS-Soap and Apache Soap are not interoperable as far as session maintenance is concerned this is because unlike Apache SOAP, MS-SOAP does not allow you to set cookies in the HTTP header.

9.10 How do I exchange complex types between Apache-SOAP and MS SOAP?
The Castor XML tool (http://www.castor.org) is one way of doing this. Andrew Fawcett of CODA was kind enough to make some sample code available on the Castor web site: http://www.castor.org/presentations.html.

PDF

Copyright © 1999-2003 The Apache Software Foundation. All rights reserved.

Apache-SOAP User's FAQ