Thanks to Apache Forrest Team, WS-SOAP website has renewed by using this wonderful Forrest Tool.

CVS Repository has moved to http://cvs.apache.org/viewcvs/ws-soap/ from http://cvs.apache.org/viewcvs/xml-soap/. Repository name is now "ws-soap". For more information, see the WebServices Homepage (CVS)

Nightly builds have moved to http://cvs.apache.org/dist/soap/nightly/. Releases are still at http://www.apache.org/dyn/closer.cgi/ws/soap/.

Click here for a list of changes.

Click here for a list of changes.

Click here for a list of changes.

Click here for a list of changes.

Apache SOAP ("Simple Object Access Protocol") is an implementation of the SOAP submission to W3C. It is based on, and supersedes, the IBM SOAP4J implementation.

From the draft W3C specification: SOAP is a lightweight protocol for exchange of information in a decentralized, distributed environment. It is an XML based protocol that consists of three parts: an envelope that defines a framework for describing what is in a message and how to process it, a set of encoding rules for expressing instances of application-defined datatypes, and a convention for representing remote procedure calls and responses.

See also the follow-on project: Apache Axis.

Apache SOAP is available in both source code and precompiled binary (JAR files) form. All Apache SOAP packages are made available under the Apache Software License.

• Supports most of the SOAP v1.1 specification.
• Supports the SOAP Messages with Attachments W3C Note.
• Provides server-side infrastructure for deploying, managing and running SOAP enabled services.
• Provides client-side API for invoking SOAP services.
• Release includes full source under the Apache Software License.
• Supports three encoding styles: SOAP v1.1 Encoding, Literal XML and XMI.
• XMI encoding (available when using Java 1.2.2) supports automatic marshalling and unmarshalling of arbitrary objects.
• SOAP encoding: built-in support is provided for encoding/decoding primitive types, Strings, arbitrary JavaBeans (using reflection) and 1-dimensional arrays of these types. For other types user can hand-write encoder/decoder and register with XML-SOAP runtime.
• Literal XML encoding: allows one to send XML elements (DOM org.w3c.dom.Element objects) as parameters by embedding the literal XML serialization of the DOM tree. No code needs to be written to support this (see the addressbook demo to see a sample use of it).
• Supports messaging and RPC over two transports: HTTP and SMTP.
• Supports authoring services in scripting languages.

The following features of the SOAP v1.1 specification are not currently supported:

• encodingStyle attribute must have only one encoding style given (see section 4.1.1 of the spec)
• mustUnderstand attribute support - only supports checking for and rejecting requests that require mustUnderstand checking
• root attribute
• actor attribute and SOAP intermediaries
• does not use multi-ref accessors during serialization

The following limitations on SOAP Messages with Attachments currently exist:

• The document base URI is not picked up from the multipart's Content-Location header.
• Support for relative URIs in Content-Location headers is limited to concatenating the document base URI to the relative URI.
• The provided SMTP transport does not support multipart messages.
• Server-side RPC methods have no way to add attachments to the response other than via the return object. Messaging methods can do this already.

The following people are currently committers to the xml-soap project:

• Harmeet Bedi
• Jonathan Chawke
• Franciso Curbera
• Glen Daniels
• Doug Davis
• Matthew J. Duftler
• Kevin Mitchell
• William Nagy
• Scott Nichol
• Sam Ruby
• James Snell
• Sanjiva Weerawarana

Medium Traffic Subscribe Unsubscribe Archives

This is the list where active users of Soap meet and discuss issues, installation problems and what not.

Medium Traffic Subscribe Unsubscribe Archives

This is the list where participating developers of Soap meet and discuss issues, code changes/additions, etc. Subscribers to this list also get notices of each and every code change, build results, testing notices, etc.

• Added logic to use xsi:nil, instead of xsi:null, when using the 2001 Schema spec.
• Fixed behavior when the 1999 or 2000 schema URI is specified so that the serialization logic uses the older version of both the xsi and the xsd namespaces; it was previously just using the older xsd namespace.

