You are viewing a plain text version of this content. The canonical link for it is here.
Posted to soap-dev@xml.apache.org by du...@apache.org on 2001/05/23 16:57:12 UTC
cvs commit: xml-soap/java/docs/guide attachments.html rpcclient.html transhooks.html
duftler 01/05/23 07:57:11
Modified: java/docs faq.html
java/docs/guide attachments.html rpcclient.html
transhooks.html
Added: java/docs faq_chawke.txt faq_chawke_smtp.html
Removed: java/docs faq_chawke.html
Log:
More updates from Bill, and an additional SMTP FAQ from Jonathan Chawke.
Submitted by: Bill Nagy and Jonathan Chawke
Reviewed by: Matthew J. Duftler
Revision Changes Path
1.4 +4 -1 xml-soap/java/docs/faq.html
Index: faq.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/faq.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- faq.html 2001/05/21 21:25:31 1.3
+++ faq.html 2001/05/23 14:56:52 1.4
@@ -58,8 +58,11 @@
by XMethods.
</li>
<li class="faqA">
-<em><a href="faq_chawke.html">Jonathan Chawke's SOAP FAQ</a></em> which will eventually be merged with
+<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>
1.1 xml-soap/java/docs/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-soap/java/docs/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:j_chawke@hotmail.com">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:soaprouter@soapserver.yourdomain.com"); </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.4 +10 -11 xml-soap/java/docs/guide/attachments.html
Index: attachments.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/guide/attachments.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- attachments.html 2001/05/22 15:05:02 1.3
+++ attachments.html 2001/05/23 14:57:01 1.4
@@ -14,16 +14,15 @@
be nicer just to allow data, such as JPEG
images, WAV files, etc., to be passed along
with the SOAP message, instead of inside
-of it. To address this issue, the SOAP with
-Attachments specification was created. The
-SOAP with Attachments specification allows
-for the embedding of a SOAP message inside
-of a MIME document, in a manner in which
-does not alter the processing rules of the
-message. The specification also describes
-how one refers to the attachments from inside
-the body of the SOAP message. Apache SOAP
-contains an implementation of this specification.</P>
+of it. To address this issue, the <A href="http://www.w3.org/TR/SOAP-attachments">SOAP Messages with Attachments</A> specification was created. The SOAP Messages
+with Attachments specification allows for
+the embedding of a SOAP message inside of
+a MIME document, in a manner in which does
+not alter the processing rules of the message.
+The specification also describes how one
+refers to the attachments from inside the
+body of the SOAP message. Apache SOAP contains
+an implementation of this specification.</P>
<H3>Using Attachments on the Client</H3>
<P>If you are interacting with an RPC-based
service, you may not need to do anything
@@ -70,7 +69,7 @@
URI referring to the Content-Location of
the attachment. (The Content-ID is set as
part of the javax.mail.internet.MimeBodyPart.)</P>
-<P>Last updated 5/22/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
+<P>Last updated 5/23/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</body>
1.5 +3 -0 xml-soap/java/docs/guide/rpcclient.html
Index: rpcclient.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/guide/rpcclient.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- rpcclient.html 2001/05/22 15:05:15 1.4
+++ rpcclient.html 2001/05/23 14:57:03 1.5
@@ -144,6 +144,9 @@
example) if you are unable to set up multiple POP3 accounts
yourself.</p>
+<p>For more information on using Apache SOAP and SMTP please see
+<a href="../faq_chawke_smtp.html">Jonathan Chawke's FAQ</a>.</p>
+
<P>Last updated 5/19/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</BODY>
</HTML>
1.3 +4 -7 xml-soap/java/docs/guide/transhooks.html
Index: transhooks.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/guide/transhooks.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- transhooks.html 2001/05/21 20:19:18 1.2
+++ transhooks.html 2001/05/23 14:57:04 1.3
@@ -17,12 +17,9 @@
extensions in the Apache SOAP framework are
known as Envelope Editors.</P>
<H3>Using Envelope Editors on the Server</H3>
-<P>To enable the transport extensions on the
-server, you need to define a system property
-called org.apache.soap.TransportHookExtension
-(i.e. java -Dorg.apache.soap.TransportHookExtension=1).
-You also need to set an init-parameter called
-<I>EnvelopeEditorFactory</I> in the configuration files for the RPCRouter
+<P>To enable the enveope editor transport extensions
+on the server, you need to set an init-parameter
+called <I>EnvelopeEditorFactory</I> in the configuration files for the RPCRouter
and MessageRouter servlets. The value of
this parameter should be the fully qualified
classname of a Java class which implements
@@ -64,7 +61,7 @@
be sent, respectively.</P>
<P>The class org.apache.soap.transport.EnvelopeEditorAdapter
contains a sample Envelope Editor.</P>
-<P>Last updated 5/21/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
+<P>Last updated 5/23/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</body>