duftler 01/05/23 08:31:57
Added: targets/soap/faq faq_chawke.txt faq_chawke_smtp.html
index.html
Log:
Revision Changes Path
1.1 xml-site/targets/soap/faq/faq_chawke.txt
Index: faq_chawke.txt
===================================================================
======================
APACHE-SOAP USER'S FAQ
======================
TABLE OF CONTENTS
=================
1. HOT TOPICS
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"
2. GENERAL
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 good books on SOAP?
2.5. What other SOAP implementations are available?
2.6. How do I tell my Apache SOAP client to use a proxy server?
2.7. How do I perform Proxy Authentication with my Apache SOAP client?
2.8. How do I use TcpTunnel and TcpTunnelGUI?
2.9. How do I use SOAP over SSL?
2.10. How do I use SOAP over SMTP?
2.11. What products are available that will let me use ASP or Perl as SOAP
client?
2.12. I'd like to write a SOAP client as a Java applet. Are there any
'tiny' SOAP client libraries I could use?
2.13. Where do I find nightly builds of the POP3 and SMTP beans?
2.14. Can a SOAP server maintain session between multiple client
invocations?
2.15. How do I use a String array as a parameter to a SOAP service?
2.16. Is there a way to generate SOAP stub/skeleton from deployment
descriptor?
2.17. Is there a way to generate SOAP deployment descriptor from IDL?
2.18. Is there any way of specifying a timeout for a SOAP method
invocation?
2.20. What is the best way to send a large file (>10Mb) with a soap
request?
2.21. Help! I got the following error message: "SOAP Service Manager:
Unable to read 'DeployedServices.ds': assuming fresh start"
2.22. How can I generate a WSDL file for my SOAP service?
2.23. Is there a tool that can validate WSDL?
2.25. Is it possible to pass parameters to the constructor in a SOAP
application ?
2.26. How do I write a SOAP service that maintains state across a session?
2.27. Where can I find the WSDL specification document?
3. INSTALLATION
3.0. Can I install Apache-SOAP 2.1 on Tomcat 4.0 beta?
3.1. How do I install Apache-SOAP on Tomcat?
3.2. How do I install Apache-SOAP on Bea WebLogic 6.0?
3.3. How do I install Apache-SOAP on Resin?
3.4. How do I install Apache-SOAP on IBM WebSphere?
3.5. How do I install Apache-SOAP on Bluestone?
3.6. How do I install Apache-SOAP on Orion?
3.7. How do I install Apache-SOAP on Apache-JServ?
3.8. How do I install Apache-SOAP on iPlanet?
3.10. How do I install Apache-SOAP on Unify's ServletExec?
4. TROUBLESHOOTING
4.2. Help! Visual Age can't compile SOAP - it says I'm missing package
com.ibm.xmi.job.*
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"
5. SOAP AND .NET
5.3. 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".
QUESTIONS AND ANSWERS
=====================
1. HOT TOPICS
Q1.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.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 it is the FIRST entry in your classpath.
Q1.2. Help! I'm getting this error: "Unable to resolve namespace URI for
'xsd'".
Ensure that:
(a) You are using Xerces 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.
Q1.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.
Q1.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.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.
Q1.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.
2. GENERAL
Q2.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).
Q2.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/.
Q2.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.perfectxml.com/articles/xml/hellosoap.asp
http://www.javapro.com/upload/free/features/javapro/2001/04apr01/prs0104/prs0104-1.asp
http://www.soaplite.com/#LINKS
http://www.xmethods.com/gettingstarted/apache.html
Q2.4. Are there any good books on SOAP?
See http://www.soaprpc.com/books/.
Q2.5. 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.
Q2.6. 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);
Q2.7. 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");
Q2.8. 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.
Q2.9. 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
Q2.10. How do I use SOAP over SMTP?
See the Apache-SMTP FAQ, available in the soap user mail archives:
http://marc.theaimsgroup.com/?l=soap-user&m=98692249417026&q=p3
Q2.11. 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/.
Q2.12. 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
design, see: http://www.extreme.indiana.edu/soap/.
Q2.13. Where do I find nightly builds of the POP3 and SMTP beans?
You'll find them here: http://www.alphaworks.ibm.com/ab.nsf/.
Q2.14. Can a SOAP server maintain session between multiple client
invocations?
It does now! 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.
Q2.15. How do I use a String array as a parameter to a SOAP service?
<xsd:complexType name="ArrayOfString">
<xsd:complexContent>
<xsd:restriction base="SOAP-ENC:Array">
<xsd:attribute ref="SOAP-ENC:arrayType"
wsdl:arrayType="xsd:string[]" />
</xsd:restriction>
</xsd:complexContent>
</xsd:complexType>
NOTE: IBM's WSTK doesn't currently support arrays.
Q2.16. Is there a way to generate SOAP stub/skeleton from deployment
descriptor?
Yes, you can use the IBM alphawork WSTK toolkit:
http://www.alphaworks.ibm.com/tech/webservicestoolkit.
Q2.17. Is there a way to generate SOAP deployment descriptor from IDL?
It could make more sense to transform IDL to WSDL otherwise you will lose
information regarding the syntax of method calls if you use
directly the SOAP deployment descriptor.
Q2.18. 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);
Q2.20. What is the best way to send a large file (>10Mb) with a soap
request?
As a MIME attachment. Note that this will use a lot of memory, because the
entire file is read into memory before it is sent.
Q2.21. 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.
Q2.22. 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.alphaworks.ibm.com/tech/webservicestoolkit/.
You could also consider using GLUE, which includes a command line tool for
static generation of WSDL: http://www.themindelectric.com/.
Q2.23. 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/.
Q2.25. 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.
Q2.26. 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.
Q2.27. Where can I find the WSDL specification document?
The WSDL specification document is available at
http://www.w3.org/TR/wsdl.
3. INSTALLATION
Q3.0. Can I install Apache-SOAP 2.1 on Tomcat 4.0 beta?
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.
Q3.1. How do I install Apache-SOAP on Tomcat?
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.com have a good tutorial which includes setup information:
http://www.xmethods.com/gettingstarted/apache.html
Q3.2. 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.
Q3.3. 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).
Q3.4. How do I install Apache-SOAP on IBM WebSphere?
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.
Q3.5. 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
Q3.6. How do I install Apache-SOAP on Orion?
Have a look here:
http://marc.theaimsgroup.com/?l=soap-dev&m=97678072329144&q=p3
Q3.7. How do I install Apache-SOAP on Apache-JServ?
Here are some instructions:
http://marc.theaimsgroup.com/?l=soap-user&m=98890652006035&w=2.
Q3.8. How do I install Apache-SOAP on iPlanet?
See Erik Onnen's article here:
http://marc.theaimsgroup.com/?l=soap-user&m=98753020626284&q=p3.
Q3.10. How do I install Apache-SOAP on Unify's ServletExec?
See http://marc.theaimsgroup.com/?l=soap-user&m=97741067209680&w=2
4. TROUBLESHOOTING
Q4.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.*
Q4.7. Help! I'm using Tomcat+SOAP on Linux. When I try to access the SOAP
admin page, Tomcat crashes and I see this message: "HotSpot Virtual Machine
Error, Unexpected Signal 11"
This may be related to a jdk1.3 bug on linux; try
- using jdk1.2
- using the -server or -client option on the jdk1.3 JVM
5. SOAP AND .NET
Q5.3. 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.
1.1 xml-site/targets/soap/faq/faq_chawke_smtp.html
Index: faq_chawke_smtp.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd";>
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=windows-1252">
<style type="text/css">
<!--
H1 { font-family : Arial, Helvetica; font-size : 14pt }
H2 { font-family : Arial, Helvetica; font-style: italic; font-size :
12pt }
H3 { font-family : Arial, Helvetica; font-size : 10pt }
CODE { font-family : Courier New, Courier; font-size : 9pt; color :
#0000ff }
PRE { font-family : Courier New, Courier; font-size : 9pt; color :
#0000ff }
-->
</style>
<TITLE>Making Apache SOAP Invocations using SMTP</TITLE>
<META NAME="subject" CONTENT="Apache SOAP and SMTP">
</HEAD>
<BODY LINK="#0000ff" VLINK="#800080">
<H1>Making Apache SOAP Invocations using SMTP</H1>
<H3><A HREF="mailto:[EMAIL PROTECTED]">Jonathan Chawke</A>, 9th March
2001.</H3>
<H2>Introduction</H2>
This document provides an explanation of:
<OL TYPE="a">
<LI>How Apache provides it�s SMTP transport for SOAP<br>
<LI>How to set up Apache SOAP on a server so that it can service requests via
SMTP.</LI>
<LI>How to write a client that makes a SOAP invocation using e-mail (a
combination of SMTP and POP).</LI></OL>
<H2>Assumptions</H2>
This document assumes that you have already installed Apache SOAP [<A
HREF="http://xml.apache.org/soap/index.html";>http://xml.apache.org/soap/index.html</A>]
onto a Tomcat [<A
HREF="http://jakarta.apache.org/tomcat/index.html";>http://jakarta.apache.org/tomcat/index.html</A>]
3.2 JSP/Servlet container.
<BR>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!).
<H2>SOAP Over SMTP</H2>
<H3>SOAP: a Transport-independent Protocol</H3>
</B>The writers of the SOAP 1.1 protocol [<A
HREF="http://www.w3.org/TR/SOAP/";>http://www.w3.org/TR/SOAP/</A>] note that:
'<I>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</I>'.
<br>
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.
<H2>Apache SOAP Provides an SMTP Transport</H2>
The Apache SOAP distribution includes classes which permit the servicing of
SOAP requests using e-mail. It does this using a combination of SMTP [<A
HREF="http://www.freesoft.org/CIE/RFC/821/";>http://www.freesoft.org/CIE/RFC/821/]</A>
and POP [<A
HREF="http://www.freesoft.org/CIE/RFC/1725/";>http://www.freesoft.org/CIE/RFC/1725/</A>].
A class called <CODE>SMTP2HTTPBridge</CODE> 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.
<H3>Running the Apache SOAP SMTP Bridge (Server)</H3>
<OL TYPE="a">
</B>
<LI>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.</LI>
<LI>Download the POP3 and SMTP jar files from the Apache SOAP web site
(currently they are here: <A
HREF="http://xml.apache.org/dist/soap/";>http://xml.apache.org/dist/soap/</A>).
The SMTP bridge software uses these classes to send and receive e-mail
messages.</LI>
<LI>Ensure that the POP3 and SMTP jar files (<CODE>pop3.jar</CODE> and
<CODE>smtp.jar</CODE>) are included in your classpath.</LI>
<LI>Create a new account (e.g. <CODE>soaprouter</CODE>) 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!</LI>
<LI>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 <CODE>org.apache.soap.server.SMTP2HTTPBridge</CODE>. Don�t forget to
include the <CODE>pop3.jar</CODE> and <CODE>smtp.jar</CODE> in your classpath
or it won�t work! A sample (Unix) shell script to launch the class is provided
here:</LI>
<table>
<tr><td><PRE>
#!/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
<br>
# 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
</PRE>
</td></tr>
</table>
<LI>If all goes well, you should (periodically) see something like this:</LI>
<PRE>SMTP2HTTPBridge: Polling for messages ..
Status update: Contacting host: localhost...
Status update: Host contacted, sending login information..
Status update: No new messages on server.
</PRE>
</OL>
<B><H3>Running an Apache SOAP Client using SMTP</H3>
<OL TYPE="a">
</B><LI>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.</LI>
<LI>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.</LI>
<LI>The first modification is the transport; instead of using the �standard�
HTTP transport (<CODE>org.apache.soap.transport.SOAPHTTPConnection</CODE>), we
need to use an SMTP one. </LI>
<LI>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:</LI>
<PRE>
// 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
);
</PRE>
<LI>The next modification we make is to the URL that is used for the request.
Instead of creating a <CODE>http://</CODE> URL, we create a
<CODE>mailto:</CODE> URL (warning: the <CODE>mailto:</CODE> 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 <CODE>soaprouter</CODE> account
described in the previous section):</LI>
<PRE>
URL url = new URL("mailto:[EMAIL PROTECTED]"); </PRE>
<LI>Setup a new call and tell it to use our SMTP transport instead of
HTTP:</LI></OL>
<PRE>
// build the call
org.apache.soap.rpc.Call call = new Call();
call.setSOAPTransport(ss);	// use smtp transport instead of http
</PRE>
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 <code>GetQuoteSMTP.java</code>
in <code>samples/stockquote</code> which demonstrates a SOAP SMTP client.
<H2>Further Information</H2>
<H3>SOAP</H3>
<UL>
</B><LI>The SOAP Protocol: <A
HREF="http://www.w3.org/TR/SOAP/";>http://www.w3.org/TR/SOAP/</A>. </LI>
<LI>Apache SOAP: <A
HREF="http://xml.apache.org/soap/";>http://xml.apache.org/soap/</A>.</LI></UL>
<B><H3>Post Office Protocol (POP)</H3>
<UL>
</B><LI>rfc1725 - POP3 - Post Office Protocol version 3 [<a
href="http://www.freesoft.org/CIE/RFC/1725/";>http://www.freesoft.org/CIE/RFC/1725/</a>]</LI>
<LI>rfc1082 - POP3 - Extended Service Offerings [<a
href="http://www.freesoft.org/CIE/RFC/1082/";>http://www.freesoft.org/CIE/RFC/1082/</a>]</LI>
<LI>rfc1734 - POP3 - AUTHentication command [<a
href="http://www.freesoft.org/CIE/RFC/1734/";>http://www.freesoft.org/CIE/RFC/1734/</a>]</LI></UL>
</BODY>
</HTML>
1.1 xml-site/targets/soap/faq/index.html
Index: index.html
===================================================================
<!-- saved from url=(0022)http://internet.e-mail -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd";
>
<html>
<head>
<title>Apache SOAP Frequently Asked Questions (FAQ)</title>
<style type="text/css">
H1 { font-family : Helvetica; font-size : 14pt }
P.faqTopic
{
font-family: Helvetica;
font-size: 12pt;
padding-top:0.25em;
padding-bottom:0.25em;
}
LI.faqQ
{
font-family: Helvetica;
font-size: 9pt
font-weight: bold
}
P.faqA, LI.faqA
{
font-family: Times Roman;
font-weight: normal
}
</style>
</head>
<body>
<h1>Apache SOAP Frequently Asked Questions (FAQ)</h1>
<p class="faqA">
I have composed this list of questions partly from my own learning process
and partly by perusing questions from the
<a href="mailto:[email protected]";>SOAP User</a> mailing list.
Corrections and suggestions for new questions are always welcome. Please
forward new questions - preferably with answers! - or errors to the
<a href="mailto:[email protected]";>SOAP Developer</a> mailing list.
</p>
<p class="faqTopic">See also:</p>
<ul>
<li class="faqA">
<em><a
href="http://www-106.ibm.com/developerworks/library/xml-messaging/";>Messaging:
The transport part of the XML puzzle</a></em>
by Gordon Van Huizen.
</li>
<li class="faqA">
<em><a HREF="http://www.w3.org/2000/03/29-XML-protocol-matrix";>XML Protocol
Comparisons</a></em>
produced by the W3C.
</li>
<li class="faqA">Also see the
<a href="http://www.develop.com/soap/soapfaq.htm";>SOAP FAQ</a>
maintained by Developmentor.
</li>
<li class="faqA">
<em><a href="http://www.xmethods.com/gettingstarted/apache.html";>A
Quick-Start Guide for Installing Apache SOAP</a></em>
by XMethods.
</li>
<li class="faqA">
<em><a href="faq_chawke.txt">Jonathan Chawke's SOAP FAQ</a></em> which will
eventually be merged with
this FAQ and hosted on the Apache SOAP web-site.
</li>
<li class="faqA">
<em><a href="faq_chawke_smtp.html">SOAP and SMTP FAQ</a></em> by Jonathan
Chawke.
</li>
</ul>
<div id="faq_topic_namespaces" class="faqTopic">
<p class="faqTopic">Namespaces</p>
<ul class="faqTopic">
<li id="faq_ns_soap" class="faqQ">What are all these SOAP Namespaces?
<p class="faqA">
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:
</p>
<ol>
<li><code>xmlns:SOAP-ENV="<a
href="http://schemas.xmlsoap.org/soap/envelope/";>http://schemas.xmlsoap.org/soap/envelope/</a>"</code></li>
<li><code>xmlns:SOAP-ENC="<a
href="http://schemas.xmlsoap.org/soap/encoding/";>http://schemas.xmlsoap.org/soap/encoding/</a>"</code></li>
<li><code>xmlns:xsi="<a
href="http://www.w3.org/1999/XMLSchema-instance";>http://www.w3.org/1999/XMLSchema-instance</a>"</code></li>
<li><code>xmlns:xsd="<a
href="http://www.w3.org/1999/XMLSchema";>http://www.w3.org/1999/XMLSchema</a>"</code></li>
</ol>
<p class="faqA">
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.
</p>
<p class="faqA">
The SOAP Envelope
namespace defines the <code>Envelope</code>, <code>Header</code>
and <code>Body</code> element names and the
<code>encodingStyle</code>,
<code>actor</code> and <code>mustUnderstand</code> attributes.
</p>
<p class="faqA">
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.
</p>
<p class="faqA">
The XML Schema Instance namespace defines the <code>type</code>
attribute which identifies the data type of an element.
</p>
<p class="faqA">
The XML Schema namespace defines several datatypes used
as values of the <code>xsi:type</code> attribute. Examples
include: <code>int</code>, <code>String</code>,
<code>double</code>,
and <code>ur-type</code>.
</p>
</li>
<li id="faq_ns_my" class="faqQ">
Do I need to use namespaces on my XML data?
<p class="faqA">
The short answer is yes, but only a little.
</p>
<p class="faqA">
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.
</p>
<p class="faqA">
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
<a href="http://www.w3.org/TR/SOAP";>SOAP specification</a>).
</p>
<p class="faqA">
If you already have one or more namespaces, use them. If you
need to generate a new namespace, use something like
<code>urn://acmecorp.com/whatever/</code> as the URI when you
register an element name. See
<a href="#faq_topic_serialization">Serialization</a> below.
</p>
</li>
<li id="faq_ns_prefix" class="faqQ">
What are all those namespace prefixes in my SOAP messages?
Won't they keep validation from working?
<p class="faqA">
The Apace 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).
</p>
<pre><code>
<SOAP-ENV:Envelope
...xmlns:acme="urn://acmecorp.com/namespace"...>
...
<ns3:GetData xmlns:ns3="urn://acmecorp.com/namespace">
</ns3:GetData>
...
</code></pre>
<p class="faqA">
In this example, the prefix can be "ns3" or "acme". Either way,
it refers to the same namespace and, thus, for any local name,
the same element or attribute.
</p>
</li>
</ul>
</div>
<div id="faq_topic_serialization" class="faqTopic">
<p class="faqTopic">Serialization</p>
<ul class="faqTopic">
<li id="faq_s11n_user_objects" class="faqQ">
How do I send user defined java objects using SOAP?
<p class="faqA">
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).
</p>
<p class="faqA">
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:
</p>
<pre><code>
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 );
</code></pre>
<p class="faqA">
Then, when you deploy the service that you are calling, you must
have a mapping entry that looks something like the following:
</p>
<p class="faqA">
<pre><code>
<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"/>
</code></pre>
</p>
<p class="faqA">
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.
</p>
<p class="faqA">
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.
</p>
<p class="faqA">
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.
</p>
<p class="faqA">
Note, that it is often not necessary to write your own Serializer
or Deserializer. If your class has a get and a set for each attribute
that needs to be marshalled, you can just use the Apache SOAP
BeanSerializer class.
</p>
</li>
<li id="faq_s11n_enc_styles" class="faqQ">
What are the different SOAP encoding styles? Which should I
use?
<p class="faqA">
The Apache SOAP library uses the
<code>SOAP-ENV:encodingStyle</code>
attribute as a lookup qualifier when locating a
<code>Serializer</code>
for a Java object or a <code>Deserialzier</code> for an XML
element.
</p>
<p class="faqA">
The SOAP specification allows the <code>encodingStyle</code>
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
<code>encodingStyle</code>
attribute value as a single URI reference.
</p>
<ol>
<li>SOAP Encoding
<p class="faqA">
This encoding style is identified by the SOAP Encoding
URI
<code>http://schemas.xmlsoap.org/soap/encoding/</code>
and is
described fully in <a
href="http://www.w3.org/TR/SOAP#_Toc478383512";>section 5</a>
of the SOAP specification.
</p>
</li>
<li>XMI Encoding</li>
<li>Literal XML Encoding</li>
</ol>
</p>
</li>
<li id="faq_s11n_date" class="faqQ">
How do you serialize java.util.Date objects?
<p class="faqA">
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.
</p>
<p class="faqA">
Date objects should be converted to <code><a
href="http://www.w3.org/TR/xmlschema-2/#date";>xsd:date</a></code> or
<code><a
href="http://www.w3.org/TR/xmlschema-2/#timeInstant";>xsd:timeInstant</a></code>
to be SOAP compliant. The SOAP spec says, "For simple types, SOAP adopts
all the types
found in the section
<em><a href="http://www.w3.org/TR/SOAP/#_Toc478383514";>Built-in
datatypes</a></em>
of the <em>XML Schema Part 2: Datatypes</em>", but not all have
been implemented.
</p>
</li>
<li id="faq_s11n_literalxml" class="faqQ">
How do you return a DOM Element from an RPC Call?
<p class="faqA">
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:
<pre><code>
...
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 ) );
...
</code></pre>
</p>
</li>
</ul>
</div>
<div id="faq_topic_svchandlers" class="faqTopic">
<p class="faqTopic">Service Handlers</p>
<ul class="faqTopic">
<li id="faq_svc_actor" class="faqQ">
What is an actor?
<p class="faqA">
Every SOAP message has primary intended recipient. An actor is
a
different message recipient that may recieve the message,
and
possibly modify it, before forwarding it on to either the next
actor
or the final, intended recipient.
</p>
<p class="faqA">
SOAP allows <code>Header</code> entries to be addressed to
specific
actors with the <code>SOAP-ENV:actor</code> attribute. This
attribute
contains the URI that uniquely identifies the actor.
</p>
</li>
<li id="faq_svc_tools" class="faqQ">
What tools are available that use Apache SOAP?
<p class="faqA">
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
<a
href="http://www-106.ibm.com/developerworks/library/w-wsdl.html";>specification</a>
and the <a
href="http://www.alphaworks.ibm.com/tech/webservicestoolkit";>IBM toolkit</a>.
</p>
</li>
<li id="faq_svc_samp_install" class="faqQ">
How do I get the samples installed?
<p class="faqA">
For Tomcat: put the soap.jar and samples classes on the system
classpath
(i.e, in $TOMCAT_HOME/classes,lib) rather than in
webapps/soap/WEB-INF
</p>
</li>
<li id="faq_svc_webspere" class="faqQ">
I am having problems configuring SOAP with Webspere!
<p class="faqA">
Apache SOAP has worked under every version of WebSphere from
1.1 to 3.02.
It will, however, work out of the box on WebSphere 3.5 with
fixpak 2 applied.
The WebSphere install instructions for that level are part of
the current
SOAP kit. You can browse them
<a
href="http://xml.apache.org/websrc/cvsweb.cgi/~checkout~/xml-soap/java/docs/install/websphere.html?rev=1.1&content-type=text/html&only_with_tag=MAIN";>online</a>.
Be sure to check the following items:
</p>
<ol>
<li class="faqA">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
<code>http://aaa.bbb.ccc.ddd:port/soap/servlet/rpcrouter</code>.
</li>
<li class="faqA">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).
</li>
</ol>
</li>
<li id="faq_svc_actor" class="faqQ">
Does Apache SOAP work with Microsoft SOAP?
<p class="faqA">
Yes, but 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.
</p>
<p class="faqA">
James Snell has provided a patch adding the typing. It can be
found at
<a
href="http://www.soap-wrc.com/apache_ms_soap_interop.zip";>SOAP-WRC web site</a>.
</p>
</li>
</ul>
</div>
</body>
</html>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
