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/21 18:51:54 UTC
cvs commit: xml-soap/java/docs/guide config.html deploy.html errors.html manage.html message.html msgclient.html provider.html rpcclient.html serializer.html tools.html
duftler 01/05/21 09:51:53
Modified: java/docs/guide config.html deploy.html errors.html
manage.html message.html msgclient.html
provider.html rpcclient.html serializer.html
tools.html
Log:
More additions and cleanup of the docs by Bill Nagy. More to come...
Submitted by: Bill Nagy (nagy@watson.ibm.com)
Reviewed by: Matthew J. Duftler (duftler@us.ibm.com)
Revision Changes Path
1.3 +121 -96 xml-soap/java/docs/guide/config.html
Index: config.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/guide/config.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- config.html 2001/01/21 01:18:08 1.2
+++ config.html 2001/05/21 16:51:17 1.3
@@ -1,28 +1,36 @@
+<!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>Configuring the Apache SOAP Server</TITLE>
+</HEAD>
+<BODY bgcolor="#ffffff">
-<body>
-
<h2 align="center">Configuring the Apache SOAP Server</h2>
<h3> Configuration File </h3>
-
-<p> New in version 2.1 is a SOAP server configuration file.
- By default the server will look in
- the current directory for a file called "soap.xml". If a different
- file is to be used, this can be changed by specifying a parameter that
- the transport listener (ie. RPCRouter Servlet) passes along to the
- SOAP server during startup. The transport listener should call the
- static <b>setConfigFilename()</b> method on the <b>ServiceManager</b>
- object before invoking the SOAP server:
-<xmp>
- ServiceManager.setConfigFilename( "d:\\soap\\mysoap.xml" );
-</xmp>
- For HTTP transport listeners, this option can be set in the configuration
- file for the rpcrouter servlet by adding an init-parameter
- called ConfigFile who's value is the location and name of the soap
- configuration file. For example:
-<pre>
- <servlet>
+<P>Configuration information may be passed to
+the Apache SOAP server via an XML-based configuration
+flie. By default, the server will look in
+the current working directory for a file
+called "soap.xml." If a different
+file is to be used, the default path and
+name can be overridden by specifying a parameter
+that the transport listener (i.e. RPCRouterServlet)
+passes along to the SOAP server during startup.
+(All transport listeners should call the
+org.apache.soap.server.ServiceManager's static
+method setConfigFileName(...) before invoking
+the SOAP server.)<BR>
+</P>
+<P>For HTTP transport listeners, this option
+can be set in the configuration file for
+the rpcrouter servlet by adding an init-parameter
+called <I>ConfigFile</I> to the servlet's deployment properties file.
+A servlet deployment properties file with
+this modification would look like the following:<BR>
+</P>
+<pre> <servlet>
<servlet-name>rpcrouter</servlet-name>
<display-name>Apache-SOAP RPC Router</display-name>
<description>no description</description>
@@ -32,120 +40,137 @@
<init-param>
<param-name>faultListener</param-name>
<param-value>org.apache.soap.server.DOMFaultListener</param-value>
- </init-param> <font color="blue">
- <font color="blue"><init-param>
+ </init-param>
+ <init-param>
<param-name>ConfigFile</param-name>
- <param-value>d:\soap\mysoap.xml</param-value>
- </init-param> </font> </font>
- </servlet>
-</pre>
-<p> Currently, only one setting can be specified in this file: the
- <a href="#pcm">pluggable configuration manager </a> to use.
- By default the <b>DefaultConfigManager</b> class is used.
- When services are deployed and undeloyed this class
- will save list of deployed services to a file called
- <b>DeployedServices.ds</b> in the current directory.
- As an option in the configuration file, you can change the location
- of this file by using the "filename" option:
-<pre>
- <!-- Sample Apache SOAP Server Configuration File -->
+ <param-value><B><I>config-file</I></B></param-value>
+ </init-param>
+ </servlet></pre>
+<P>where <B><I>config-file</I></B> is the path (either fully qualified or relative)
+and filename of the SOAP configuration file.<BR>
+</P>
+<p><A name="configfile"></A>There is only one setting currently allowed
+in the SOAP server configuration file: information
+about the <a href="#pcm">pluggable configuration manager</a>. A SOAP server configuration file which
+sets information about the provider would
+look like the following:<pre> <!-- Sample Apache SOAP Server Configuration File -->
<soapServer>
<!-- This section defines the same thing you get if you don't -->
<!-- specify anything at all - aka the default -->
- <configManager value="org.apache.soap.server.DefaultConfigManager" >
- <font color="blue"><option name="filename" value="d:\soap\mylist.ds" /></font>
+ <configManager value="<B><I>config-manager</I></B>" >
+ [<option name="<B><I>option-name</I></B>" value="<B><I>option-value</I></B>"/>]*
</configManager>
- </soapServer>
-</pre>
-
-As state before, if no configuration file is found, or if no configuration
-manager is specified in the file configuration file that is found, then
-the <b>DefaultConfigManager</b> class will be used. And the
-<b>DeployedServices.ds</b> file in the current directory will be used to
-save the list of deployed services.
-
-<a name="pcm"/>
-<hr>
-<h3> Pluggable Configuration Manager </h3>
-
-<p> Simply stated, a configuration manager is responsible for saving the
- current list of deployed services so that when the soap server is
- restarted the services will not need to be redeployed again.
- Configuration managers implement the ConfigManager interface:
-<pre>
-public interface ConfigManager
+ </soapServer></pre>
+<P>where <B><I>config-manager</I></B> is the fully qualified class name of the
+configuration manager which should be used
+by the SOAP server. Additional information
+may be passed to the configuration manager
+through the use of <option> elements,
+with <B><I>option-name</I></B> and<B><I> option-value</I></B> acting as key/value pairs.</P>
+<HR>
+<h3><A name="pcm"/>Pluggable Configuration Manager</A></h3>
+<P>The SOAP configuration manager is responsible
+for saving the current list of deployed services
+to persistent storage, so that when the SOAP
+server is stopped and restarted, the services
+will not need to be redeployed.<BR>
+<BR>
+If no configuration manager is specified
+in the server configuration file, or if the
+specified configuration manager cannot be
+loaded, then the org.apache.soap.server.DefaultConfigManager
+is used. The DefaultConfigManger saves the
+list of deployed services to a file called
+DeployedServices.ds in the current working
+directory (or in the file specified by the
+<option> element in the server configuration
+file,) each time that a service is deployed
+or undeployed. Upon initialization, the DefaultConfigManager
+will attempt to read from this file to restore
+its state information.</P>
+<P>If you want to override the path and/or filename
+of the deployed services storage file for
+the DefaultConfigManager, then your SOAP
+server configuration file would look like
+the following:</P>
+<PRE> <!-- Apache SOAP Server Configuration File -->
+ <soapServer>
+ <configManager value="org.apache.soap.server.DefaultConfigManager">
+ <option name="filename" value="<B><I>config-file</I></B>"/>
+ </configManager>
+ </soapServer></PRE>
+<P>where <B><I>config-file</I></B> is the path (either fully qualified or relative)
+and filename of the deployed services storage
+file.</P>
+<H4>Creating a Configuration Manager</H4>
+<P>If you find that the DefaultConfigurationManager
+is not meeting your needs, then you should
+create your own and use that one instead.
+All configuration managers must implement
+the org.apache.soap.util.ConfigManager interface,
+which is as follows:</P>
+<PRE>public interface ConfigManager
{
- public void setOptions(Hashtable options) throws SOAPException ;
- public void init() throws SOAPException ;
- public void deploy(DeploymentDescriptor dd) throws SOAPException ;
- public String[] list() throws SOAPException ;
+ public void setContext(ServletContext context);
+ public void setOptions( Hashtable options ) throws SOAPException ;
+ public void init() throws SOAPException ;
+ public void deploy( DeploymentDescriptor dd ) throws SOAPException ;
+ public String[] list() throws SOAPException ;
- public DeploymentDescriptor undeploy(String id) throws SOAPException ;
+ public DeploymentDescriptor undeploy( String id ) throws SOAPException ;
public DeploymentDescriptor query(String id) throws SOAPException ;
-}
-</pre>
-
+}</PRE>
+<p>
<b>The methods:</b>
- <blockquote>
+ <blockquote><p>
<code><b>void setOptions(Hashtable options) throws SOAPException</b></code><br>
- This method will be called with a Hasbtable of name/value
- pairs that were specified in the configuration file. In the event of
- an error a SOAPException should be thrown.
- </blockquote>
+This method will be called with a Hasbtable
+of name/value pairs that were specified via
+the <option> elements in the configuration
+file. In the event of an error a SOAPException
+should be thrown.</blockquote><p>
- <blockquote>
+ <blockquote><p>
<code><b>void init() throws SOAPException</b></code><br>
This method will be called after the ConfigManager object is created,
allowing any initializion to be done. For example, reading the
DeployedServices.ds file. In the event of an error a SOAPException
should be thrown.
- </blockquote>
+ </blockquote><p>
- <blockquote>
+ <blockquote><p>
<code><b>void deploy(DeploymentDescriptor dd) throws SOAPException</b></code><br>
This method will be called when a service is deployed (or redeployed).
The service should be added to whatever internal data structure is used
to store the list of services and that list should be persisted so
that if the server is stopped the list can be reloaded upon startup.
In the event of an error a SOAPException should be thrown.
- </blockquote>
-
- <blockquote>
+ </blockquote><blockquote><p>
<code><b>String[] list() throws SOAPException</b></code><br>
This method should return an array of String objects, one for each
deployed service. In the event of an error a SOAPException should be
thrown.
- </blockquote>
+ </blockquote><p>
- <blockquote>
+ <blockquote><p>
<code><b>DeploymentDescriptor undeploy(String id) throws SOAPException</b></code><br>
This method will be called when a service is undeployed. The should should
be removed from whatever internal data structure is used to store the list
and that list should be persisted so that if the server is stopped the
list can be reloaded upon startup. In the event of an error a
SOAPException should be thrown.
- </blockquote>
+ </blockquote><p>
- <blockquote>
+ <blockquote><p>
<code><b>DeploymentDescriptor query(String id)throws SOAPException</b></code><br>
This method should return a DeploymentDescriptor object representing the
metadata about a service. In the event of an error a SOAPException
should be thrown.
- </blockquote>
-
-A user-defined configuration manager may be used by specifying the classname
-in the SOAP configuration file:
-<pre>
- <!-- Sample Apache SOAP Server Configuration File -->
- <soapServer>
- <!-- This section defines the same thing you get if you don't -->
- <!-- specify anything at all - aka the default -->
- <font color="blue"><configManager value="org.mycom.MyMgr" >
- <option name="myopt1" value="myval1" />
- </configManager></font>
- </soapServer>
-</pre>
-
+ </blockquote><p>As is noted in the section <A href="#configfile">above</A>, your configuration manager can be passed
+parameters via <option> elements in
+the SOAP server configuration file.
+<P>Last updated 5/20/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</body>
-<html>
+
+</HTML>
1.4 +12 -7 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.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- deploy.html 2001/05/19 15:13:37 1.3
+++ deploy.html 2001/05/21 16:51:19 1.4
@@ -96,8 +96,8 @@
specified by simply adding additional <faultListener>
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>
+<H3><A name="typemapping">Specifying Type Mappings in a Deployment
+Descriptor</A></H3>
<P>Type mapping information for RPC services
may also be specified in the deployment descriptors.
Mappings are specified through the use of
@@ -111,7 +111,7 @@
<PRE><isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment" id="...">
<isd:provider .../>
<isd:faultListener .../>
- <isd:mappings>
+ <isd:mappings [defaultRegistryClass="<B><I>registry-class</I></B>"]>
<isd:map encodingStyle="<B><I>encoding-uri</I></B>" xmlns:x="<B><I>qname-namespace</I></B>" qname="x:<B><I>qname-element</I></B>"
javaType="<B><I>java-type</I></B>" java2XMLClassName="<B><I>serializer</I></B>" xml2JavaClassName="<B><I>deserializer</I></B>"/>
...
@@ -123,9 +123,14 @@
<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 <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
+org.apache.soap.util.xml.Deserializer. On
+the <mappings> element is an optional
+attribute called <I>defaultRegistryClass</I>, whose value (indicated by <B><I>registry-class</I></B>)is the fully qualified Java class (which
+is a subclass of org.apache.soap.encoding.SOAPMappingRegistry)
+that you wish to use as the default type
+mapping registry. For more information about
+the Apache SOAP type mapping support, look
+<A href="serializer.html">here</A>.</P>
+<P>Last updated 5/20/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</BODY>
</HTML>
1.2 +60 -7 xml-soap/java/docs/guide/errors.html
Index: errors.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/guide/errors.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- errors.html 2001/01/23 18:58:53 1.1
+++ errors.html 2001/05/21 16:51:21 1.2
@@ -1,9 +1,62 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
-
-<body>
-
-<p><em>Explain how to handle errors/faults</em></p>
-
+<HEAD>
+<META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux">
+<TITLE>Fault Handling</TITLE>
+</HEAD>
+<BODY bgcolor="#ffffff">
+<H2 align="center">Fault Handling</H2>
+<P>Occasionally something will go wrong on the
+server side, whether it is due to an errant
+service implementation, a bad client request,
+or perhaps just normal operating difficulties.
+The SOAP specification provides for the communication
+of these errors through the transmittal of
+a SOAP Fault body element within a SOAP Envelope.
+The Apache SOAP server will attempt to capture
+an error state and then construct a SOAP
+Fault message containing a base set of information
+about the error which occurred. However,
+sometimes it is useful to augment the fault
+information for a particular service or to
+perform one or more additional tasks when
+an error state arises. To allow for this
+type of flexibility, the Apache SOAP server
+provides a pluggable fault handling mechanism
+into which one or more fault listeners may
+be registered to process faults. (The pluggable
+fault handling mechanism in Apache SOAP works
+on on the event/listener model.)</P>
+<P>Apache SOAP provides two basic fault handlers:
+</P>
+<UL>
+ <LI>org.apache.soap.server.DOMFaultListener
+ <LI>org.apache.soap.server.ExceptionFaultListner
+</UL>
+<P>Both of these augment the SOAP Fault message
+with additional information about the fault;
+the first by adding a DOM element representing
+the root exception which occurred, and the
+second by wrappering the root exception in
+a Parameter. Most people will probably find
+the first to be more useful.</P>
+<H3>Registering Fault Handlers</H3>
+<P>Fault handlers are registered by including
+one or more <faultListener> elements
+within the deployment descriptor of a service.
+For more information about adding fault handlers
+to the deployment descriptor, look <A href="deploy.html">here</A>.</P>
+<H3>Creating New Fault Handlers</H3>
+<P>Creating a new fault handler is simply a
+matter of creating a Java class which implements
+the org.apache.soap.server.SOAPFaultListener
+interface. The single method which you need
+to implement, fault, takes in a SOAPFaultEvent.
+The SOAPFaultEvent wraps the SOAP Fault and
+SOAP Exception objects which were created
+due to the error. Once you've created the
+fault handler, you'll need to register it
+as indicated above.</P>
+<P>Last updated 5/20/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</body>
-
-<html>
+</HTML>
1.2 +31 -24 xml-soap/java/docs/guide/manage.html
Index: manage.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/guide/manage.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- manage.html 2001/01/19 05:19:17 1.1
+++ manage.html 2001/05/21 16:51:22 1.2
@@ -1,19 +1,24 @@
-<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>Managing Services</TITLE>
+</HEAD>
+<BODY bgcolor="#ffffff">
-<body>
-
<h2 align="center">Managing Services</h2>
-
-<p><em>Needs to be updated for 2.1!</em></p>
-<p>Apache-SOAP provides an administration tool to manage services.
-There are two clients to service manager: an HTML one used via a
+<p>Apache-SOAP provides an administration tool
+to manage services.
+There are two clients to service manager:
+an HTML one used via a
browser and a command-line tool. </p>
-<p>NOTE: If you had previously deployed services to an Apache-SOAP
-server, then this version will not recognize those services
-because the class that was being serialized to represent services
-has changed.</p>
+<p><I>NOTE: If you had previously deployed services
+to an Apache-SOAP server older than v2.0,
+then this version may not recognize those
+services because the class that was being
+serialized to represent services has changed
+since then.</I></p>
<h3>Running the Server Side Admin Tool to Manage Services</h3>
@@ -22,7 +27,7 @@
the list and the definitions of the services deployed on a given
SOAP server. </p>
-<p>Point your browse to <a href="http://hostname:port/soap">http://hostname:port/soap</a>
+<p>Point your browse to <a href="http://hostname:port/soap">http://hostname:port/soap/admin</a>
(see above) and you will get the "Apache-SOAP Admin"
screen with three options:</p>
@@ -82,9 +87,13 @@
</li>
<li><b>Method list. </b>Defines the names of the method that
can be invoked on this service object.</li>
- <li><b>Provider type.</b><strong> </strong>Indicates whether
- the service is implemented using Java or a scripting
- language.</li>
+ <li><b>Provider type.</b><strong> </strong>Indicates whether the service is implemented
+ using Java, a scripting language, or a user-defined
+ provider. If you are using a user-defined
+ provider, then you also need to specify the
+ fully qualified class name of the provider,
+ as well as any options (key/value pairs)
+ that you wish to pass to it.</li>
<li><b>For Java services, Provider class.</b> Fully specified
class name of the target object servicing the request. </li>
<li><b>For Java services, Use static class. </b>If set to<b> </b>"Yes"
@@ -127,19 +136,17 @@
<p>The command line tool is run by typing java org.apache.soap.server.ServiceManagerClient.
Running this yields:</p>
-
-<blockquote>
- <pre><font color="#0000FF">% java org.apache.soap.server.ServiceManagerClient
-Usage: java org.apache.soap.server.ServiceManagerClient url operation arguments
+<PRE>% java org.apache.soap.server.ServiceManagerClient
+Usage: java org.apache.soap.server.ServiceManagerClient [-auth username:password] url operation arguments
where
- url is the Apache-SOAP router's URL whose services are managed
+ username and password is the HTTP Basic authentication info
+ url is the Apache SOAP router's URL whose services are managed
operation and arguments are:
deploy deployment-descriptor-file.xml
list
query service-name
- undeploy service-name</font></pre>
-</blockquote>
-
+ undeploy service-name
+</PRE>
<p>To deploy a service, for example, type:</p>
<blockquote>
@@ -149,6 +156,6 @@
<p>where foo.xml is the deployment descriptor and the URL is
appropriate for your installation.</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 +20 -3 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- message.html 2001/05/19 15:13:38 1.2
+++ message.html 2001/05/21 16:51:23 1.3
@@ -42,6 +42,19 @@
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>If the communications transport which you
+are using supports two-way interaction, such
+as HTTP, then you can use the response context
+to send a response back to the client. If
+you want to send a SOAP Envelope back to
+the client, you can use the org.apache.soap.Envelope's
+marshall(...) method to marshall your envelope
+to a java.io.StringWriter, and then invoke
+the response context's setRootPart(...) method,
+passing the StringWriter as the first argument.
+If you want to send back any other data types,
+then you may need to invoke other methods
+in the response context.</P>
<P>As with RPC-based service implementations,
in a Java based message-oriented service
implementation you may throw a SOAPException
@@ -54,9 +67,13 @@
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 <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
+...)) If your transport supports two-way
+interaction, such as HTTP, then a SOAP Envelope
+containing a SOAP Fault will automatically
+be returned to the client. See the SOAP v1.1
+specification for more information on SOAP
+Faults.</P>
+<P>Last updated 5/20/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</body>
1.2 +92 -0 xml-soap/java/docs/guide/msgclient.html
Index: msgclient.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/guide/msgclient.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- msgclient.html 2001/05/19 15:13:38 1.1
+++ msgclient.html 2001/05/21 16:51:25 1.2
@@ -6,5 +6,97 @@
</HEAD>
<BODY bgcolor="#ffffff">
<H2 align="center">Writing Message Clients</H2>
+<P>Writing clients to access SOAP message-oriented
+services requires that you interact with
+a lower-level set of Apache SOAP APIs than
+you would otherwise have to if you were writing
+a SOAP RPC-based client. However, message-oriented
+services provide you with a finer grain of
+control over what is actually being transmitted
+over SOAP. (In fact, the RPC mechanism is
+built on type of this message-oriented layer.)</P>
+<P>The basic steps for creating a client which
+interacts with a SOAP message-oriented service
+are as follows:</P>
+<OL>
+ <LI><B>Obtain the interface description of the SOAP
+ service, so that you know what the format
+ of the SOAP message should be (i.e. what
+ headers it should have, what the body should
+ look like, etc.) as well as the type of
+ message
+ exchange which will take place.</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.
+ Unlike SOAP RPC, there is no predefined
+ message
+ exchange pattern defined, so a message-oriented
+ service may return a SOAP envelope, may
+ return
+ another type of data, or may return nothing
+ at all.<BR>
+ <BR>
+
+ <LI><B>Construct an org.apache.soap.Envelope which
+ contains the information that the SOAP
+ service
+ requires.</B><BR>
+ At the very least, you will need to add
+ an
+ org.apache.soap.Body object to the envelope.
+ You can optionally add headers as well.<BR>
+ <I>
+ Note: When the message is received on the
+ server, it will be routed to the proper
+ service
+ by looking at the XML Namespace associated
+ with the first child element in the body,
+ and then to the correct method/function
+ within
+ that service via the name of the element
+ itself.</I><BR>
+ <BR>
+
+ <LI><B>Create an org.apache.soap.messaging.Message
+ object.</B><BR>
+ If you need to <A href="attachments.html">add MIME attachments</A> to your message, then you can use addBodyPart(...)
+ method to do so. If you need to send your
+ message over a transport other than HTTP,
+ then you will need to invoke the setSOAPTransport(...)
+ method.<BR>
+ <BR>
+ <LI><B>Invoke the send(...) method on the Message
+ object, providing the URL of the endpoint
+ which is providing the service (i.e. http://localhost/soap/servlet/messagerouter),
+ the actionURI, and your envelope.</B><BR>
+ <BR>
+
+ <LI><B>If your service is returning data, and assuming
+ that the transport supports two-way interaction,
+ then you need to retreive the SOAPTransport
+ object from the Message object (assuming
+ that you don't already have a handle to
+ it)
+ by using the getSOAPTransport() method.
+ You
+ can then invoke the receive() method on
+ the
+ SOAPTransport object to retrieve the returned
+ data.</B><BR>
+ If the service is returning a SOAP Envelope,
+ then you can parse the XML and pass the root
+ element to org.apache.soap.Envelope's unmarshall(..)
+ method to allow it to reconstruct a SOAP
+ Envelope object for you. If an error has
+ occurred on the server during the processing
+ of the request, the server will automatically
+ send back a SOAP Envelope with a SOAP Fault
+ in the body describing what went wrong.
+
+</OL>
+<P>Last updated 5/20/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</BODY>
</HTML>
1.4 +111 -76 xml-soap/java/docs/guide/provider.html
Index: provider.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/guide/provider.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- provider.html 2001/01/21 21:31:52 1.3
+++ provider.html 2001/05/21 16:51:26 1.4
@@ -1,69 +1,95 @@
+<!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 Providers</TITLE>
+</HEAD>
+<BODY bgcolor="#ffffff">
+
+<h2 align="center">Writing Providers</h2>
+<P>When creating services, it makes sense to
+take advantage of legacy programming artifacts
+in order to not have to reinvent the wheel,
+and to program in the language(s) in which
+you are most comfortable. The developers
+of Apache SOAP recognized that not all services
+were going to be methods on Java classes,
+and architected a way to allow any type of
+programming artifact to be used as a service
+implementation. To enable this, a layer of
+abstraction was created between the Apache
+SOAP server and the service implementation.
+This layer is called the Apache SOAP Pluggable
+Provider.</P>
+<P>A pluggable provider acts as the bridge between
+the SOAP engine and the service which is
+being invoked. The provider is responsible
+for:</P>
+<UL>
+ <LI>locating the service implementation
+ <LI>loading the service implementation
+ <LI>invoking the service
+ <LI>converting the result from the service implementation
+ into a SOAP envelope when necessary
+</UL>
+<P>Apache SOAP comes with six predefined providers:</P>
+<UL>
+ <LI>org.apache.soap.providers.RPCJavaProvider<BR>
+ This provider is the default for exposing
+ Java artifacts and BSF-supported scripts
+ via SOAP RPC.
+ <LI>org.apache.soap.providers.MsgJavaProvider<BR>
+ This provider is the default for exposing
+ Java artifacts and BSF-supported scripts
+ via SOAP Messages.
+ <LI>org.apache.soap.providers.StatelessEJBProvider<BR>
+ This provider allows you to expose Stateless
+ Session Beans as services.
+ <LI>org.apache.soap.providers.StatefulEJBProvider<BR>
+ This provider allows you to expose Stateful
+ Session Beans as services.
+ <LI>org.apache.soap.providers.EntityEJBProvider<BR>
+ This provider allows you to expose Entity
+ Beans as services.
+ <LI>org.apache.soap.providers.com.RPCProvider<BR>
+ This provider allows you to expose COM objects
+ via SOAP RPC. <I>Note: This provider works only under Windows.</I> For more information about the COM provider,
+ look <A href="../../samples/com/readme.htm">here</A>.
+</UL>
+<H3>Using Pluggable Providers</H3>
+<P>Information about the provider that you wish
+your service to use is located in the deployment
+descriptor. The <provider> element,
+as well as its descendent elements, provide
+information to the runtime and provider about
+what they should do to make a service accessible.
+The <I>type</I> attribute on the <provider> element
+identifies the Java class which should act
+as the provider. If you are exposing a Java
+class (either as an RPC-based service or
+as a message-oriented service) then you should
+specify "java" as the value for
+this attribute, if you are exposing a BSF-supported
+script then you should specify "script",
+otherwise you should specify the fully qualified
+classname of the provider.</P>
+<P>Additional information to the pluggable providers
+may be specified by adding <option>
+elements as descendents to the <provider>
+elements. For more information about specifying
+pluggable providers and their options, look
+<A href="deploy.html">here</A>.</P>
+<H3>Writing Pluggable Providers</H3>
+<P>If you need to support programming artifacts
+which are not directly supported by one of
+the included providers, or if one of the
+included providers does not quite meet your
+needs, then you will need to create your
+own pluggable provider.</P>
+<P>Providers need to implement the org.apache.soap.util.Provider
+interface, which is as follows:</P>
-<body>
-
-<h2 align="center">Writing Pluggable Provider</h2>
-
-<h3> What Is A Pluggable Provider </h3>
-
-<p> A provider is the bridge between the SOAP engine and the service
- being invoked. The provider is responsible for:
- <blockquote>
- <li>locating the service
- <li>loading the service
- <li>invoking the service
- <li>converting the result from the service into a SOAP envelope
- </blockquote>
- By default the SOAP engine will use the RPCJavaProvider for RPC
- services, and the MsgJavaProvider for Message services. The
- RPCJavaProvider simply loads the appropriate class, invokes the
- desired method and converts any result into a SOAP envelope.
-<p> Pluggable providers were introduced because it was clear that not
- all services would be methods on Java classes. For example, using
- pluggable providers a service could be an executable, or an EJB.
-
-<h3> Using Pluggable Providers </h3>
-
-<p> When deploying a service the <b>type</b> field in the <b>provider</b>
- element is used to denote whether the service is a java method or
- a script that should be passed along to BSF. For example:
-
-<pre>
-<b>DeploymentDescriptor.xml</b>
-<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
- id="urn:xmltoday-delayed-quotes">
- <isd:provider <font color="blue">type="java"</font>
- scope="Application"
- methods="getQuote">
- <isd:java class="samples.stockquote.StockQuoteService"/>
- </isd:provider>
-</isd:service>
-</pre>
- To use a different type of provider simply place the full classname
- in the <b>type</b> attribute:
-<pre>
-<b>DeploymentDescriptor.xml</b>
-<isd:service xmlns:isd="http://xml.apache.org/xml-soap/deployment"
- id="urn:testprovider">
- <isd:provider <font color="blue">type="com.mycom.MyProvider"</font>
- scope="Application"
- methods="myMethod">
- <font color="blue"><isd:java class="com.mycom.MyClass"/>
- <isd:option key="classpath" value="c:\classes" /> </font>
- </isd:provider>
-</isd:service>
-</pre>
- Notice that the <b>java</b> element can still be optionally used if
- your provider needs it. Also, notice that there can optionally be
- <b>option</b> elements that can be used to configure your provider.
- These options will be placed in the <b>props</b> instance variable
- of the deployment descriptor passed into the <b>locate</b> method.
-
-<h3> How To Write A Pluggable Provider </h3>
-
-<p> Providers need to implement the <b>Provider</b> interface:
-<pre>
-public interface Provider {
+<pre>public interface Provider {
public void locate( DeploymentDescriptor dd,
Envelope env,
Call call,
@@ -74,21 +100,30 @@
public void invoke(SOAPContext req, SOAPContext res) throws SOAPException ;
}
</pre>
- The <code>locate</code> method will be called in order to allow the
- provider a chance to verify that the service exists and is available
- to process the request. If an error occurs this method should throw
- a SOAPException. After a successful call to <code>locate</code> the
- SOAP engine will then call <code>invoke</code> to actually call the
- service. Notice that <code>invoke</code> call does not have any
- information about the service, all of that information was passed
- into the <code>locate</code> method so it is the responsibilty of
- <code>locate</code> to save whatever information is needed so that
+ The <code>locate</code> method will be called in order to allow
+the provider a chance to verify that the
+service implementation exists and is available
+to process the request. If an error occurs,
+this method should throw a SOAPException.
+After a successful call to <code>locate</code> the SOAP engine will then execute the <code>invoke</code> method to actually call the service implementation.
+Notice that the <code>invoke</code> call does not have any information about
+the service. All of that information was
+passed into the <code>locate</code> method, so it is the responsibilty of <code>locate</code> to save whatever information is needed so that
<code>invoke</code> can call the service.
<p> The <code>invoke</code> method is also responsible for converting
- any response from the service into a SOAP envelope and placing it
- in the <b>res</b> parameter (a SOAPContext).
+any response from the service implementation
+into a SOAP envelope and placing it in the
+<b>res</b> parameter (a SOAPContext).
+
+<P>If any <option> elements which were
+specified in the deployment descriptor for
+the service are accessible as properties
+via a Hashtable retrieved through a call
+to <B>dd</B>.getProps() in the <CODE>locate</CODE> method.</P>
+<P>Last updated 5/20/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</body>
-<html>
+
+</HTML>
1.2 +2 -3 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.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- rpcclient.html 2001/05/19 15:13:38 1.1
+++ rpcclient.html 2001/05/21 16:51:28 1.2
@@ -26,9 +26,8 @@
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>
+ service, so that 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)
1.3 +132 -16 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- serializer.html 2001/05/19 15:13:38 1.2
+++ serializer.html 2001/05/21 16:51:29 1.3
@@ -1,21 +1,137 @@
<!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>
+<META name="GENERATOR" content="IBM WebSphere Homepage Builder V4.0.0 for Linux">
+<TITLE>Creating Type Mappings</TITLE>
+</HEAD>
+<BODY bgcolor="#ffffff">
<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>
+<P>Apache SOAP uses type mappings to determine
+how Java datatypes should be marshalled to/unmarshalled
+from XML so that they can be transmitted
+on/received from the wire. The type mappings
+are stored in a type mapping registry, with
+the default registry being org.apache.soap.encoding.SOAPMappingRegistry.<BR>
+<BR>
+Each type mapping carries several pieces
+of information: a URI describing the encoding
+style (i.e. http://schemas.xmlsoap.org/soap/encoding/,)
+a qualified name (QName) for the XML element
+(i.e. http://www.w3.org/2001/XMLSchema:int,)
+the Java class to be encoded from/decoded
+to, the name of the Java class to act as
+the serializer, and the name of the Java
+class to act as the deserializer. The Java
+classes acting as serializers/deserializers
+must implement org.apache.soap.util.xml.Serializer
+and org.apache.soap.util.xml.Deserializer,
+respectively.</P>
+<P>To make life a little easier, a set of type
+mappings has been predefined and registered
+into the SOAPMappingRegistry for the SOAP
+encoding style. These include mappings for
+the following Java types:</P>
+<UL>
+ <LI>all Java primitive types, such as int, float,
+ boolean, byte, etc. and their corresponding
+ wrapper classes (i.e. java.lang.Integer,
+ java.lang.Boolean, etc.)
+ <LI>Java arrays
+ <LI>java.lang.String
+ <LI>java.util.Date
+ <LI>java.util.GregorianCalendar
+ <LI>java.util.Vector
+ <LI>java.util.Hashtable
+ <LI>java.util.Map
+ <LI>javax.mail.internet.MimeBodyPart
+ <LI>java.io.InputStream
+ <LI>javax.activation.DataSource
+ <LI>javax.activation.DataHandler
+ <LI>org.apache.soap.util.xml.QName
+ <LI>org.apache.soap.rpc.Parameter
+ <LI>java.lang.Object (a deserializer for null
+ objects only)
+</UL>
+<P>The SOAPMappingRegistry also provides a type
+mapping to encode org.apache.soap.rpc.Parameters
+in the literal XML encoding style, and a
+set of mappings to encode types supported
+by the <A href="http://www.alphaworks.ibm.com/tech/xmiframework">IBM XMI Framework</A> in the XMI encoding style.</P>
+<P>If you want to pass your own objects as parameters
+to SOAP RPC services, then you will need
+to register new type mappings (and possibly
+create your own serializers/deserializers.)
+<I>Remember that you will need to register the
+new type mappings on both the server and
+the client sides.</I></P>
+<H3>Registering Type Mappings on the Server</H3>
+<P>There are two main ways to register type
+mapping information into an Apache SOAP server:</P>
+<OL>
+ <LI>Registering them via the deployment descriptor.
+ <LI>Overriding the default mapping registry with
+ a registry that has your new type mappings
+ pre-registered.
+ </OL>
+<P>The first way is probably the easiest to
+implement and manage, but it does require
+that you replicate the mapping information
+in each deployment descriptor that needs
+it. For more information on registering type
+mapping information via a deployment descriptor,
+look <A href="deploy.html#typemapping">here</A>.</P>
+<P>The second mechanism requires a little more
+work, but allows you to limit the amount
+of additional information that you need to
+put into each deployment descriptor. In addition,
+the same mapping registry may be used on
+the client side, and thus may cut down on
+the amount of additional code that must be
+written for the client. The new registry
+must be a subclass of the SOAPMappingRegistry.
+For information about overriding the default
+mapping registry, look <A href="deploy.html#typemapping">here</A>.</P>
+<H3>Registering Type Mappings on the Client</H3>
+<P>As is the case with the server, on the client
+there are also two main ways to register
+type mapping information:</P>
+<OL>
+ <LI>Create an instance of the SOAPMappingRegistry
+ and use the mapTypes(...) method to add
+ new
+ mappings.
+ <LI>Create an instance of a subclass of the SOAPMappingRegistry
+ that already has your mappings pre-registered.
+</OL>
+<P>The first way is probably the easiest to
+do, but if you have to use the same type
+mappings in multiple different clients or
+if you are also implementing the server-side
+as well, then the second method may save
+you a little bit of coding.</P>
+<H3>The Bean Serializer/Deserializer</H3>
+<P>In many cases, even if there is not a default
+type mapping for the object that you are
+trying to transmit, you still may not need
+to create a new serializer/deserializer.
+Apache SOAP comes with a Java Bean Serializer/Deserializer
+that may suit your needs. The org.apache.soap.encoding.soapenc.BeanSerializer
+can be used to serialize and deserialize
+JavaBeans using the SOAP encoding style.
+The public properties of the bean will become
+named accessors (elements) in the XML form.
+To use the BeanSerializer, simply pass "org.apache.soap.encoding.soapenc.BeanSerializer"
+as the last two parameters when you are registering
+the type mapping for your object.</P>
+<H3>Creating New Serializers and Deserializers</H3>
+<P>If you need to create a new serializer/deserializer,
+then looking at the source code for the predefined
+ones will probably provide you with the best
+guidence. Remember that they will need to
+implement org.apache.soap.util.xml.Serializer
+and org.apache.soap.util.xml.Deserializer
+respectively. You can implement them both
+in the same class, or use two different classes,
+it really makes no difference.</P>
+<P>Last updated 5/20/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</body>
-
-
</HTML>
1.2 +33 -16 xml-soap/java/docs/guide/tools.html
Index: tools.html
===================================================================
RCS file: /home/cvs/xml-soap/java/docs/guide/tools.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tools.html 2001/01/19 05:19:17 1.1
+++ tools.html 2001/05/21 16:51:30 1.2
@@ -1,20 +1,37 @@
+<!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>Tools</TITLE>
+</HEAD>
+<BODY bgcolor="#ffffff">
-<body>
-
-<h2 align="center">Tool for Debugging SOAP</h2>
-
-<p>Apache-SOAP also includes a TCP tunnel / monitor tool that we
-developed to help debug SOAP and other TCP protocols. The class
-org.apache.soap.util.net.TcpTunnelGui can be used to open a port
-on the current machine which basically acts as a tunnel to a
-remote host / port combination. When a connection is made to the
-port, the tunnel in turn makes a connection to the remote host /
-port combination and uses two windows to show the data going from
-each side. Thus, the client wishing to make a connection to a
-remote host/port can be told to connect to the local host / port
-and as a result you can see the data that's flowing between the
-two. This provides a very useful debugging tool. Check it out!</p>
-
+<h2 align="center">Tools</h2>
+<P>As we all know, there are times when things
+never seem to work correctly. While we can't
+eliminate all problems, we can help you to
+determine their cause; at least for problems
+with Apache SOAP.</P>
+<P>In order to debug problems with Apache SOAP,
+it's often useful to see the SOAP messages
+which are travelling back and forth between
+the client and the server. To make that task
+a little easier, we have included a TCP tunnel/monitor
+tool to help debug SOAP (as well as other
+TCP-based protocols.) The GUI-based tool
+will open a port on the machine upon which
+it was started, and will tunnel traffic to
+a remote host/port combination. Inside the
+tool's GUI, you will see two windows which
+show data originating from the client and
+from the server. </P>
+<P>To start the tool up, execute:</P>
+<PRE>java org.apache.soap.util.net.TcpTunnelGui <B><I>listenport</I></B> <B><I>tunnelhost</I></B> <B><I>tunnelport</I></B></PRE>
+<P>where <B><I>listenport</I></B> is the port that you want the tool to listen
+on (i.e. the port which you will send your
+SOAP messages to), <B><I>tunnelhost</I></B> is the hostname of the SOAP server, and
+<B><I>tunnelport</I></B> is the port that the SOAP server is running
+on.</P>
+<P>Last updated 5/20/2001 by Bill Nagy <<A href="mailto:nagy@watson.ibm.com">nagy@watson.ibm.com</A>>.</P>
</body>
</html>