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/19 17:13:41 UTC

cvs commit: xml-soap/java/docs/guide/images CreatingTypeMappingsButton.gif DeploymentDescriptorsButton.gif UsingTransportHooksButton.gif WritingMessageClientsButton.gif WritingRPCClientsButton.gif ClientAPIButton.gif DeployingServicesButton.gif TransportHooksButton.gif WritingSerializersButton.gif

duftler     01/05/19 08:13:41

  Modified:    java/docs/guide deploy.html intro.html message.html rpc.html
                        serializer.html toc.html
  Added:       java/docs/guide msgclient.html rpcclient.html
               java/docs/guide/images CreatingTypeMappingsButton.gif
                        DeploymentDescriptorsButton.gif
                        UsingTransportHooksButton.gif
                        WritingMessageClientsButton.gif
                        WritingRPCClientsButton.gif
  Removed:     java/docs/guide client.html
               java/docs/guide/images ClientAPIButton.gif
                        DeployingServicesButton.gif
                        TransportHooksButton.gif
                        WritingSerializersButton.gif
  Log:
  1st pass at committing Bill's re-work and update of the User's Guide.
  Submitted by: William Nagy (nagy@watson.ibm.com)
  Reviewed by: Matthew J. Duftler (duftler@us.ibm.com)
  
  Revision  Changes    Path
  1.3       +49 -5     xml-soap/java/docs/guide/deploy.html
  
  Index: deploy.html
  ===================================================================
  RCS file: /home/cvs/xml-soap/java/docs/guide/deploy.html,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- deploy.html	2001/05/17 21:44:43	1.2
  +++ deploy.html	2001/05/19 15:13:37	1.3
  @@ -2,11 +2,11 @@
   <HTML>
   <HEAD>
   <META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux">
  -<TITLE></TITLE>
  +<TITLE>The Apache SOAP Deployment Descriptor</TITLE>
   <LINK rel="stylesheet" href="ait.css">
   </HEAD>
  -<BODY>
  -<H2>The Apache SOAP Deployment Descriptor</H2>
  +<BODY bgcolor="#ffffff">
  +<H2 align="center">Deployment Descriptors</H2>
   <P>Apache SOAP utilizes XML documents called
   &quot;deployment descriptors&quot; to provide
   information to the SOAP runtime about the
  @@ -24,13 +24,15 @@
   will find details about the different types
   of deployment descriptors which may be used
   in this release.</P>
  +<HR>
   <H3>Standard Java Class Deployment Descriptor</H3>
   <P>A deployment descriptor which exposes a service
   which is implemented via a standard Java
   class (including a normal Java Bean) looks
   like the following:</P>
   <PRE>&lt;isd:service xmlns:isd=&quot;http://xml.apache.org/xml-soap/deployment&quot;
  -             id=&quot;urn:<I><STRONG>service-urn</STRONG></I>&quot; [type=&quot;message&quot;]&gt;<BR>  &lt;isd:provider type=&quot;java&quot;<BR>                scope=&quot;Request | Session | Application&quot;<BR>                methods=&quot;<I><STRONG>exposed-methods</STRONG></I>&quot;&gt;<BR>    &lt;isd:java class=&quot;<I><STRONG>implementing-class</STRONG></I>&quot; [static=&quot;true|false&quot;]/&gt;<BR>  &lt;/isd:provider&gt;<BR>  &lt;isd:faultListener&gt;org.apache.soap.server.DOMFaultListener&lt;/isd:faultListener&gt;<BR>&lt;/isd:service&gt;</PRE>
  +             id=&quot;urn:<I><STRONG>service-urn</STRONG></I>&quot; [type=&quot;message&quot;]&gt;<BR>  &lt;isd:provider type=&quot;java&quot;<BR>                scope=&quot;Request | Session | Application&quot;<BR>                methods=&quot;<I><STRONG>exposed-methods</STRONG></I>&quot;&gt;<BR>    &lt;isd:java class=&quot;<I><STRONG>implementing-class</STRONG></I>&quot; [static=&quot;true|false&quot;]/&gt;<BR>  &lt;/isd:provider&gt;<BR>  &lt;isd:faultListener&gt;org.apache.soap.server.DOMFaultListener&lt;/isd:faultListener&gt;
  +&lt;/isd:service&gt;</PRE>
   <P>Where <I><STRONG>service-urn</STRONG></I> is the URN that you want to give to a service,
   <I><STRONG>exposed-methods</STRONG></I> is a space separated list of methods which
   you wish to expose, and <I><STRONG>implementing-class</STRONG></I> is fully qualified class name (i.e. packagename.classname)
  @@ -82,6 +84,48 @@
   the service. If the deployment descriptor
   has the <I>source</I> attribute, then <I><STRONG>source-filename</STRONG></I> refers to the file which contains the service
   implementation.</P>
  -<P>Last updated 5/17/2001 by Bill Nagy &lt;<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>&gt;.</P>
  +<HR>
  +<H3>Specifying Fault Listeners</H3>
  +<P>In all of the examples above, a single fault
  +listener, org.apache.soap.server.DOMFaultListener,
  +has been registered. In reality, any class
  +which implements the interface specified
  +by org.apache.soap.server.SOAPFaultListener
  +may be registered via the &lt;faultListener&gt;
  +element. Multiple fault listeners may be
  +specified by simply adding additional &lt;faultListener&gt;
  +elements. For more information about Apache
  +SOAP fault listeners, look <A href="errors.html">here</A>.</P>
  +<H3>Specifying Type Mappings in a Deployment
  +Descriptor</H3>
  +<P>Type mapping information for RPC services
  +may also be specified in the deployment descriptors.
  +Mappings are specified through the use of
  +a &lt;mappings&gt; element which may optionally
  +appear as a child of the &lt;service&gt;
  +element. Mappings specified in this manner
  +are only available to the service described
  +by the deployment descriptor in which they
  +appear. A deployment descriptor with type
  +mappings looks like the following:</P>
  +<PRE>&lt;isd:service xmlns:isd=&quot;http://xml.apache.org/xml-soap/deployment&quot; id=&quot;...&quot;&gt;
  +  &lt;isd:provider .../&gt;
  +  &lt;isd:faultListener .../&gt;
  +  &lt;isd:mappings&gt;
  +    &lt;isd:map encodingStyle=&quot;<B><I>encoding-uri</I></B>&quot; xmlns:x=&quot;<B><I>qname-namespace</I></B>&quot; qname=&quot;x:<B><I>qname-element</I></B>&quot;
  +             javaType=&quot;<B><I>java-type</I></B>&quot; java2XMLClassName=&quot;<B><I>serializer</I></B>&quot; xml2JavaClassName=&quot;<B><I>deserializer</I></B>&quot;/&gt;
  +    ...
  +  &lt;/isd:mappings&gt;</PRE>
  +<P>Where <B><I>encoding-uri</I></B> is the URI for the encoding method (i.e.
  +http://schemas.xmlsoap.org/soap/encoding
  +for the standard SOAP encoding,) <B><I>qname-namespace</I></B> is the namespace for the XML element, <B><I>qname-element</I></B> is the name of the XML element, <B><I>java-type</I></B> is the fully qualified Java class that you
  +are providing the mapping for (i.e. samples.Date,)
  +<B><I>serializer</I></B> is the fully qualified Java class that implements
  +org.apache.soap.util.xml.Serializer, and
  +<B><I>deserializer</I></B> is the fully qualified Java class that implements
  +org.apache.soap.util.xml.Deserializer. For
  +more information about the Apache SOAP type
  +mapping support, look <A href="serializer.html">here</A>.</P>
  +<P>Last updated 5/18/2001 by Bill Nagy &lt;<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>&gt;.</P>
   </BODY>
   </HTML>
  
  
  
  1.2       +16 -6     xml-soap/java/docs/guide/intro.html
  
  Index: intro.html
  ===================================================================
  RCS file: /home/cvs/xml-soap/java/docs/guide/intro.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- intro.html	2001/01/19 05:19:17	1.1
  +++ intro.html	2001/05/19 15:13:38	1.2
  @@ -1,9 +1,19 @@
  -<html>
  -<body>
  +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  +<html><HEAD>
  +<META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux">
  +<TITLE>User's Guide</TITLE>
  +</HEAD>
  +<BODY bgcolor="#ffffff">
   
  -<h2 align="center">User's Guide</h2>
  -
  -<p>The Apache SOAP User's Guide explains how to use Apache SOAP.</p>
  -
  +<h2 align="center">Introduction</h2>
  +<H3>Welcome to the Apache SOAP User's Guide!
  +</H3>
  +<P>The purpose of this guide is to help you
  +to use both the client-side and server-side
  +functionality provided by the Apache SOAP
  +implementation. While we try to keep this
  +guide up-to-date as much as possible, the
  +best source of information will always be
  +the actual source code.</P>
   </body>
   </html>
  
  
  
  1.2       +60 -6     xml-soap/java/docs/guide/message.html
  
  Index: message.html
  ===================================================================
  RCS file: /home/cvs/xml-soap/java/docs/guide/message.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- message.html	2001/01/19 05:19:17	1.1
  +++ message.html	2001/05/19 15:13:38	1.2
  @@ -1,9 +1,63 @@
  +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   <html>
  -
  -<body>
  -
  -<p><em>Explain how to write a message-oriented service.</em></p>
  -
  +<HEAD>
  +<META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux">
  +<TITLE>Writing Message Services</TITLE>
  +</HEAD>
  +<BODY bgcolor="#ffffff">
  +<H2 align="center">Writing Message Services</H2>
  +<P>Creating message-oriented services in Apache
  +SOAP is a little more complex than creating
  +a simple RPC-based service, but in many cases
  +a message-oriented model provides a better
  +fit to the problem which you are trying to
  +solve. In a message-oriented service, the
  +service implementation is responsible for
  +processing the contents of the SOAP Envelope.
  +That is to say, that while the Apache SOAP
  +API's are still available to interact with
  +the SOAPEnvelope object, the service implementation
  +must invoke those calls which are necessary
  +to extract whatever information from the
  +header and body that are needed for it to
  +process the request. If the message-oriented
  +service is participating in in a request-response
  +protocol which uses SOAP messages in both
  +directions, then it is also responsible for
  +generating the appropriate response SOAPEnvelope.
  +(A message-oriented service does not have
  +to return a SOAPEnvelope, but instead can
  +return anything that it wants.)</P>
  +<P>Because message-oriented services have full
  +control over the SOAP Envelopes, any XML
  +document may be passed as part of the envelope
  +body. When the service receives the SOAP
  +Envelope, it is free to extract the body,
  +and do with it as it pleases.</P>
  +<P>Unlike RPC-service implementations, message-oriented
  +service implementations must all conform
  +to a single interface:</P>
  +<PRE>void <B><I>name</I></B>(SOAPEnvelope <B><I>request-envelope</I></B>, SOAPContext <B><I>request-context</I></B>, SOAPContext <B><I>response-context</I></B>)</PRE>
  +<P>where <B><I>name</I></B> is the name of the method/function, <B><I>request-envelope</I></B> is the SOAPEnvelope containing the incoming
  +message, <B><I>request-context</I></B> is the SOAPContext for the incoming message,
  +and <B><I>response-context</I></B> is the SOAPContext which may be used for
  +a response if one is needed.</P>
  +<P>As with RPC-based service implementations,
  +in a Java based message-oriented service
  +implementation you may throw a SOAPException
  +to indicate that some error has occurred
  +when processing the request. Throwing a SOAPException(FAULT_CODE_CLIENT,
  +...) will allow your service implementation
  +to indicate that the failure was due to a
  +client error, whereas throwing a SOAPException(FAULT_CODE_SERVER,
  +...) will indicate that your service implementation
  +was at fault. (If you throw any other type
  +of exception, the server will catch it, and
  +will pass it on as a SOAPException(FAULT_CODE_SERVER,
  +...)) See the SOAP v1.1 specification for
  +more information on SOAP Faults.</P>
  +<P>Last updated 5/18/2001 by Bill Nagy &lt;<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>&gt;.</P>
   </body>
   
  -<html>
  +
  +</HTML>
  
  
  
  1.2       +58 -6     xml-soap/java/docs/guide/rpc.html
  
  Index: rpc.html
  ===================================================================
  RCS file: /home/cvs/xml-soap/java/docs/guide/rpc.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- rpc.html	2001/01/19 05:19:17	1.1
  +++ rpc.html	2001/05/19 15:13:38	1.2
  @@ -1,9 +1,61 @@
  +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   <html>
  -
  -<body>
  -
  -<p><em>Explain how to write an RPC-oriented service.</em></p>
  -
  +<HEAD>
  +<META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux">
  +<TITLE>Writing RPC Services</TITLE>
  +</HEAD>
  +<BODY bgcolor="#ffffff">
  +<H2 align="center">Writing RPC Services</H2>
  +<P>Writing an RPC-based SOAP service is a very
  +trivial undertaking, and really only involves
  +the following two basic steps:<BR>
  +</P>
  +<OL>
  +  <LI><B>Create a code artifact which is supported
  +  by one of the Apache SOAP providers</B>; either a standard Java class (including
  +  Java Beans,) an EJB, or a BSF supported script.
  +  The code artifact does not have to know anything
  +  about Apache SOAP, as you will simply be
  +  exposing either a method or a script function
  +  that exists within the artifact. For example,
  +  if you create a Java class that has a method
  +  called add(), then you could expose that
  +  method as a SOAP service. Multiple methods
  +  may be exposed for a single service, as is
  +  described in the next section.<BR>
  +  <I>Note that parameters to your method/function
  +  must be serializable by SOAP, and so must
  +  exist within the SOAP mapping registry.</I><I> For information on creating type mappings,
  +  look <A href="serializer.html">here</A>.</I><BR>
  +  <BR>
  +  
  +  <LI><B>Create an Apache SOAP deployment descriptor
  +  for your service.</B> The deployment descriptor provides the implementation
  +  with the information necessary to handle
  +  requests for an offered service. For a Java
  +  service implementation, this will include
  +  such information as the name of the class
  +  which is providing the implementation, as
  +  well as the name of the methods which are
  +  to be exposed. More information about the
  +  deployment descriptors may be found <A href="deploy.html">here</A>.<BR>
  +  
  +</OL>
  +<P>In a Java based service implementation, you
  +may throw a SOAPException to indicate that
  +some error has occurred when processing the
  +request. Throwing a SOAPException(FAULT_CODE_CLIENT,
  +...) will allow your service implementation
  +to indicate that the failure was due to a
  +client error, whereas throwing a SOAPException(FAULT_CODE_SERVER,
  +...) will indicate that your service implementation
  +was at fault. (If you throw any other type
  +of exception, the server will catch it, and
  +will pass it on as a SOAPException(FAULT_CODE_SERVER,
  +...)) See the SOAP v1.1 specification for
  +more information on SOAP Faults.</P>
  +<P>Last updated 5/18/2001 by Bill Nagy &lt;<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>&gt;.</P>
   </body>
   
  -<html>
  +
  +</HTML>
  
  
  
  1.2       +17 -5     xml-soap/java/docs/guide/serializer.html
  
  Index: serializer.html
  ===================================================================
  RCS file: /home/cvs/xml-soap/java/docs/guide/serializer.html,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- serializer.html	2001/01/19 05:19:17	1.1
  +++ serializer.html	2001/05/19 15:13:38	1.2
  @@ -1,9 +1,21 @@
  -<html>
  +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  +<html><HEAD>
  +<META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux"></HEAD>
   
   <body>
  -
  -<p><em>Explain how to write a serializer/deserializer.</em></p>
  -
  +<H2 align="center">Creating Type Mappings</H2>
  +<P>The marshalling/unmarshalling of Java datatypes
  +to/from XML is supported by a type mapping
  +registry (see org.apache.soap.encoding.SOAPMappingRegistry),
  +and serialization (org.apache.soap.util.xml.Serializer)
  +and deserialization (org.apache.soap.util.xml.Deserialization)
  +interfaces that marshallers and unmarshallers,
  +respectively, must implement. The built-in
  +encoders/decoders are simply implementations
  +of these interfaces that are preregistered
  +in the SOAPMappingRegistry. <BR>
  +</P>
   </body>
  +
   
  -<html>
  +</HTML>
  
  
  
  1.7       +8 -7      xml-soap/java/docs/guide/toc.html
  
  Index: toc.html
  ===================================================================
  RCS file: /home/cvs/xml-soap/java/docs/guide/toc.html,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- toc.html	2001/02/05 18:25:34	1.6
  +++ toc.html	2001/05/19 15:13:38	1.7
  @@ -1,17 +1,18 @@
   <html>
     <body>
       <a href="intro.html" target="data"><img src="images/IntroductionButton.gif"></a>
  -    <a href="client.html" target="data"><img src="images/ClientAPIButton.gif"></a>
  -    <a href="config.html" target="data"><img src="images/ServerConfigurationButton.gif"></a>
  +    <a href="rpcclient.html" target="data"><img src="images/WritingRPCClientsButton.gif"></a>
  +    <a href="msgclient.html" target="data"><img src="images/WritingMessageClientsButton.gif"></a>
       <a href="rpc.html" target="data"><img src="images/WritingRPCServicesButton.gif"></a>
       <a href="message.html" target="data"><img src="images/WritingMessageServicesButton.gif"></a>
  -    <a href="serializer.html" target="data"><img src="images/WritingSerializersButton.gif"></a>
  -    <a href="deploy.html" target="data"><img src="images/DeployingServicesButton.gif"></a>
  -    <a href="errors.html" target="data"><img src="images/FaultHandlingButton.gif"></a>
  -    <a href="attachments.html" target="data"><img src="images/UsingAttachmentsButton.gif"></a>
       <a href="manage.html" target="data"><img src="images/ManagingServicesButton.gif"></a>
  +    <a href="deploy.html" target="data"><img src="images/DeploymentDescriptorsButton.gif"></a>
  +    <a href="config.html" target="data"><img src="images/ServerConfigurationButton.gif"></a>
  +    <a href="serializer.html" target="data"><img src="images/CreatingTypeMappingsButton.gif"></a>
  +    <a href="errors.html" target="data"><img src="images/FaultHandlingButton.gif"></a>
       <a href="provider.html" target="data"><img src="images/WritingProvidersButton.gif"></a>
  -    <a href="transhooks.html" target="data"><img src="images/TransportHooksButton.gif"></a>
  +    <a href="attachments.html" target="data"><img src="images/UsingAttachmentsButton.gif"></a>
  +    <a href="transhooks.html" target="data"><img src="images/UsingTransportHooksButton.gif"></a>
       <a href="tools.html" target="data"><img src="images/ToolsButton.gif"></a>
       <a href="../body.html" target="body"><img src="images/GoBackButton.gif"></a>
     </body>
  
  
  
  1.1                  xml-soap/java/docs/guide/msgclient.html
  
  Index: msgclient.html
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  <HTML>
  <HEAD>
  <META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux">
  <TITLE>Writing Message Clients</TITLE>
  </HEAD>
  <BODY bgcolor="#ffffff">
  <H2 align="center">Writing Message Clients</H2>
  </BODY>
  </HTML>
  
  
  
  1.1                  xml-soap/java/docs/guide/rpcclient.html
  
  Index: rpcclient.html
  ===================================================================
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
  <HTML>
  <HEAD>
  <META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux">
  <TITLE>Writing RPC Clients</TITLE>
  <LINK rel="stylesheet" href="ait.css">
  </HEAD>
  <BODY bgcolor="#ffffff">
  <H2 align="center">Writing RPC Clients</H2>
  <P>Writing clients to access SOAP RPC-based
  services is fairly straightforward. Apache
  SOAP provides a client-side API to assist
  in the construction of the SOAP request,
  and then to assist in interpretting the response.
  Conceptually, RPC-based service are relatively
  easy to understand, because the concepts
  involved are those which may be found in
  any procedural based language. To invoke
  a procedure, you need the name of the procedure
  and the parameters to pass to it. When the
  invocation completes, you need to extract
  any response information from the return
  value and/or output parameters.</P>
  <P>The basic steps for creating a client which
  interacts with a SOAP RPC-based service are
  as follows:</P>
  <OL>
    <LI><B>Obtain the interface description of the SOAP
    service, so you know what the signatures
    of the methods that you wish to invoke
    are.</B><BR>
    You can either look at a WSDL file (or
    at
    some other interface definition format)
    for
    the service, or directly at its implementation.<BR>
    <BR>
    
    <LI><B>Create the org.apache.soap.rpc.RPCMessage.Call
    object.</B><BR>
    The Apache SOAP Call object is the main interface
    to the underlying SOAP RPC code<BR>
    .<BR>
    
    <LI><B>Set the target URI into the Call object using
    the setTargetObjectURI(...) method.</B><BR>
    Pass in the URN that the service used to
    identify itself in its <A href="deploy.html">deployment descriptor</A>.<BR>
    <BR>
    
    <LI><B>Set the method name that you wish to invoke
    into the Call object using the setMethodName(...)
    method.</B><BR>
    This must be one of the methods exposed
    by
    the service which is identified by the
    URN
    given in the previous step.<BR>
    <BR>
    
    <LI><B>Create any Parameter objects necessary for
    the RPC call and set them into the Call object
    using the setParams(...) method.</B><BR>
    Make sure that you have the same number of
    parameters with the same types as the service
    is expecting. Parameters must be serialized
    into XML before they can be transmitted,
    and so Apache SOAP provides a number of pre-defined
    serializers/deserializers which are available.
    If you need to transmit a type which has
    not been registered, then you will need to
    <A href="serializer.html">write and register your own serializer/deserializer</A>.<BR>
    <BR>
    
    <LI><B>Execute the Call object's invoke(...) method
    and capture the Response object which is
    returned from invoke(...).</B><BR>
    The invoke(...) method takes in two parameters,
    the first is a URL which identifies the
    endpoint
    at which the service resides (i.e. http://localhost/soap/servlet/rpcrouter)
    and the second is the value to be placed
    into the SOAPAction header. Remember that
    the RPC call is synchronous, and so may
    take
    a while to complete.<BR>
    <BR>
    
    <LI><B>Check the Response object to see if a fault
    was generated using the generatedFault()
    method.</B><BR>
    <BR>
    
    <LI><B>If a fault was returned, retrieve it using
    the getFault(...) method, otherwise extract
    any result or returned parameters using the
    getReturnValue() and getParams() methods
    respectively.</B><BR>
    While most of the providers will only return
    a result, if you have created your own
    provider
    (or obtained one from somewhere else,)
    it
    may also return output parameters.<BR>
    
  </OL>
  <P>Because SOAP is a supposed to be a standard,
  you should be able to use the clients that
  you create with the Apache SOAP API to access
  services running on a different implementations,
  and vice versa.<a name="RPC over SMTP"></a></P>
  <H3>Special Note: Using RPC over SMTP</H3>
  <p>To do RPC over SMTP in Apache-SOAP a certain amount of email
  infrastructure needs to be available. Namely, you need an SMTP
  server, a POP3 server and an email address that you can use to be
  the equivalent of the server-side HTTP router. That is, all SOAP
  RPC calls are sent to a specific address which then processes the
  request somehow and send the result to the sender. To avoid
  duplicating the server-side infrastructure, we have implemented
  the SMTP server-side as a bridge that receives mail sent to the
  SOAP router email address via POP3, posts the SOAP envelope to an
  existing HTTP SOAP infrastructure and sends the response back to
  the sender of the email request via SMTP.</p>
  
  <p>On the client side, the application sends the SOAP request via
  SMTP to the SOAP router email address indicating the address that
  the response should be sent to. Then, it starts polling a POP3
  server to see whether the response has arrived. When it does, the
  envelope is parsed and the respose is extracted. We are using a <a
  href="http://www.alphaworks.ibm.com/aw.nsf/frame?ReadForm&amp;/ab.nsf/techmain/AD8820E9114E5B4488256723000AC87A">POP3
  bean from alphaWorks</a> for the POP3 stuff and that bean does
  not support selective downloading of email. As a result, the
  current implementation relies on the &quot;next message&quot;
  arriving to the client's reply address to be the message
  containing the response to the request. The implication is that
  current implementation does not allow you to make multiple RPC
  calls using the same reply address at the same time.</p>
  
  <p><strong>NOTE</strong>: We <em>strongly</em> recommend against
  using your own email address for testing RPC over SMTP. There are
  many free POP3 email providers on the Web (such as <a
  href="http://www.mailandnews.com">www.mailandnews.com</a>, for
  example) if you are unable to set up multiple POP3 accounts
  yourself.</p>
  
  <P>Last updated 5/19/2001 by Bill Nagy &lt;<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>&gt;.</P>
  </BODY>
  </HTML>
  
  
  
  1.1                  xml-soap/java/docs/guide/images/CreatingTypeMappingsButton.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-soap/java/docs/guide/images/DeploymentDescriptorsButton.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-soap/java/docs/guide/images/UsingTransportHooksButton.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-soap/java/docs/guide/images/WritingMessageClientsButton.gif
  
  	<<Binary file>>
  
  
  1.1                  xml-soap/java/docs/guide/images/WritingRPCClientsButton.gif
  
  	<<Binary file>>