• Changed default schema to 2001 spec.
• Reflected timeInstant -> dateTime change in 2001 schema spec.
• Added support for primitive XSD data type hexBinary.
• Added support for 2001:base64Binary.
• Added HTTPS proxy support.
• Made several changes to reduce the overhead of a SOAPMappingRegistry creation and also to reduce the number of SMRs created.
• Removed SMR constructor which took the schema namespace URI because it doesn't work (new'ing an SMR with the desired URI isn't enough to make the entire thing use that schema URI).
• Added a getParent() method to SOAPMappingRegistry to allow the registry tree to be walked-up.
• Added a test to the SOAPMappingRegistry so that null strings get serialized correctly.
• Fixed a bug that prevents the default encoding from being correctly applied in the SOAPMappingRegistry.
• The SOAPMappingRegistry class, a subclass of XMLJavaMappingRegistry, now supports chaining, i.e. an instance has a parent, with the parent being null for the "root" instance. When looking up a mapping, the chain is followed if necessary to resolve the mapping.
• The XMLJavaMappingRegistry class has a method setDefaultEncodingStyle, which sets the default encoding style. When this method is called on a SOAPMappingRegistry instance, the default encoding style is set only for the particular link in the chain. It is *not* set for the parent (and recursively for all parents). This breaks the proper application of the default.
• Fixed encoding in SOAPHTTPConnection for systems whose default codepage is not 8859_1.
• Add deployment descriptor to the bag in SOAPContext so people can query the data in it.
• Fixed the popPollDelay constructor argument in SOAPSMTPConnection so that it is no longer being ignored.
• Put the port number back in the HTTP host header.
• Fixed the behavior of ExceptionFaultListener. It was previously not looking in the right place for the type of the detail entry to be unmarshalled. It was also not printing the encodingStyle attribute.
• Within SOAPException, the fault code and exception message will now be run through Utils.cleanString(...) to escape special characters.
• "Clean" stack tracebacks. In particular, constructors appear in stack tracebacks as <init> methods.
• Fixed the deployment descriptor so javaType= doesn't get output if the value is null.
• Fixed a bug that prevented a service's method from taking a Hashtable, array, or Vector, as a parameter, while returning a DOM Element.
• Fixed the documentation and code for the Base64 class so that they match, and so that encode uses its len parameter correctly.
• Fixed a bug that prevented the client from using a BeanSerializer to serialize SOAP-encoded parameters within a Call labeled with the literalXML encoding style.
• The BooleanDeserializer has been updated to be very liberal in what it will accept; per the spec, 0 and 1 are valid boolean values (and, in fact, are the ones used by the WhiteMesa implementation).
• Synchronized calls to DateFormat's methods, since DateFormat appears to not be thread-safe.
• Serialize dates without losing precision (the JDK format is contains milliseconds). Deserialize dates with any number of digits of fractional seconds, and with or without a time zone offset.
• Fixed a NullPointerException that was being thrown when a DataSource was passed as the source parameter within the MimePartSerializer.
• Started to add the ability to serialize elements with qualified names. If PrefixedName objects are not explicitly used as the context arguments for serialization, the behavior is exactly the same as it was before.
• Fixed a bug in the EJB providers which printed out the wrong error message.
• Changed context intialization within the EJB providers to allow the specification of the PROVIDER_URL and INITIAL_CONTEXT_FACTORY separately.
• Put in the non-debug version of the COM provider.
• Added a method to remove a body part from a Call object.
• Fixed a problem that would cause a Call object's targetObjectURI property to get set to null if a Fault was returned.
• Pass the actual encoding style on the Call constructor. Solves a literal XML interop problem with pocket soap.
• Fixed a bug that was causing an attribute to be printed without a closing ".
• The DeploymentDescriptor will now allow a TypeMapping to be specified without the elementType.
• Made the DeploymentDescriptor and TypeMappings serializing/deserializing logic more tolerant of null values.
• Fixed the DeploymentDescriptor.toString() method to correctly display the TypeMappings.
• Removed debug println from the DeploymentDescriptor.
• Add support for opts on java and script services in the dd.xml file.
• A type-check was not being performed in the ServiceManager due to its placement. It has been moved so that it now has effect.
• Added support for setting the configuration file name as a Web application context parameter so that it will be picked up by the JSPs as well as the router servlets. This will fix the problem of the JSPs using the default ConfigMananger when one has been specified for the router servlets.
• Fixed problem of attempting to store null as the classloader in the servlet attributes.
• Made the servlets store the classloader from the thread instead of theirs.
• Removed 2 server-side stack traces from the servlets where exceptions were also being propagated.
• Made the ServerHTTPUtils.readEnvelopeFromRequest(...) method public, instead of the default package access.
• The code will now only store the target object in the ServletContext or HTTPSession when it is newly created, and will not store it on each invocation.
• Added a patch to SOAPHTTPConnection that makes the set-cookie and set-cookie2 header searches case-insensitive.
• Fixed exceptions that are thrown from HTTPUtils, so that they contain more helpful messages.
• Ensure request URI contains at least one character.
• Fixed a StringOutOfBoundsException that was being thrown when a server returned a header with no value to an Apache SOAP client.
• Added a method to DOMUtils to retrieve qualified attribute value. That is, it will returna QName representing the value of the requested attribute.
• Fixed a problem with QName that Was causing it to throw a NullPointerException if localPart constructor arg was null.
• Fixed a missing closing </a> tag in list.jsp.
• Build now allows dist target to build when ejb is not present.
• Added support for config file element to allow users to enable or disable SOAP interface to Service Manager.
• Changed all samples to use the Fault class's toString() method, instead of calling the getFaultCode() and getFaultString() methods. This will cause the samples to display all the fault information, and not just parts of it.
• Added a new calculator demo that simulates a reverse polish notation calculator.
• Fixed the EJB sample so that the correct parameters are passed to the EJB method.
• Fixed up the interop sample and added support for the echoMap service.
• Updated to reflect Java 1.2+ requirement.
• Fixed some typos in the documentation.
• Fixed WAS 3.5 instructions for using the correct Xerces JAR.
• Updated deployment descriptor schema to reflect the mapping QName being made optional.
• Made the XMLParserUtils.getXMLDocBuilder() method synchronized.
• Added support for turning off Nagle's algorithm under TCP (HTTP).
• Fixed ArraySerializer to recognize null items when unmarshalling.
• Changed unmarshalling of xsi:null to be just as liberal as BooleanDeserializer is in what it accepts.

