Introduction

Thank you for downloading Apache SOAP!

Apache SOAP is an open-source implementation of the SOAP v1.1 and SOAP Messages with Attachments specifications in Java. Apache SOAP is developed by the Apache SOAP community.

Apache SOAP can be used as a client library to invoke SOAP services available elsewhere or as a server-side tool to implement SOAP accessible services. As a client library it provides an API for invoking SOAP RPC services as well as an API for sending and receiving SOAP messages. As a mechanism to write new RPC accessible services or message accessible services, it expects to be hosted by a servlet container (such as Apache Tomcat, for example). While the codebase can be extended to support non-HTTP transports, the provided code only has limited support for non-HTTP transports (specifically, only for SMTP).

If you are new to SOAP and would like to learn more about SOAP and Web services in general, there are many wonderful resources available on the Web. Given below is a woefully incomplete list (in no particular order) of great starting places:

• http://www.xmethods.net
• http://www.webservices.org
• http://www.ibm.com/developerworks/webservices/
• http://msdn.microsoft.com/soap
• http://www.develop.com/soap
• http://www.soapware.org/

For a list of Frequently Asked Questions (and answers to them) please visit http://xml.apache.org/soap/faq.

Requirements & Limitations

Apache SOAP has the following requirements:

• Java 1.2 or higher, and a servlet engine supporting version 2.1 or higher of the Java Servlet API
• A JAXP compatible, namespace aware XML parser
• JavaMail (mail.jar) and the JavaBeans Activation Framework (activation.jar)
• XMI encoding requires use of Java 1.2.2 and XML4J 2.0.15. Your classpath must have xerces.jar first and then xml4j.jar next in that order.
• Implementing services in scripting languages requires the use of Bean Scripting Framework.
• SSL (HTTPS) support requires Java 1.2.1 or later and the Java Secure Socket Extension.
• The SMTP transport requires the SMTP and POP3 Bean Suites.

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

• multiple encoding styles in the encodingStyle attribute (see section 4.1.1 of the spec)
• actor attribute and SOAP intermediaries (4.2.2)
• complete mustUnderstand attribute behavior - only supports checking for and rejecting requests that require mustUnderstand checking (4.2.3)
• element typing by having the name of the element bear a definite relation to the type, that type then determinable from a schema, except for elements named SOAP-ENC:Array (5.1 rule 2c); note specifically that Web Service Definition Language (WSDL) 1.1 is not supported for type determination
• deserialization of null values for XML schema types that are mapped to primitive Java types (5.1 rule 9)
• the complete set of XML schema simple types (5.2)
• multi-dimensional arrays (5.4.2), arrays of arrays (5.4.2), partially transmitted arrays (5.4.2.1), sparse arrays (5.4.2.2)
• root attribute (5.6)
• input/output and output parameters

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.