xml-general-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From duft...@apache.org
Subject cvs commit: xml-site/targets/soap/faq faq_chawke.txt faq_chawke_smtp.html index.html
Date Wed, 23 May 2001 15:31:58 GMT
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: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"
  
  &nbsp;
  # 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.
  &nbsp;</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";&#9;
  String popserver = "popservername";&#9;// name of incoming mail server
  // pop account to use for Ďfromí field and to check for response 
  String poplogin = "soapresponse";   
  String poppasswd = "secret";&#9;&#9;// password
  String fromaddress = poplogin + "@" + popserver;
  &#9;&#9;&#9;
  SOAPTransport ss = new org.apache.soap.transport.smtp.SOAPSMTPConnection(
  &#9;&#9;&#9;/* from/replyto address */ fromaddress,
  &#9;&#9;&#9;/* subject */ "SOAP SMTP Request (TEST)",
  &#9;&#9;&#9;/* smtpServer */ smtpserver,
  &#9;&#9;&#9;/* popPollDelay in millis */ 30000,
  &#9;&#9;&#9;/* popServer */ popserver,
  &#9;&#9;&#9;/* popLogin */ poplogin,
  &#9;&#9;&#9;/* 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);&#9;// 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:soap-user@xml.apache.org">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:soap-dev@xml.apache.org">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>
  &lt;SOAP-ENV:Envelope
    ...xmlns:acme="urn://acmecorp.com/namespace"...>
    ...
    &lt;ns3:GetData xmlns:ns3="urn://acmecorp.com/namespace">
    &lt;/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>
  &lt;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: general-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: general-cvs-help@xml.apache.org


Mime
View raw message