• Changed all code and samples to use JAXP; no longer bound to Xerces.
• Removed many printlns from the server-side code, replacing them with thrown Exceptions.
• A soap.war Web Application Archive is now included in the distribution for easier deployment to Servlet containers.
• Included SSL (on Tomcat) doc, and linked to it from the Installation page.
• Added support for serializing/deserializing java.util.Maps.
• Added support for serializing/deserializing BigDecimal <--> xsd:decimal.
• Removed non-threadsafe private variables from Servlets.
• If a service method with a matching signature is not found, a second search is done for a method with an additional (first) parameter of type SOAPContext.
• User's Guide has been re-worked and updated.
• COM sample has been updated.
• Added a BEA WebLogic EJB sample.
• Changed the EJB providers so that it grabs the JNDIName from one of the 'options' instead of from the 'java class=' section of the deployment descriptor. For backwards compatibility if it doesn't find it in the options section (using key="JNDIName") then it will look in the old 'java class=' section.
• Added an XMLConfigManager.
• Added a BaseConfigManager (to make authoring ConfigManagers easier).
• Added a workaround to org.apache.soap.Fault to enable it to work with Xerces 1.3.1 and later. It will now accept a return value of "" from Node.getNamespaceURI(), instead of just accepting null or a non-empty String.
• Fixed a bug when deserializing nulls of type "ur-type", which are generated when the VectorSerializer finds nulls inside a Vector.
• Removed requirement of <java> tag in deployment descriptor when using pluggable providers.
• Fixed a bug where a 400 error code was being returned instead of the 500 required by SOAP.
• Fixed a bug in header parsing code .. it was assuming that a space existed after the ":" character.
• Unmarshalling logic now understands 1999, 2000, and 2001 Schema simple types.
• Unmarshalling logic can now deserialize payload with ID/HREF attributes.
• RPCRouter can now throw a SOAPException if the checkMustUnderstand property is set on the DeploymentDescriptor and a mustUnderstand="1" attribute is found on a header.
• The output buffer size can now be explicitly set on the SOAPHTTPConnection.
• Added HTTP proxy basic authentication support.
• The SOAPHTTPConnection now has a maintainSession property which, when true, will cause the SOAPHTTPConnection to return the appropriate cookies with requests. It is true by default.
• Added a default encoding style property to SOAPMappingRegistry, to be used when no encoding style is specified.
• Removed special treatment of CDATA sections in the code that inserts escape sequences. The code will now round trip Strings correctly, whether they contain CDATA sections or not.
• All the simple numeric types now use a serializer that does not run its content through Utils.cleanString(String).
• Cleaned up handling of servlet init-parameters in RPCRouterServlet and MessageRouterServlet.
• Removed transport hook system property dependency. The only remaining call to System.getProperty(String) is to get "line.separator". This should help with some of the security constraints for Applets and the like.
• Removed some extraneous methods from org.apache.soap.util.StringUtils.
• Put 2 lines back into XMISerializer and XMIDeserializer (the same 1 line in each, actually) to enable them to work with the xmisoap.jar which is posted on the site. These lines were originally there, but were removed to try to work with the latestXMI version. For now, the code works with the posted version.
• Added the BidBuy interoperability sample.
• Made DateSerializer.unmarshall(...) a little more lenient so that it handles parsing dates with and without milliseconds specified.
• Added a Troubleshooting table, and a link to it from the front page.
• Added an Interoperability section to the User's Guide.
• Added a Migration section to the User's Guide.
• Fixed a bug in StatelessEJBProvider and StatefulEJBProvider where the respEncStyle was being set, but not used.
• In RPCRouterServlet.doGet(...) and MessageRouterServlet.doGet(...), moved res.setContentType(...) call before res.getWriter() call to be in compliance with Servlet spec.
• Added install docs for iPlanet.

