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 sa...@locus.apache.org on 2000/08/03 18:50:43 UTC
cvs commit: xml-soap/java/doc/install index.html
sanjiva 00/08/03 09:50:42
Modified: java/doc/install index.html
Added: java/doc/guide index.html
Log:
more doc mods; committed restructured docs .. now have to write more.
Revision Changes Path
1.1 xml-soap/java/doc/guide/index.html
Index: index.html
===================================================================
<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
<title>XML-SOAP v1.2 Release Notes</title>
</head>
<body bgcolor="#FFFFFF">
<h1 align="center">Apache SOAP Version 2.0: User's Guide</h1>
<p align="center">August, 2000.</p>
<h2 align="left">Table of Contents</h2>
<ul>
<li><p align="left"><a href="#Features of XML-SOAP"><font
size="4"><strong>Features of Apache-SOAP</strong></font></a></p>
</li>
<li><p align="left"><a
href="#Using XML-SOAP for Remote Procedure Calls"><font
size="4"><strong>Using Apache-SOAP for Remote Procedure
Calls</strong></font></a></p>
</li>
<li><p align="left"><a href="#RPC over SMTP"><font size="4"><strong>RPC
over SMTP</strong></font></a></p>
</li>
<li><p align="left"><a href="#Managing Services"><font
size="4"><strong>Managing Services</strong></font></a></p>
</li>
<li><p align="left"><a href="#Tool for Debugging SOAP"><font
size="4"><strong>Tool for Debugging SOAP</strong></font></a></p>
</li>
<li><p align="left"><a href="#Implementation Restrictions"><font
size="4"><strong>Implementation Restrictions</strong></font></a></p>
</li>
<li><p align="left"><a href="#Dependencies"><font size="4"><strong>Dependencies</strong></font></a></p>
</li>
</ul>
<h2><a name="Features of XML-SOAP">Features of XML-SOAP</a></h2>
<ul>
<li>Supports most of the SOAP v1.1 specification</li>
<li>Provides server-side infrastructure for deploying,
managing and running SOAP enabled services</li>
<li>Provides client-side API for invoking SOAP services</li>
<li>Release includes full source under the <em>Apache
Software License</em></li>
<li>Supports three encoding styles: SOAP v1.1 Encoding,
Literal XML and XMI.</li>
<li>XMI encoding (available when using Java 1.2.2) supports
automatic marshalling and unmarshalling of arbitrary
objects</li>
<li>SOAP encoding: built-in support is provided for encoding/decoding
primitive types, Strings, arbitrary JavaBeans (using
reflection) and Vectors, Enumerations, or 1-dimensional
arrays of these types. For other types user can hand-write
encoder/decoder and register with XML-SOAP runtime.</li>
<li>Literal XML encoding: allows one to send XML elements (DOM
org.w3c.dom.Element objects) as parameters by embedding
the literal XML serialization of the DOM tree. No code
needs to be written to support this (see the addressbook
demo to see a sample use of it).</li>
<li>Supports messaging and RPC over two transports: HTTP and
SMTP</li>
<li>Supports authoring services in scripting languages</li>
</ul>
<h2><a name="Using XML-SOAP for Remote Procedure Calls">Using XML-SOAP
for Remote Procedure Calls</a></h2>
<p>The org.apache.soap.rpc package supports performing RPC over
SOAP. The XML-SOAP model is as follows: </p>
<p>The URI of the method call element is used as the object ID on
the remote side. The client side API has a "Call"
object (org.apache.soap.rpc.Call) that is filled in with the
method name, object ID and parameters. 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. </p>
<p>Once a Call object is set up, its invoke (URL, String) method
may be called to call the method using the URL as the SOAP
endpoint to deliver to and the 2nd argument being the value of
the SOAPAction header. This method returns a Response object (org.apache.soap.rpc.Response)
which contains the actual response (if any) or the fault if a
fault was generated.</p>
<p>If the RPC is carried over HTTP, the server-side RPC router (rpcrouter.jsp
in the webapp directory) receives the POST-ed envelope,
unmarshalls it and then builds a Call object. Then, the target
object is located by looking up the object ID in the
ServiceManager's (org.apache.soap.server.ServiceManager), the
method name is verified and then the invoke (Object) method is
called to call the method on the target object. The return value
is a Result (org.apache.soap.rpc.Result) object which is then
marshalled and sent back as the HTTP response. </p>
<p>If the RPC is carried over SMTP, then it goes to a mailbox and
sits there waiting to be acted upon. We provide a POP3 to HTTP to
SMTP bridge to receive these mail messages, post the content to
an HTTP SOAP endpoint, get the result and forward the result by
mail (SMTP) to the original sender. The receiving side will poll
the POP3 server, receive the message, extract the content,
unmarshall and return the Response to the original caller.</p>
<h2><a name="RPC over SMTP">RPC over SMTP</a></h2>
<p>To do RPC over SMTP in XML-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&/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 "next message"
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>
<h2><a name="Managing Services">Managing Services</a></h2>
<p>XML-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 XML-SOAP
server, then this version will not recognize those services
because the class that was being serialized to represent services
has changed.</p>
<h3>Running the Server Side Admin Tool to Manage Services</h3>
<p>With the XML-SOAP Administration Tools it is possible to use a
Web browser to deploy and un-deploy services and to review 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/xml-soap">http://hostname:port/xml-soap</a>
(see above) and you will get the "XML-SOAP Admin"
screen with three options:</p>
<ul>
<li><b>Deploy </b>to deploy a new service. </li>
<li><b>Un-deploy </b>to remove a deployed service. </li>
<li><b>List </b>shows the list of services currently deployed
in the server.</li>
</ul>
<p>The usage of these functions is immediate once one understands
the nature of the information required for deploying a service.
In the next section we describe this information.<b> </b></p>
<p><b>Service Deployment Information</b></p>
<p>We review here the information that defines a deployed service.
This information must be provided when using the Deploy function,
and can be browsed using the List function. We refer to this
information as "properties" of the service. </p>
<ul>
<li><b>ID.</b> An URN uniquely identifies the service to
clients. It must be unique among the deployed services,
and be encoded as a URI. We commonly use the format: urn:UniqueServiceID
. It corresponds to the target object ID, in the
terminology of the SOAP specification. </li>
<li><b>Scope. </b>Defines the lifetime of the object serving
the invocation request. This corresponds scope attribute
of the <jsp:useBean> tag in the JavaServer Pages.
It may thus have the following possible values: <ul>
<li><b>page:</b> the object is available until the
target JSP page (in this case the rpcrouter.jsp)
sends a response back or the request is forwarded
to another page (if you are using the standard
deployment mechanism this is unlikely to happen).
</li>
<li><b>request: </b>the object is available for the
complete duration of the request, regardless of
forwarding. </li>
<li><b>session: </b>the object is available for the
complete duration of the session. </li>
<li><b>application: </b>any page within the
application may access the object. In particular,
successive service invocations belonging to
different sessions will share the same instance
of the object. It is important to observe that
the value of this attribute can have important
security implications. The page and request
scopes assure the isolation of successive calls.
On the other extreme, application scope implies
that all service objects are shared among
different users of the SOAP server. A document
describing usage scenarios for different scopes
will be forthcoming. </li>
</ul>
</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>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"
the class method that is made available is a static
method, and thus no object will be instantiated. When
static invocation is used, the "scope" property
is not applicable. </li>
<li><strong>For script services, Script language.</strong>
Indicates the scripting language used to implement the
service.</li>
<li><strong>For script services, Script filename.</strong>
Name of file containing the script, or</li>
<li><strong>For script services, Script.</strong> The actual
script to run.</li>
<li><b>Type mappings. </b>In order to control the
serialization and deserialization of specific Java types
to and from XML in a particular encoding style, it may be
necessary to provide serialization and deserialization
classes that know how to perform the correct conversions
for those types. The XML-SOAP server already includes
serialization classes for most basic types in the SOAP
encoding style, as well as a Bean encoding class that can
provide a generic serialization of a bean in terms of its
properties. It also includes XMI serializer/deserializer
classes to support the XMI encoding style. Since
different types may require additional support for
correct serialization, the XML-SOAP maintains a registry
of Serializers and Deserializers. The registry is
accessible to service administrators through the XML-SOAP
administration tool, as well as through a program API. In
order to register a (de)serializer class, the class must
implement the Serializer or Deserializer interfaces, see
JavaDocs for org.apache.soap.util.xml.Serializer and com.org.apache.soap.util.Deserializer
.</li>
</ul>
<h3>Using the Command Line Tool to Manage Services</h3>
<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
where
url is the XML-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>
<p>To deploy a service, for example, type:</p>
<blockquote>
<pre>% java org.apache.soap.server.ServiceManagerClient <a
href="http://hostname:port/xml-soap/rpcrouter.jsp">http://hostname:port/xml-soap/rpcrouter.jsp</a> <strong>deploy</strong> foo.xml</pre>
</blockquote>
<p>where foo.xml is the deployment descriptor and the URL is
appropriate for your installation.</p>
<h2><a name="Tool for Debugging SOAP">Tool for Debugging SOAP</a></h2>
<p>XML-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><a name="Implementation Restrictions">Implementation
Restrictions</a></h2>
<p>The following features of the SOAP v1.1 specification are <strong>not</strong>
currently supported:</p>
<ul>
<li>encodingStyle attribute must have only one encoding style
given (see section 4.1.1 of the spec)</li>
<li>mustUnderstand attribute</li>
<li>root attribute</li>
<li>actor attribute and SOAP intermediaries</li>
<li>ID/href links and multi-ref accessors</li>
<li>all but the following XML Schema simple types: string,
boolean, double, float, long, int, short, byte</li>
</ul>
<h2><a name="Dependencies">Dependencies</a></h2>
<ul>
<li>XMI encoding requires use of Java 1.2.2 and XML4J 2.0.15.
The rest of XML-SOAP requires Apache Xerces 1.0.3. Your
classpath must have xerces.jar first and then xml4j.jar
next <strong>in that order</strong>. </li>
<li>Implementing services in scripting languages requires the
use of <a href="http://www.alphaworks.ibm.com/tech/bsf">BSF</a>.
When you download BSF, note carefully the versions of the
various scripting languages supported! [A new release of
BSF is upcoming very shortly.]</li>
</ul>
</body>
</html>
1.2 +0 -3 xml-soap/java/doc/install/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/xml-soap/java/doc/install/index.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.html 2000/08/03 16:44:25 1.1
+++ index.html 2000/08/03 16:50:42 1.2
@@ -12,9 +12,6 @@
<h1 align="center">Apache SOAP Version 2.0: Installation
Instructions</h1>
-<p align="center">Sanjiva Weerawarana (<a
-href="mailto:mailto:sanjiva@watson.ibm.com">sanjiva@watson.ibm.com</a>)</p>
-
<p align="center">August, 2000.</p>
<p>The Apache SOAP distribution can be installed for use as a