jechawke 01/07/04 06:56:18 Modified: targets/soap/faq faq_chawke.html Log: Added some new faq entries, made some minor corrections, added some new topics. Revision Changes Path 1.4 +118 -76 xml-site/targets/soap/faq/faq_chawke.html Index: faq_chawke.html =================================================================== RCS file: /home/cvs/xml-site/targets/soap/faq/faq_chawke.html,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- faq_chawke.html 2001/06/20 22:37:27 1.3 +++ faq_chawke.html 2001/07/04 13:56:16 1.4 @@ -11,7 +11,7 @@ </HEAD> <BODY LINK="#0000ff" VLINK="#800080"> <H1>Apache-SOAP User's FAQ</H1> -This FAQ is based on the questions and answers that appear on the <a href="http://xml.apache.org/soap/mail.html";>Apache-SOAP User's Mailing List</a>.<br> It is currently maintained by <A HREF="mailto:[EMAIL PROTECTED]">Jonathan Chawke</A>, and was last modified on Wed 20-Jun-2001 11:24PM GMT. +This FAQ is based on the questions and answers that appear on the <a href="http://xml.apache.org/soap/mail.html";>Apache-SOAP User's Mailing List</a>.<br> It is currently maintained by <A HREF="mailto:[EMAIL PROTECTED]">Jonathan Chawke</A>, and was last modified on Wed 04-Jul-2001 01:55PM GMT. <br>Corrections and suggestions for new questions are always welcome. <H1><A NAME="toc">Table of Contents</A></H1><OL><LI><H2>Hot Topics</H2>1.1 <A HREF="#Q1_1">Help! I'm getting this error: "Element must contain a:'faultcode' element"</A><br> 1.2 <A HREF="#Q1_2">Help! I'm getting this error: "Unable to resolve namespace URI for 'xsd'".</A><br> @@ -33,52 +33,66 @@ 2.13 <A HREF="#Q2_13">What products are available that will let me use ASP or Perl as SOAP client?</A><br> 2.14 <A HREF="#Q2_14">I'd like to write a SOAP client as a Java applet. Are there any 'tiny' SOAP client libraries I could use?</A><br> 2.15 <A HREF="#Q2_15">Where do I find nightly builds of the POP3 and SMTP beans?</A><br> -2.16 <A HREF="#Q2_16">Can a SOAP server maintain session between multiple client invocations?</A><br> -2.18 <A HREF="#Q2_18">Is there a way to generate SOAP stub/skeleton from deployment descriptor?</A><br> +2.18 <A HREF="#Q2_18">Is there a way to generate SOAP stub/skeleton code from a deployment descriptor?</A><br> 2.19 <A HREF="#Q2_19">Is there a way to generate SOAP deployment descriptor from IDL?</A><br> 2.20 <A HREF="#Q2_20">Is there any way of specifying a timeout for a SOAP method invocation?</A><br> -2.21 <A HREF="#Q2_21">Can Apache-SOAP handle large (multiple megabyte) files?</A><br> -2.22 <A HREF="#Q2_22">What is the best way to send a large file (multiple megabytes) with a soap request?</A><br> +2.22 <A HREF="#Q2_22">Are there any ISP's that will host SOAP applications?</A><br> 2.24 <A HREF="#Q2_24">Help! I got the following error message: "SOAP Service Manager: Unable to read 'DeployedServices.ds': assuming fresh start"</A><br> -2.26 <A HREF="#Q2_26">Is it possible to pass parameters to the constructor in a SOAP application ?</A><br> -2.27 <A HREF="#Q2_27">How do I write a SOAP service that maintains state across a session?</A><br> 2.28 <A HREF="#Q2_28">How do I tell my Apache SOAP client to use a proxy server?</A><br> 2.29 <A HREF="#Q2_29">How do I perform Proxy Authentication with my Apache SOAP client?</A><br> +2.31 <A HREF="#Q2_31">Are there any commercially ready servlet containers which will support Apache SOAP clients ?</A><br> 2.32 <A HREF="#Q2_32">Where can I find a list of public SOAP services that are available on the Internet?</A><br> 2.34 <A HREF="#Q2_34">What tools are available that use Apache SOAP?</A><br> -2.35 <A HREF="#Q2_35">What is an actor?</A><br> <br></LI><LI><H2>Installation</H2>3.1 <A HREF="#Q3_1">What jar files do I need to provide for Apache-SOAP clients?</A><br> 3.2 <A HREF="#Q3_2">How do I install Apache-SOAP on Tomcat?</A><br> 3.3 <A HREF="#Q3_3">Can I install Apache-SOAP 2.1 on Tomcat 4.0 beta?</A><br> -3.4 <A HREF="#Q3_4">How do I install Apache-SOAP on Bea WebLogic 6.0?</A><br> -3.5 <A HREF="#Q3_5">How do I install Apache-SOAP on Bea WebLogic 6.1 beta?</A><br> -3.6 <A HREF="#Q3_6">How do I install Apache-SOAP on Resin?</A><br> -3.7 <A HREF="#Q3_7">How do I install Apache-SOAP on IBM WebSphere?</A><br> -3.8 <A HREF="#Q3_8">How do I install Apache-SOAP on Bluestone?</A><br> -3.9 <A HREF="#Q3_9">How do I install Apache-SOAP on Orion?</A><br> -3.10 <A HREF="#Q3_10">How do I install Apache-SOAP on Apache-JServ?</A><br> -3.11 <A HREF="#Q3_11">How do I install Apache-SOAP on iPlanet?</A><br> -3.13 <A HREF="#Q3_13">How do I install Apache-SOAP on Unify's ServletExec?</A><br> +3.4 <A HREF="#Q3_4">How do I install Apache-SOAP on Bea WebLogic 5.1?</A><br> +3.5 <A HREF="#Q3_5">How do I install Apache-SOAP on Bea WebLogic 6.0?</A><br> +3.6 <A HREF="#Q3_6">How do I install Apache-SOAP on Bea WebLogic 6.1 beta?</A><br> +3.7 <A HREF="#Q3_7">How do I install Apache-SOAP on Resin?</A><br> +3.8 <A HREF="#Q3_8">How do I install Apache-SOAP on IBM WebSphere?</A><br> +3.9 <A HREF="#Q3_9">How do I install Apache-SOAP on Bluestone?</A><br> +3.10 <A HREF="#Q3_10">How do I install Apache-SOAP on Orion?</A><br> +3.11 <A HREF="#Q3_11">How do I install Apache-SOAP on Apache-JServ?</A><br> +3.12 <A HREF="#Q3_12">How do I install Apache-SOAP on iPlanet?</A><br> +3.14 <A HREF="#Q3_14">How do I install Apache-SOAP on Unify's ServletExec?</A><br> <br></LI><LI><H2>Troubleshooting</H2>4.2 <A HREF="#Q4_2">Help! Visual Age can't compile SOAP - it says I'm missing package com.ibm.xmi.job.*</A><br> +4.3 <A HREF="#Q4_3">Help! My client sees error message: "SOAP-ENV:Server.BadTargetObjectURI"</A><br> 4.5 <A HREF="#Q4_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".</A><br> 4.7 <A HREF="#Q4_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"</A><br> -4.8 <A HREF="#Q4_8">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"</A><br> -4.9 <A HREF="#Q4_9">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?</A><br> -4.10 <A HREF="#Q4_10">Help! I'm getting this error: "java.io.InvalidClassException: +4.8 <A HREF="#Q4_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?</A><br> +4.9 <A HREF="#Q4_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"</A><br> +4.10 <A HREF="#Q4_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?</A><br> +4.11 <A HREF="#Q4_11">Help! I'm getting this error: "java.io.InvalidClassException: org.apache.soap.server.DeploymentDescriptor; Local class not compatible"</A><br> -<br></LI><LI><H2>SOAP and Namespaces</H2>5.1 <A HREF="#Q5_1">What are all these SOAP Namespaces?</A><br> -5.2 <A HREF="#Q5_2">Do I need to use namespaces on my XML data?</A><br> -5.3 <A HREF="#Q5_3">What are all those namespace prefixes in my SOAP messages? Won't they keep validation from working?</A><br> -<br></LI><LI><H2>SOAP and Serialization</H2>6.1 <A HREF="#Q6_1">How do I send user defined java objects using SOAP?</A><br> -6.2 <A HREF="#Q6_2">What are the different SOAP encoding styles? Which should I use?</A><br> -6.3 <A HREF="#Q6_3">How do you serialize java.util.Date objects?</A><br> -<br></LI><LI><H2>SOAP and DOM</H2>7.1 <A HREF="#Q7_1">I would like to write a SOAP service method that returns a DOM Document (org.w3c.dom.Document). How do I do this?</A><br> +4.13 <A HREF="#Q4_13">I'm getting an error telling me that class 'XMLParserLiason' is not found. What is wrong?</A><br> +4.14 <A HREF="#Q4_14">Help! I'm getting this error message: "Unable to retrieve PropertyDescriptor for property 'checkMustUnderstands' of class 'class org.apache.soap.server.DeploymentDescriptor'.</A><br> +4.15 <A HREF="#Q4_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.</A><br> +4.17 <A HREF="#Q4_17">Help! I'm getting this error: "Caught SOAPException <SOAP-ENV:Client>: Error opening socket:connection refused: no further information"</A><br> +<br></LI><LI><H2>Design and Architecture Issues</H2>5.2 <A HREF="#Q5_2">Can a SOAP server maintain session between multiple client invocations?</A><br> +5.3 <A HREF="#Q5_3">What is an actor?</A><br> +5.4 <A HREF="#Q5_4">Can Apache-SOAP handle large (multiple megabyte) files?</A><br> +5.5 <A HREF="#Q5_5">What is the best way to send a large file (multiple megabytes) with a soap request?</A><br> +5.8 <A HREF="#Q5_8">Is it possible to pass parameters to the constructor in a SOAP application ?</A><br> +5.9 <A HREF="#Q5_9">How do I write a SOAP service that maintains state across a session?</A><br> +5.11 <A HREF="#Q5_11">Is it possible to perform more than one invocation in a single SOAP request?</A><br> +5.12 <A HREF="#Q5_12">I would like to write a SOAP service method that returns a DOM Document (org.w3c.dom.Document). How do I do this?</A><br> +5.14 <A HREF="#Q5_14">What is the performance difference (if any) between SOAP and RMI? Are there any benchmark test results available?</A><br> +5.15 <A HREF="#Q5_15">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?</A><br> +<br></LI><LI><H2>SOAP and Namespaces</H2>6.1 <A HREF="#Q6_1">What are all these SOAP Namespaces?</A><br> +6.2 <A HREF="#Q6_2">Do I need to use namespaces on my XML data?</A><br> +6.3 <A HREF="#Q6_3">What are all those namespace prefixes in my SOAP messages? Won't they keep validation from working?</A><br> +<br></LI><LI><H2>SOAP and Serialization</H2>7.1 <A HREF="#Q7_1">How do I send user defined java objects using SOAP?</A><br> +7.2 <A HREF="#Q7_2">What are the different SOAP encoding styles? Which should I use?</A><br> +7.3 <A HREF="#Q7_3">How do you serialize java.util.Date objects?</A><br> <br></LI><LI><H2>WSDL</H2>8.1 <A HREF="#Q8_1">Where can I find the WSDL specification document?</A><br> -8.2 <A HREF="#Q8_2">How can I generate a WSDL file for my SOAP service?</A><br> -8.3 <A HREF="#Q8_3">Is there a tool that can validate WSDL?</A><br> -8.4 <A HREF="#Q8_4">Is there a command-line utility that I can use to generate a WSDL File?</A><br> -8.5 <A HREF="#Q8_5">Is there a command-line utility that I can use to generate WSDL stub and skeleton files?</A><br> -<br></LI><LI><H2>SOAP and .NET</H2>9.4 <A HREF="#Q9_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".</A><br> +8.2 <A HREF="#Q8_2">Does Apache SOAP use WSDL?</A><br> +8.3 <A HREF="#Q8_3">How can I generate a WSDL file for my SOAP service?</A><br> +8.4 <A HREF="#Q8_4">Is there a tool that can validate WSDL?</A><br> +8.5 <A HREF="#Q8_5">Is there a command-line utility that I can use to generate a WSDL File?</A><br> +8.6 <A HREF="#Q8_6">Is there a command-line utility that I can use to generate WSDL stub and skeleton files?</A><br> +<br></LI><LI><H2>SOAP and .NET</H2>9.1 <A HREF="#Q9_1">Does Apache SOAP work with Microsoft SOAP?</A><br> +9.4 <A HREF="#Q9_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".</A><br> </OL> <HR NOSHADE><H2>Questions and Answers</H2> @@ -104,7 +118,7 @@ 2.2 <STRONG><A NAME="Q2_2">Where can I find mailing list archives for the soap-user mailing list?</A></STRONG><BR> Try: <A HREF="http://marc.theaimsgroup.com/?l=soap-user&r=1&w=2";>http://marc.theaimsgroup.com/?l=soap-user&r=1&w=2</a> or: <A HREF="http://archive.covalent.net/";>http://archive.covalent.net/</a>.<p> 2.3 <STRONG><A NAME="Q2_3">I'm just getting started with SOAP. Where can I find a tutorial on SOAP programming?</A></STRONG><BR> -Try these links: <BR><A HREF="http://www-106.ibm.com/developerworks/library/ws-peer2/";>http://www-106.ibm.com/developerworks/library/ws-peer2/</a> <BR><A HREF="http://www.perfectxml.com/articles/xml/hellosoap.asp";>http://www.perfectxml.com/articles/xml/hellosoap.asp</a> <BR><A HREF="http://www.javapro.com/upload/free/features/javapro/2001/04apr01/prs0104/prs0104-1.asp";>http://www.javapro.com/upload/free/features/javapro/2001/04apr01/prs0104/prs0104-1.asp</a> <BR><A HREF="http://www.soaplite.com/#LINKS";>http://www.soaplite.com/#LINKS</a> <BR><A HREF="http://soap.manilasites.com/";>http://soap.manilasites.com/</a> <BR><A HREF="http://www.xmethods.net/gettingstarted/apache.html";>http://www.xmethods.net/gettingstarted/apache.html</a><p> +Try these links: <BR><A HREF="http://www-106.ibm.com/developerworks/library/ws-peer2/";>http://www-106.ibm.com/developerworks/library/ws-peer2/</a> <BR><A HREF="http://www.perfectxml.com/articles/xml/hellosoap.asp";>http://www.perfectxml.com/articles/xml/hellosoap.asp</a> <BR><A HREF="http://www.soapwebservices.com/articles/what_is_soap.asp";>http://www.soapwebservices.com/articles/what_is_soap.asp</a> (shockwave flash presentation) <BR><A HREF="http://www.javapro.com/upload/free/features/javapro/2001/04apr01/prs0104/prs0104-1.asp";>http://www.javapro.com/upload/free/features/javapro/2001/04apr01/prs0104/prs0104-1.asp</a> <BR><A HREF="http://www.soaplite.com/#LINKS";>http://www.soaplite.com/#LINKS</a> <BR><A HREF="http://soap.manilasites.com/";>http://soap.manilasites.com/</a> <BR><A HREF="http://www.xmethods.net/gettingstarted/apache.html";>http://www.xmethods.net/gettingstarted/apache.html</a><p> 2.4 <STRONG><A NAME="Q2_4">Are there any other SOAP FAQs available?</A></STRONG><BR> Yes, a list of FAQs is available here: <A HREF="http://www.SoapRPC.com/faqs/";>http://www.SoapRPC.com/faqs/</a>. You could also look at the SOAP FAQ maintained by Developmentor: <A HREF="http://www.develop.com/soap/soapfaq.htm";>http://www.develop.com/soap/soapfaq.htm</a>.<p> 2.5 <STRONG><A NAME="Q2_5">How does SOAP compare with other XML protocols?</A></STRONG><BR> @@ -127,34 +141,26 @@ Consider using SoapRMI for your client. It is 183KB (including full XML parser) and is available here: <A HREF="http://www.extreme.indiana.edu/soap/rmi/download/";>http://www.extreme.indiana.edu/soap/rmi/download/</a>. For more details about its design, see: <A HREF="http://www.extreme.indiana.edu/soap/";>http://www.extreme.indiana.edu/soap/</a>. <BR>You could also consider using IBM's 'Web Services Development Environment' <A HREF="http://www.alphaworks.ibm.com/tech/wsde";>http://www.alphaworks.ibm.com/tech/wsde</a> (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.<BR>Also have a look at KSoap - a small-footprint SOAP lib for J2ME: <A HREF="http://ksoap.enhydra.org/index.html";>http://ksoap.enhydra.org/index.html</a>.<p> 2.15 <STRONG><A NAME="Q2_15">Where do I find nightly builds of the POP3 and SMTP beans?</A></STRONG><BR> You'll find them here: <A HREF="http://www.alphaworks.ibm.com/ab.nsf/";>http://www.alphaworks.ibm.com/ab.nsf/</a>.<p> -2.16 <STRONG><A NAME="Q2_16">Can a SOAP server maintain session between multiple client invocations?</A></STRONG><BR> -It does now! Client-side cookie support was added to Apache SOAP by Sanjiva with the addition of the setMaintainSession function to the SOAPHTTPConnectionclass:<BR> shc = new SOAPHTTPConnection ();<BR> shc.setMaintainSession( true ); // NEW FUNCTION!!<BR> call.setSOAPTransport( shc );<BR>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). <BR>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.<p> -2.18 <STRONG><A NAME="Q2_18">Is there a way to generate SOAP stub/skeleton from deployment descriptor?</A></STRONG><BR> +2.18 <STRONG><A NAME="Q2_18">Is there a way to generate SOAP stub/skeleton code from a deployment descriptor?</A></STRONG><BR> Yes, you can use the IBM alphawork WSTK toolkit: <A HREF="http://www.alphaworks.ibm.com/tech/webservicestoolkit";>http://www.alphaworks.ibm.com/tech/webservicestoolkit</a>.<p> 2.19 <STRONG><A NAME="Q2_19">Is there a way to generate SOAP deployment descriptor from IDL?</A></STRONG><BR> 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.<p> 2.20 <STRONG><A NAME="Q2_20">Is there any way of specifying a timeout for a SOAP method invocation?</A></STRONG><BR> In Apache-SOAP version 2.1 you can set a timeout on the client side by using:<BR>SOAPHTTPConnection shc;<BR>shc = new SOAPHTTPConnection();<BR>shc.setTimeout(5000); //<-- 5 seconds<BR>Call call = new Call();<BR><BR>call.setSOAPTransport(shc);<p> -2.21 <STRONG><A NAME="Q2_21">Can Apache-SOAP handle large (multiple megabyte) files?</A></STRONG><BR> -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.<p> -2.22 <STRONG><A NAME="Q2_22">What is the best way to send a large file (multiple megabytes) with a soap request?</A></STRONG><BR> -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 <A HREF="http://xml.apache.org/soap/docs/guide/attachments.html";>http://xml.apache.org/soap/docs/guide/attachments.html</a> for more information.<p> +2.22 <STRONG><A NAME="Q2_22">Are there any ISP's that will host SOAP applications?</A></STRONG><BR> +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:<BR>- <A HREF="http://www.servlets.com/isps/<BR>-">http://www.servlets.com/isps/<BR>-</a> <A HREF="http://www.adrenalinegroup.com/jwsisp.html";>http://www.adrenalinegroup.com/jwsisp.html</a><p> 2.24 <STRONG><A NAME="Q2_24">Help! I got the following error message: "SOAP Service Manager: Unable to read 'DeployedServices.ds': assuming fresh start"</A></STRONG><BR> 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.<p> -2.26 <STRONG><A NAME="Q2_26">Is it possible to pass parameters to the constructor in a SOAP application ?</A></STRONG><BR> -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. <BR>An alternative to parameter passing is to load the information you need from a property file.<p> -2.27 <STRONG><A NAME="Q2_27">How do I write a SOAP service that maintains state across a session?</A></STRONG><BR> -Both the client and the server have to be modified to use maintain state across a session:<BR><BR>(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"). <BR><BR>(b) The client side needs to be told to return the cookies that help the maintain sessions:<BR> // Build the call.<BR> Call call = new Call();<BR> // We require the session to be maintained<BR> SOAPHTTPConnection conn = new SOAPHTTPConnection();<BR> conn.setMaintainSession(true);<BR> call.setSOAPTransport(conn); <BR><BR>See the samples.addressbook2.Main sample code for a detailed example of how to do this.<p> 2.28 <STRONG><A NAME="Q2_28">How do I tell my Apache SOAP client to use a proxy server?</A></STRONG><BR> Here is some sample code to do this:<BR>SOAPHTTPConnection connection = new SOAPHTTPConnection();<BR>connection.setProxyHost("proxy");<BR>connection.setProxyPort(8080);<p> 2.29 <STRONG><A NAME="Q2_29">How do I perform Proxy Authentication with my Apache SOAP client?</A></STRONG><BR> See the sample code in the weather service client - it shows how to do proxy authentication. Here is some sample code too:<BR>SOAPHTTPConnection connection = new SOAPHTTPConnection();<BR>connection.setProxyHost("proxy");<BR>connection.setProxyPort(8080);<BR>setProxyUserName("username");<BR>setProxyPassword("password");<p> +2.31 <STRONG><A NAME="Q2_31">Are there any commercially ready servlet containers which will support Apache SOAP clients ?</A></STRONG><BR> +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:<BR>- Bea WebLogic 6.0 at <A HREF="http://www.bea.com/";>http://www.bea.com/</a> <BR>- Resin at <A HREF="http://www.caucho.com/";>http://www.caucho.com/</a> <BR>- IBM WebSphere at <A HREF="http://www-4.ibm.com/software/webservers/";>http://www-4.ibm.com/software/webservers/</a> <BR>- HP Bluestone at <A HREF="http://www.bluestone.com/";>http://www.bluestone.com/</a> <BR>- Orion at <A HREF="http://www.orionserver.com/";>http://www.orionserver.com/</a> <BR>- iPlanet Application Server at <A HREF="http://www.iplanet.com/";>http://www.iplanet.com/</a> <BR>- ServletExec from Unify at <A HREF="http://www.unify.com/";>http://www.unify.com/</a> <BR>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.<BR>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.<p> 2.32 <STRONG><A NAME="Q2_32">Where can I find a list of public SOAP services that are available on the Internet?</A></STRONG><BR> Salcentral maintain a searchable list of web services here: <A HREF="http://www.salcentral.com/";>http://www.salcentral.com/</a>. <BR>Xmethods have a list here as well: <A HREF="http://www.xmethods.net/";>http://www.xmethods.net/</a>.<p> 2.34 <STRONG><A NAME="Q2_34">What tools are available that use Apache SOAP?</A></STRONG><BR> 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 (<A HREF="http://www-106.ibm.com/developerworks/library/w-wsdl.html";>http://www-106.ibm.com/developerworks/library/w-wsdl.html</a>), and the IBM toolkit (<A HREF="http://www.alphaworks.ibm.com/tech/webservicestoolkit";>http://www.alphaworks.ibm.com/tech/webservicestoolkit</a>).<p> -2.35 <STRONG><A NAME="Q2_35">What is an actor?</A></STRONG><BR> -Every SOAP message has 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. <BR><BR>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.<p> <p><H2><u>3. Installation</u></H2> @@ -164,79 +170,115 @@ 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'.<BR>Xmethods have a good tutorial which includes setup information: <A HREF="http://www.xmethods.net/gettingstarted/apache.html";>http://www.xmethods.net/gettingstarted/apache.html</a><p> 3.3 <STRONG><A NAME="Q3_3">Can I install Apache-SOAP 2.1 on Tomcat 4.0 beta?</A></STRONG><BR> 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.<p> -3.4 <STRONG><A NAME="Q3_4">How do I install Apache-SOAP on Bea WebLogic 6.0?</A></STRONG><BR> +3.4 <STRONG><A NAME="Q3_4">How do I install Apache-SOAP on Bea WebLogic 5.1?</A></STRONG><BR> +Dion Almaer has written an article about this and it has been included in the distribution. See <A HREF="http://xml.apache.org/websrc/cvsweb.cgi/xml-soap/java/docs/install/weblogic51.html";>http://xml.apache.org/websrc/cvsweb.cgi/xml-soap/java/docs/install/weblogic51.html</a>.<p> +3.5 <STRONG><A NAME="Q3_5">How do I install Apache-SOAP on Bea WebLogic 6.0?</A></STRONG><BR> Dion Almaer has written an article about this: <A HREF="http://www.almaer.com/weblogic60.html";>http://www.almaer.com/weblogic60.html</a>. There are some additional comments here: <A HREF="http://marc.theaimsgroup.com/?l=soap-user&m=98808422428291&w=2";>http://marc.theaimsgroup.com/?l=soap-user&m=98808422428291&w=2</a>.<p> -3.5 <STRONG><A NAME="Q3_5">How do I install Apache-SOAP on Bea WebLogic 6.1 beta?</A></STRONG><BR> -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 <A HREF="http://marc.theaimsgroup.com/?l=soap-user&m=99270271408539&w=2";>http://marc.theaimsgroup.com/?l=soap-user&m=99270271408539&w=2</a>.<p> -3.6 <STRONG><A NAME="Q3_6">How do I install Apache-SOAP on Resin?</A></STRONG><BR> +3.6 <STRONG><A NAME="Q3_6">How do I install Apache-SOAP on Bea WebLogic 6.1 beta?</A></STRONG><BR> +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 <A HREF="http://xml.apache.org/soap/faq/faq-for-WL6.1beta.html";>http://xml.apache.org/soap/faq/faq-for-WL6.1beta.html</a> [note: when WebLogic 6.1 is released, we will merge this FAQ with the Apache SOAP install docs] and <A HREF="http://marc.theaimsgroup.com/?l=soap-user&m=99270271408539&w=2";>http://marc.theaimsgroup.com/?l=soap-user&m=99270271408539&w=2</a>.<p> +3.7 <STRONG><A NAME="Q3_7">How do I install Apache-SOAP on Resin?</A></STRONG><BR> Under Resin 1.2.3, configure a web app to point to the soap webapp directory (i.e.<path-to-apache-soap>/webapps/soap).<p> -3.7 <STRONG><A NAME="Q3_7">How do I install Apache-SOAP on IBM WebSphere?</A></STRONG><BR> +3.8 <STRONG><A NAME="Q3_8">How do I install Apache-SOAP on IBM WebSphere?</A></STRONG><BR> 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 <A HREF="http://workspot.net/~zombie/soap/";>http://workspot.net/~zombie/soap/</a>. There are also instructions for WebSphere v3.5 in the Apache-SOAP distribution - see <A HREF="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";>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</a>. <BR>Be sure to check the following items: <BR>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 <A HREF="http://aaa.bbb.ccc.ddd:port/soap/servlet/rpcrouter";>http://aaa.bbb.ccc.ddd:port/soap/servlet/rpcrouter</a>. <BR>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).<p> -3.8 <STRONG><A NAME="Q3_8">How do I install Apache-SOAP on Bluestone?</A></STRONG><BR> +3.9 <STRONG><A NAME="Q3_9">How do I install Apache-SOAP on Bluestone?</A></STRONG><BR> The Bluestone people provide a download with instructions and samples: <A HREF="http://gallery.bluestone.com/scripts/SaISAPI.dll/Gallery.class/techDownloads/index.jsp";>http://gallery.bluestone.com/scripts/SaISAPI.dll/Gallery.class/techDownloads/index.jsp</a><p> -3.9 <STRONG><A NAME="Q3_9">How do I install Apache-SOAP on Orion?</A></STRONG><BR> +3.10 <STRONG><A NAME="Q3_10">How do I install Apache-SOAP on Orion?</A></STRONG><BR> Have a look here: <A HREF="http://marc.theaimsgroup.com/?l=soap-dev&m=97678072329144&q=p3";>http://marc.theaimsgroup.com/?l=soap-dev&m=97678072329144&q=p3</a>.<p> -3.10 <STRONG><A NAME="Q3_10">How do I install Apache-SOAP on Apache-JServ?</A></STRONG><BR> +3.11 <STRONG><A NAME="Q3_11">How do I install Apache-SOAP on Apache-JServ?</A></STRONG><BR> Here are some instructions: <A HREF="http://marc.theaimsgroup.com/?l=soap-user&m=98890652006035&w=2";>http://marc.theaimsgroup.com/?l=soap-user&m=98890652006035&w=2</a>.<p> -3.11 <STRONG><A NAME="Q3_11">How do I install Apache-SOAP on iPlanet?</A></STRONG><BR> +3.12 <STRONG><A NAME="Q3_12">How do I install Apache-SOAP on iPlanet?</A></STRONG><BR> See Erik Onnen's article here: <A HREF="http://marc.theaimsgroup.com/?l=soap-user&m=98753020626284&q=p3";>http://marc.theaimsgroup.com/?l=soap-user&m=98753020626284&q=p3</a>.<p> -3.13 <STRONG><A NAME="Q3_13">How do I install Apache-SOAP on Unify's ServletExec?</A></STRONG><BR> +3.14 <STRONG><A NAME="Q3_14">How do I install Apache-SOAP on Unify's ServletExec?</A></STRONG><BR> See <A HREF="http://marc.theaimsgroup.com/?l=soap-user&m=97741067209680&w=2";>http://marc.theaimsgroup.com/?l=soap-user&m=97741067209680&w=2</a>.<p> <p><H2><u>4. Troubleshooting</u></H2> 4.2 <STRONG><A NAME="Q4_2">Help! Visual Age can't compile SOAP - it says I'm missing package com.ibm.xmi.job.*</A></STRONG><BR> These classes can be downloaded from <A HREF="http://www.alphaworks.ibm.com/aw.nsf/textformula/bc977085639b0fb888256a10006";>http://www.alphaworks.ibm.com/aw.nsf/textformula/bc977085639b0fb888256a10006</a>. The missing package is a xmisoap.jar, which contains the following files: <BR>com.ibm.xmi.framework.* <BR>com.ibm.xmi.job.* <BR>com.ibm.xmi.utility.*<p> +4.3 <STRONG><A NAME="Q4_3">Help! My client sees error message: "SOAP-ENV:Server.BadTargetObjectURI"</A></STRONG><BR> +The most likely cause of this problem is a classpath error: The class file that implements your service is not in the classpath of<BR>the server.<p> 4.5 <STRONG><A NAME="Q4_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".</A></STRONG><BR> Check that your client is connecting to port 8080 (i.e. <A HREF="http://localhost:8080/";>http://localhost:8080/</a> rather than <A HREF="http://localhost/";>http://localhost/</a>). You might accidentally be connecting to a web server (e.g. Apache or IIS) instead of your SOAP/Tomcat server.<p> 4.7 <STRONG><A NAME="Q4_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"</A></STRONG><BR> This may be related to a JDK 1.3 bug on Linux; try<BR>- Using JDK 1.2<BR>- Using the -server or -client option on the JDK 1.3 JVM<p> -4.8 <STRONG><A NAME="Q4_8">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"</A></STRONG><BR> +4.8 <STRONG><A NAME="Q4_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?</A></STRONG><BR> +This problem is due to a combination of the JVM 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).<BR>You should also make sure that the JVM is using the classic<BR>compiler each time. Do this by editing a file called jvm.cfg and<BR>making sure classic is the first available option for the VM. This file<BR>is in $JAVA_HOME/jre/lib.<p> +4.9 <STRONG><A NAME="Q4_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"</A></STRONG><BR> 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.<p> -4.9 <STRONG><A NAME="Q4_9">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?</A></STRONG><BR> +4.10 <STRONG><A NAME="Q4_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?</A></STRONG><BR> This problem occurs because IIS sends this data:<BR>Content-Type:text/xml; charset=utf-8<BR>But Apache-SOAP sends this data:<BR>Content-Type: text/xml; charset=utf-8 <BR>(Note the space after 'Content-Type').<BR>The problem has been fixed - upgrade to v2.2 or later of Apache-SOAP and it should go away.<p> -4.10 <STRONG><A NAME="Q4_10">Help! I'm getting this error: "java.io.InvalidClassException: +4.11 <STRONG><A NAME="Q4_11">Help! I'm getting this error: "java.io.InvalidClassException: org.apache.soap.server.DeploymentDescriptor; Local class not compatible"</A></STRONG><BR> 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.<p> +4.13 <STRONG><A NAME="Q4_13">I'm getting an error telling me that class 'XMLParserLiason' is not found. What is wrong?</A></STRONG><BR> +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.<p> +4.14 <STRONG><A NAME="Q4_14">Help! I'm getting this error message: "Unable to retrieve PropertyDescriptor for property 'checkMustUnderstands' of class 'class org.apache.soap.server.DeploymentDescriptor'.</A></STRONG><BR> +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.<p> +4.15 <STRONG><A NAME="Q4_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.</A></STRONG><BR> +This is a result of a code change that the Mozilla folks made which is not backward-compatible. You have two options: <BR>(a) Upgrade to Rhino 1.5. <BR>(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.<p> +4.17 <STRONG><A NAME="Q4_17">Help! I'm getting this error: "Caught SOAPException <SOAP-ENV:Client>: Error opening socket:connection refused: no further information"</A></STRONG><BR> +The problem is caused by one of the following:<BR>(a) Your SOAP client isn't specifying the right port in the service URL, e.g. It is using <A HREF="http://localhost:80/soap/servlet/rpcrouter";>http://localhost:80/soap/servlet/rpcrouter</a> but the SOAP service router is listening on port 8080 (i.e. <A HREF="http://localhost:8080/soap/servlet/rpcrouter";>http://localhost:8080/soap/servlet/rpcrouter</a> ). <BR>(b) Your SOAP client isn't specifying the right path in the service URL, e.g. it is using <A HREF="http://localhost:8080/rpcrouter";>http://localhost:8080/rpcrouter</a> instead of <A HREF="http://localhost:8080/soap/servlet/rpcrouter";>http://localhost:8080/soap/servlet/rpcrouter</a>. <BR>(c) Your application server/servlet container (e.g. Tomcat) isn't running.<p> + + +<p><H2><u>5. Design and Architecture Issues</u></H2> +5.2 <STRONG><A NAME="Q5_2">Can a SOAP server maintain session between multiple client invocations?</A></STRONG><BR> +Yes! Client-side cookie support was added to Apache SOAP by Sanjiva with the addition of the setMaintainSession function to the SOAPHTTPConnectionclass:<BR> shc = new SOAPHTTPConnection ();<BR> shc.setMaintainSession( true ); // NEW FUNCTION!!<BR> call.setSOAPTransport( shc );<BR>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). <BR>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.<p> +5.3 <STRONG><A NAME="Q5_3">What is an actor?</A></STRONG><BR> +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. <BR>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.<p> +5.4 <STRONG><A NAME="Q5_4">Can Apache-SOAP handle large (multiple megabyte) files?</A></STRONG><BR> +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.<p> +5.5 <STRONG><A NAME="Q5_5">What is the best way to send a large file (multiple megabytes) with a soap request?</A></STRONG><BR> +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 <A HREF="http://xml.apache.org/soap/docs/guide/attachments.html";>http://xml.apache.org/soap/docs/guide/attachments.html</a> for more information.<p> +5.8 <STRONG><A NAME="Q5_8">Is it possible to pass parameters to the constructor in a SOAP application ?</A></STRONG><BR> +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. <BR>An alternative to parameter passing is to load the information you need from a property file.<p> +5.9 <STRONG><A NAME="Q5_9">How do I write a SOAP service that maintains state across a session?</A></STRONG><BR> +Both the client and the server have to be modified to use maintain state across a session:<BR><BR>(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"). <BR><BR>(b) The client side needs to be told to return the cookies that help the maintain sessions:<BR> // Build the call.<BR> Call call = new Call();<BR> // We require the session to be maintained<BR> SOAPHTTPConnection conn = new SOAPHTTPConnection();<BR> conn.setMaintainSession(true);<BR> call.setSOAPTransport(conn); <BR><BR>See the samples.addressbook2.Main sample code for a detailed example of how to do this.<p> +5.11 <STRONG><A NAME="Q5_11">Is it possible to perform more than one invocation in a single SOAP request?</A></STRONG><BR> +No. SOAP v1.1 (see <A HREF="http://www.w3.org/TR/SOAP/";>http://www.w3.org/TR/SOAP/</a>), which is what Apache SOAP implements, does not allow that.<p> +5.12 <STRONG><A NAME="Q5_12">I would like to write a SOAP service method that returns a DOM Document (org.w3c.dom.Document). How do I do this?</A></STRONG><BR> +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 "<A HREF="http://xml.apache.org/xml-soap/literalxml"";>http://xml.apache.org/xml-soap/literalxml";</a> and the encoding style for the parameter to "<A HREF="http://schemas.xmlsoap.org/soap/encoding"";>http://schemas.xmlsoap.org/soap/encoding";</a>. Thus, part of your client code would look like:<BR>...<BR>Call call = new Call();<BR>call.setTargetObjectURI("urn:someservice");<BR>call.setMethodName("callmethod");<BR>call.setEncodingStyleURI( Constants.NS_URI_LITERAL_XML );<BR>String strparam = "joebob";<BR><BR>Vector params = new Vector();<BR>params.addElement( new Parameter( "strparam", String.class,<BR> strparam, Constants.NS_URI_SOAP_ENC ) );<BR>�<BR><BR>See the GetAllListings() method in the Addressbook sample for a more detailed example of how to control the return encoding style.<p> +5.14 <STRONG><A NAME="Q5_14">What is the performance difference (if any) between SOAP and RMI? Are there any benchmark test results available?</A></STRONG><BR> +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. <BR>Bear in mind that:<BR>- Apache SOAP implementations will be optimized in the future, and RMI probably won't. <BR>- The common expectation is that eventually, SOAP implementations will provide performance that is comparable to RMI.<BR>- RMI is Java only, SOAP isn't.<p> +5.15 <STRONG><A NAME="Q5_15">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?</A></STRONG><BR> +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).<p> -<p><H2><u>5. SOAP and Namespaces</u></H2> -5.1 <STRONG><A NAME="Q5_1">What are all these SOAP Namespaces?</A></STRONG><BR> +<p><H2><u>6. SOAP and Namespaces</u></H2> +6.1 <STRONG><A NAME="Q6_1">What are all these SOAP Namespaces?</A></STRONG><BR> 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:<BR>1. xmlns:SOAP-ENV="<A HREF="http://schemas.xmlsoap.org/soap/envelope/"";>http://schemas.xmlsoap.org/soap/envelope/";</a> <BR>2. xmlns:SOAP-ENC="<A HREF="http://schemas.xmlsoap.org/soap/encoding/"";>http://schemas.xmlsoap.org/soap/encoding/";</a> <BR>3. xmlns:xsi="<A HREF="http://www.w3.org/1999/XMLSchema-instance"";>http://www.w3.org/1999/XMLSchema-instance";</a> <BR>4. xmlns:xsd="<A HREF="http://www.w3.org/1999/XMLSchema"";>http://www.w3.org/1999/XMLSchema";</a> <BR><BR>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. <BR>The SOAP Envelope namespace defines the 'Envelope', 'Header' and 'Body' element names and the 'encodingStyle', 'actor' and 'mustUnderstand' attributes. <BR>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. <BR><BR>The XML Schema Instance namespace defines the 'type' attribute, which identifies the data type of an element. <BR><BR>The XML Schema namespace defines several datatypes used as values of the 'xsi:type' attribute. Examples include: 'int', 'String', 'double', and 'ur-type'.<p> -5.2 <STRONG><A NAME="Q5_2">Do I need to use namespaces on my XML data?</A></STRONG><BR> +6.2 <STRONG><A NAME="Q6_2">Do I need to use namespaces on my XML data?</A></STRONG><BR> The short answer is yes, but only a little. <BR>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.<BR>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 <A HREF="http://www.w3.org/TR/SOAP";>http://www.w3.org/TR/SOAP</a>). <BR>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.<p> -5.3 <STRONG><A NAME="Q5_3">What are all those namespace prefixes in my SOAP messages? Won't they keep validation from working?</A></STRONG><BR> +6.3 <STRONG><A NAME="Q6_3">What are all those namespace prefixes in my SOAP messages? Won't they keep validation from working?</A></STRONG><BR> 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). <BR>SOAP-ENV:Envelope<BR> ...xmlns:acme="urn://acmecorp.com/namespace"...<BR> ...<BR> ns3:GetData xmlns:ns3="urn://acmecorp.com/namespace"<BR> /ns3:GetData<BR> ...<BR><BR>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.<p> -<p><H2><u>6. SOAP and Serialization</u></H2> -6.1 <STRONG><A NAME="Q6_1">How do I send user defined java objects using SOAP?</A></STRONG><BR> +<p><H2><u>7. SOAP and Serialization</u></H2> +7.1 <STRONG><A NAME="Q7_1">How do I send user defined java objects using SOAP?</A></STRONG><BR> 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).<BR><BR>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: <BR>SOAPMappingRegistry smr = new SOAPMappingRegistry();<BR>MyObjectSerialzier myObjSer = new MyObjectSerialzier();<BR>smr.mapTypes( Constants.NS_URI_SOAP_ENC,<BR> new QName("urn://myown.com/objects/", "MyObject"),<BR> Object.class, myObjSer, myObjSer );<BR><BR>Then, when you deploy the service that you are calling, you must have a mapping entry that looks something like the following: <BR>isd:map encodingStyle = "<A HREF="http://schemas.xmlsoap.org/soap/encoding/"";>http://schemas.xmlsoap.org/soap/encoding/";</a> <BR> xmlns:x="urn://myown.com/objects/" qname="x:MyObject"<BR> javaType="com.myown.objects.MyObject"<BR> java2XMLClassName="com.myown.soap.MyObjectSerializer"<BR> xml2JavaClassName="com.myown.soap.MyObjectSerializer"/<BR><BR>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. <BR><BR>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. <BR><BR>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. <BR><BR>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.<p> -6.2 <STRONG><A NAME="Q6_2">What are the different SOAP encoding styles? Which should I use?</A></STRONG><BR> +7.2 <STRONG><A NAME="Q7_2">What are the different SOAP encoding styles? Which should I use?</A></STRONG><BR> 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.<BR>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.<BR>1. SOAP Encoding: This encoding style is identified by the SOAP Encoding URI <A HREF="http://schemas.xmlsoap.org/soap/encoding/";>http://schemas.xmlsoap.org/soap/encoding/</a> and is described fully in Section 5 of the SOAP specification. <BR>2. XMI Encoding <BR>3. Literal XML Encoding<p> -6.3 <STRONG><A NAME="Q6_3">How do you serialize java.util.Date objects?</A></STRONG><BR> +7.3 <STRONG><A NAME="Q7_3">How do you serialize java.util.Date objects?</A></STRONG><BR> 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.<BR>Date objects should be converted to xsd:date (<A HREF="http://www.w3.org/TR/xmlschema-2/#date";>http://www.w3.org/TR/xmlschema-2/#date</a>) or xsd:timeInstant (<A HREF="http://www.w3.org/TR/xmlschema-2/#timeInstant";>http://www.w3.org/TR/xmlschema-2/#timeInstant</a>) to be SOAP compliant. <BR>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", (<A HREF="http://www.w3.org/TR/SOAP/#_Toc478383514";>http://www.w3.org/TR/SOAP/#_Toc478383514</a>), but not all have been implemented<p> -<p><H2><u>7. SOAP and DOM</u></H2> -7.1 <STRONG><A NAME="Q7_1">I would like to write a SOAP service method that returns a DOM Document (org.w3c.dom.Document). How do I do this?</A></STRONG><BR> -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 "<A HREF="http://xml.apache.org/xml-soap/literalxml"";>http://xml.apache.org/xml-soap/literalxml";</a> and the encoding style for the parameter to "<A HREF="http://schemas.xmlsoap.org/soap/encoding"";>http://schemas.xmlsoap.org/soap/encoding";</a>. Thus, part of your client code would look like:<BR>...<BR>Call call = new Call();<BR>call.setTargetObjectURI("urn:someservice");<BR>call.setMethodName("callmethod");<BR>call.setEncodingStyleURI( Constants.NS_URI_LITERAL_XML );<BR>String strparam = "joebob";<BR><BR>Vector params = new Vector();<BR>params.addElement( new Parameter( "strparam", String.class,<BR> strparam, Constants.NS_URI_SOAP_ENC ) );<BR>�<BR><BR>See the GetAllListings() method in the Addressbook sample for a more detailed example of how to control the return encoding style.<p> - - <p><H2><u>8. WSDL</u></H2> 8.1 <STRONG><A NAME="Q8_1">Where can I find the WSDL specification document?</A></STRONG><BR> The WSDL specification document is available at <A HREF="http://www.w3.org/TR/wsdl";>http://www.w3.org/TR/wsdl</a>.<p> -8.2 <STRONG><A NAME="Q8_2">How can I generate a WSDL file for my SOAP service?</A></STRONG><BR> +8.2 <STRONG><A NAME="Q8_2">Does Apache SOAP use WSDL?</A></STRONG><BR> +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.<p> +8.3 <STRONG><A NAME="Q8_3">How can I generate a WSDL file for my SOAP service?</A></STRONG><BR> You can use IBM web services toolkit - WSTK - (class<BR>com.ibm.wstk.swrapper.ui.SWrapperGUI) on <A HREF="http://www.alphaworks.ibm.com/tech/wsde";>http://www.alphaworks.ibm.com/tech/wsde</a>, or IBM Web services development environment on <A HREF="http://www.ibm.com/developerworks/webservices";>http://www.ibm.com/developerworks/webservices</a>. You could also consider using GLUE, which includes a command line tool for static generation of WSDL: <A HREF="http://www.themindelectric.com/";>http://www.themindelectric.com/</a>. <BR>The Apache AXIS folks are also working on a tool called java2wsdl. See <A HREF="http://xml.apache.org/axis/";>http://xml.apache.org/axis/</a> for more information.<p> -8.3 <STRONG><A NAME="Q8_3">Is there a tool that can validate WSDL?</A></STRONG><BR> +8.4 <STRONG><A NAME="Q8_4">Is there a tool that can validate WSDL?</A></STRONG><BR> Yes: Simon Fell has written a Schematron-based validator for SOAP oriented WSDL documents. See here: <A HREF="http://www.pocketsoap.com/wsdl/";>http://www.pocketsoap.com/wsdl/</a>. 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.<p> -8.4 <STRONG><A NAME="Q8_4">Is there a command-line utility that I can use to generate a WSDL File?</A></STRONG><BR> +8.5 <STRONG><A NAME="Q8_5">Is there a command-line utility that I can use to generate a WSDL File?</A></STRONG><BR> Yes - the IBM web services toolkit (WSTK) 2.3 (<A HREF="http://www.ibm.com/developerworks/webservices/";>http://www.ibm.com/developerworks/webservices/</a>) includes a utility called 'wsdlgen'. It is in WSTK_HOME/bin.<p> -8.5 <STRONG><A NAME="Q8_5">Is there a command-line utility that I can use to generate WSDL stub and skeleton files?</A></STRONG><BR> +8.6 <STRONG><A NAME="Q8_6">Is there a command-line utility that I can use to generate WSDL stub and skeleton files?</A></STRONG><BR> Yes - the IBM web services toolkit (<A HREF="http://www.ibm.com/developerworks/webservices/";>http://www.ibm.com/developerworks/webservices/</a>) includes a command-line java application that should do what you want: <BR>.com.ibm.wsdl.Main -?<BR>Note that:<BR>(a) It is in the wsdl.jar library.<BR>(b) Passing in '-?' (without the apostrophes) gets you a list of available commands that the class supports.<p> <p><H2><u>9. SOAP and .NET</u></H2> +9.1 <STRONG><A NAME="Q9_1">Does Apache SOAP work with Microsoft SOAP?</A></STRONG><BR> +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. <BR>James Snell has provided a patch adding the typing. It can be found at SOAP-WRC web site (<A HREF="http://www.soap-wrc.com/apache_ms_soap_interop.zip";>http://www.soap-wrc.com/apache_ms_soap_interop.zip</a>). <BR>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: <A HREF="http://marc.theaimsgroup.com/?l=soap-user&m=98505313219298&w=2";>http://marc.theaimsgroup.com/?l=soap-user&m=98505313219298&w=2</a>).<p> 9.4 <STRONG><A NAME="Q9_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".</A></STRONG><BR> 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.<BR>SOAP users have also commented that if you upgrade to MSSoap toolkit 2.0 beta2 (or even rc0), this problem seems to go away.<p> </OL>
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