• Added Message Handling Support
• Added configurable error handling mechanism
• Added pluggable provider support
• Added client-side HTTPS support
• Added HTTP proxy support
• Added HTTP basic authentication support
• Added support for SOAP Messages with Attachments
• Introduced SOAPContext
• Added support for transport hooks
• Added SSL support
• Reduced dependency on xsi:type for deserialization
• Added soap configuration file
• Added pluggable configuration manager
• Added support for international character sets
• Added support for default serialization/deserialization of:
• Hashtable (as xmlsoap:Map)
• Date (as xsd:timeInstant)
• GregorianCalendar (as xsd:date)

• Deprecated the rpcrouter.jsp in favor of an RPCRouter servlet.
• Steven J. McDowall, Noor Zaman, Sanjiva Weerawarana

• Switched the stockquote demo's provider from www.i3solutions.com to www.xmltoday.com.
• Sam Ruby

• Restructured documentation.
• Sanjiva Weerawarana

• The serializer for java.lang.String now runs its content through Utils.cleanString(...) to escape necessary characters.
• Matthew J. Duftler

• Added a distribution containing the source.
• Matthew J. Duftler

• Created a new 'soap' webapp. Provides access to the web-based admin client, and the rpcrouter servlet.
• Sanjiva Weerawarana

• Changed remaining IBM-SOAP references to Apache-SOAP.
• Wouter Cloetens, Mike Paolini, Matthew J. Duftler

• Added a serializer for Vectors and Enumerations.
• Glen Daniels

• Removed trailing '/' in XSD and XSI namespace URIs.
• Steven J. McDowall

• The unmarshalling logic in Fault will now accept the SOAP-ENV namespace URI in addition to the old accepted behavior of no namespace URI at all, when processing subelements of Fault.
• Steven J. McDowall, Matthew J. Duftler

• HTTPUtils.post(...) will now use port 80 if no port is specified.
• Steven J. McDowall

• Fixed a bug that occurred when a ServiceManagerClient was instantiated and used to make several invocations. The problem was: when there were no params, the params property of the Call object was not being set to null.
• Peter Brittenham, Matthew J. Duftler

• Added getAttributeNS(...) to DOMUtils. It has similar behavior to DOMUtils.getAttribute(...). DOMUtils.getAttributeNS(...) will return null if there is no specified or default attribute value.
• Matthew J. Duftler

• Fixed HTTP code to use \r\n instead of println for line endings.
• Kevin J. Mitchell

• An array of bytes (i.e. byte[]) will now be serialized into a SOAP-ENC:base64 type. A SOAP-ENC:base64 type will also now be deserialized into a byte array (i.e. byte[]).
• Matthew J. Duftler, Sanjiva Weerawarana

• Removed extraneous references to BML namespace URI from deploy.jsp.
• Sanjiva Weerawarana

• Created initial code base from IBM-SOAP.

I have composed this list of questions partly from my own learning process and partly by perusing questions from the SOAP User mailing list. Corrections and suggestions for new questions are always welcome. Please forward new questions - preferably with answers! - or errors to the SOAP Developer mailing list.

See also:

• Messaging: The transport part of the XML puzzle by Gordon Van Huizen.
• XML Protocol Comparisons produced by the W3C.
• Also see the SOAP FAQ maintained by Developmentor.
• A Quick-Start Guide for Installing Apache SOAP by XMethods.
• Jonathan Chawke's SOAP FAQ which will eventually be merged with this FAQ and hosted on the Apache SOAP web-site.
• SOAP and SMTP FAQ by Jonathan Chawke.
• Apache SOAP and WebLogic 6.1Beta by Steve Livingston.
• Some info on RPC response encoding styles by Matthew J. Duftler and Dirck Hecking.

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.

Table of Contents

1. 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!

2. 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?

3. 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?

4. 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?

5. 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?

6. 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?

7. 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?

8. 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?

9. 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.

Jonathan Chawke, 9th March 2001.

This document provides an explanation of:

1. How Apache provides it's SMTP transport for SOAP
   
2. How to set up Apache SOAP on a server so that it can service requests via SMTP.
3. How to write a client that makes a SOAP invocation using e-mail (a combination of SMTP and POP).

This document assumes that you have already installed Apache SOAP [http://xml.apache.org/soap/index.html] onto a Tomcat [http://jakarta.apache.org/tomcat/index.html] 3.2 JSP/Servlet container.
Before attempting to service SMTP SOAP messages, ensure that your installation is correctly configured for HTTP SOAP (i.e. the SOAP sample applications work over HTTP!).

SOAP: a Transport-independent Protocol

The writers of the SOAP 1.1 protocol [http://www.w3.org/TR/SOAP/] note that: 'SOAP can potentially be used in combination with a variety of other protocols; however, the only bindings defined in this document describe how to use SOAP in combination with HTTP and HTTP Extension Framework'.
One of the nice things about SOAP is that it isn't restricted to a particular transport layer. Most - if not all - implementations are currently using HTTP to transport SOAP messages, but there is no reason why you can’t use other layers, such as SMTP. The Apache SOAP distribution includes classes which permit the servicing of SOAP requests using e-mail. It does this using a combination of SMTP [http://www.freesoft.org/CIE/RFC/821/] and POP [http://www.freesoft.org/CIE/RFC/1725/]. A class called SMTP2HTTPBridge must be running in a separate JVM on the server. As the name suggests, this class operates as a bridge, mapping requests between HTTP and SMTP. Strictly speaking, this is not an independent SMTP transport - what it really does is convert e-mail SOAP messages to and from HTTP SOAP messages.

Running the Apache SOAP SMTP Bridge (Server)

1. Ensure that the machine you are using is running POP3 and SMTP services (or can access another machine that provides them). Note that the scripts shown below assume that a POP3 service is running locally.
2. Download the POP3 and SMTP jar files from the Apache SOAP web site (currently they are here: http://www.apache.org/dyn/closer.cgi/ws/soap/). Note that these are IBM (and not Sun) jars, and they are also available from IBM at http://www.alphaworks.ibm.com/ab.nsf/techreqs/SMTP and http://www.alphaworks.ibm.com/ab.nsf/techreqs/POP3, respectively. The SMTP bridge software uses these classes to send and receive e-mail messages.
3. Ensure that the POP3 and SMTP jar files (pop3.jar and smtp.jar) are included in your classpath.
4. Create a new account (e.g. soaprouter) under which the SOAP bridge will execute. This makes life easier in the long term, and avoids filling your mail box with loads of XML messages!
5. The Apache SOAP distribution includes a class that maps requests between HTTP and SMTP. Login to the new account and launch this Java class - it’s called org.apache.soap.server.SMTP2HTTPBridge. Don’t forget to include the pop3.jar and smtp.jar in your classpath or it won’t work! A sample (Unix) shell script to launch the class is provided here:

#!/bin/sh # # Launch Apache SOAP SMTP Bridge # # classpath to use for soap smtp SOAPCP="/usr/local/jakarta/jars/xerces.jar:/usr/local/jakarta/jars/soap.jar" # add mail libs that the bridge requires SOAPCP="/usr/local/jakarta/soap/lib/pop3.jar:/usr/local/jakarta/soap/lib/smtp.jar:$SOAPCP"   # Usage: java org.apache.soap.server.SMTP2HTTPBridge polldelay \ # pop3host pop3login pop3passwd httpurl smtphostname # polldelay number of millisec to sleep between polls # pop3host hostname of the POP3 server # pop3login login ID of POP3 account # pop3passwd POP3 account password # routerURL http URL of SOAP router to bridge to # smtphostname SMTP server host name polldelay=30000 # run every 30 seconds (for testing) pop3host=localhost # assume pop3 server is running on local host pop3login=$USER # assume we are running in a dedicated soap bridge account pop3passwd=secret # pop3 password for soap bridge goes here # soap server url goes here (we assume its local) routerURL=http://localhost:8080/soap/servlet/rpcrouter smtphostname=yourmailserver # your outgoing mail server's name goes here # run the bridge! echo Running the SOAP Bridge using classpath: $SOAPCP java -classpath $SOAPCP org.apache.soap.server.SMTP2HTTPBridge $polldelay $pop3host $pop3login $pop3passwd $routerURL $smtphostname

6. If all goes well, you should (periodically) see something like this:

SMTP2HTTPBridge: Polling for messages ..
Status update:  Contacting host: localhost...
Status update: Host contacted, sending login information..
Status update: No new messages on server.
 

Running an Apache SOAP Client using SMTP

1. Setup a new e-mail account on a server that provides a POP3 service. This account will be used to retrieve responses to SOAP requests. You could use an existing e-mail account, but it’s probably better to use a dedicated account.
2. Find an existing SOAP client that makes invocations over HTTP, and make a copy of the code. We’ll modify the client to use SMTP instead of HTTP.
3. The first modification is the transport; instead of using the ‘standard’ HTTP transport (org.apache.soap.transport.SOAPHTTPConnection), we need to use an SMTP one.
4. We need a number of new parameters so that we can (i) send our SOAP request to the appropriate location as an e-mail message and (ii) check our e-mail account for a response to our request:

// name of out-going mailserver
String smtpserver = "outgoingmailserver";	
String popserver = "popservername";	// name of incoming mail server
// pop account to use for From field and to check for response 
String poplogin = "soapresponse";   
String poppasswd = "secret";		// password
String fromaddress = poplogin + "@" + popserver;
			
SOAPTransport ss = new org.apache.soap.transport.smtp.SOAPSMTPConnection(
			/* from/replyto address */ fromaddress,
			/* subject */ "SOAP SMTP Request (TEST)",
			/* smtpServer */ smtpserver,
			/* popPollDelay in millis */ 30000,
			/* popServer */ popserver,
			/* popLogin */ poplogin,
			/* popPassword */ poppasswd
);

5. The next modification we make is to the URL that is used for the request. Instead of creating a http:// URL, we create a mailto: URL (warning: the mailto: protocol handler is not directly supported by the Microsoft Java SDK - you need some classes that are in Sun’s JDK). The address used in the URL should be the name of the account used by the SOAP SMTP bridge application (e.g. the soaprouter account described in the previous section):

	URL url = new URL("mailto:soaprouter@soapserver.yourdomain.com");	

6. Setup a new call and tell it to use our SMTP transport instead of HTTP:

	// build the call
	org.apache.soap.rpc.Call call = new Call();
	call.setSOAPTransport(ss);	// use smtp transport instead of http

The rest of the SMTP SOAP client code should be the same as HTTP SOAP client code. Note that there is a sample application called GetQuoteSMTP.java in samples/stockquote which demonstrates a SOAP SMTP client.

SOAP

• The SOAP Protocol: http://www.w3.org/TR/SOAP/.
• Apache SOAP: http://xml.apache.org/soap/.

Post Office Protocol (POP)

• rfc1725 - POP3 - Post Office Protocol version 3 [http://www.freesoft.org/CIE/RFC/1725/]
• rfc1082 - POP3 - Extended Service Offerings [http://www.freesoft.org/CIE/RFC/1082/]
• rfc1734 - POP3 - AUTHentication command [http://www.freesoft.org/CIE/RFC/1734/]

Since the SOAP specification does not describe how to specify what encodingStyle to use for the response to an RPC request, Apache SOAP's RPCJavaProvider employs a simple algorithm to choose an appropriate encodingStyle.

First, the method call element is examined for an encodingStyle attribute. If there is no encodingStyle attribute on the call element, each parameter element is then examined in document order for encodingStyle attributes. The value specified in the first encodingStyle attribute encountered is used. If none of the parameter elements have an encodingStyle attribute, SOAP Encoding (section 5 of the SOAP specification) is used.

Put another way, if the call element specifies an encodingStyle, it is used for the response. If the call element does not specify an encodingStyle, the first parameter element-specified encodingStyle is used. If none of the parameter elements specify an encodingStyle, or if there are no parameter elements, SOAP Encoding is used by default.

Let's work through a couple of examples by answering several common questions:

Question: How do I tell an Apache SOAP server (using the RPCJavaProvider; i.e. provider type="java" in the deployment descriptor) to use literalXML encodingStyle for the response to my RPC request?

Answer: Simply set the desired response encodingStyle as the encodingStyle of the call object:

    // Build the call.
    Call call = new Call();

    ... configure the call (i.e. targetObjectURI, methodName,
        typeMappings, etc.) ...

    call.setEncodingStyleURI(Constants.NS_URI_LITERAL_XML);

    ... make the invocation and cast the value carried in the return
        parameter to an org.w3c.dom.Element ...
    

Note: See samples.addressbook.GetAllListings for a complete example.

Question: How do I tell an Apache SOAP server (using the RPCJavaProvider; i.e. provider type="java" in the deployment descriptor) to use literalXML encodingStyle for the response to my RPC request, and still send parameters using SOAP encoding?

Answer: Set the desired response encodingStyle as the encodingStyle of the call object, and set each parameter's encodingStyle individually:

    // Build the call.
    Call call = new Call();

    ... configure the call (i.e. targetObjectURI, methodName,
        typeMappings, etc.) ...

    call.setEncodingStyleURI(Constants.NS_URI_LITERAL_XML);
    Vector params = new Vector();
    // A simple type...
    params.addElement(new Parameter("quantity",
                                    int.class,
                                    new Integer(123),
                                    Constants.NS_URI_SOAP_ENC));
    // A complex (user-defined) type...
    params.addElement(new Parameter("address",
                                    Address.class,
                                    addr,
                                    Constants.NS_URI_SOAP_ENC));
    call.setParams(params);

    ... make the invocation and cast the value carried in the return
        parameter to an org.w3c.dom.Element ...
    

Authors: Matthew J. Duftler and Dirck Hecking