You are viewing a plain text version of this content. The canonical link for it is here.
Posted to soap-dev@ws.apache.org by sa...@locus.apache.org on 2000/08/03 18:53:51 UTC
cvs commit: xml-soap/java ReleaseNotes.html
sanjiva 00/08/03 09:53:50
Modified: java ReleaseNotes.html
Log:
now points to the other docs
Revision Changes Path
1.5 +8 -410 xml-soap/java/ReleaseNotes.html
Index: ReleaseNotes.html
===================================================================
RCS file: /home/cvs/xml-soap/java/ReleaseNotes.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- ReleaseNotes.html 2000/07/28 15:08:21 1.4
+++ ReleaseNotes.html 2000/08/03 16:53:50 1.5
@@ -9,419 +9,17 @@
<body bgcolor="#FFFFFF">
-<h1 align="center">XML-SOAP v2.0 Release Notes</h1>
+<h1 align="center">Apache-SOAP Version 2.0: Release Notes</h1>
-<p align="center">July 27, 2000.</p>
+<p align="center">August xx, 2000.</p>
-<h2 align="left">Table of Contents</h2>
+<p align="left">See <a href="doc/install/index.html">here</a> for
+Installation Instructions.</p>
-<ul>
- <li><p align="left"><a href="#Features of XML-SOAP"><font
- size="4"><strong>Features of XML-SOAP</strong></font></a></p>
- </li>
- <li><p align="left"><a
- href="#Using XML-SOAP for Remote Procedure Calls"><font
- size="4"><strong>Using XML-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="#Using Apache Tomcat v3.1 for the Server-side"><font
- size="4"><strong>Using Apache Tomcat v3.1 for the
- Server-side</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>
- <li><p align="left"><a href="#Bugs"><font size="4"><strong>Bugs</strong></font></a></p>
- </li>
- <li><p align="left"><a href="#Authors"><font size="4"><strong>Authors</strong></font></a></p>
- </li>
-</ul>
+<p align="left">See <a href="doc/guide/index.html">here</a> for
+the User's Guide.</p>
-<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="Using Apache Tomcat v3.1 for the Server-side">Using
-Apache Tomcat v3.1 for the Server-side</a></h2>
-
-<p><strong>IMPORTANT</strong>: Tomcat comes with an XML parser
-(lib/xml.jar) which has the DOM level 1 interfaces. Even if you
-put Xerces 1.0.3's xerces.jar in your classpath, the wrong
-interfaces are found by any Java code running in Tomcat because
-the shell script / batch file that runs Tomcat puts the user's
-classpath at the end. So, you must edit tomcat.sh or tomcat.bin
-in the bin/ directory and put xerces.jar at the BEGINING of the
-classpath the script builds. </p>
-
-<p>If you run startup.bat, then line 38 of tomcat.bat should look
-like this:</p>
-
-<blockquote>
- <pre>set CLASSPATH=path-to-xerces\xerces.jar;%CLASSPATH%;%cp%</pre>
-</blockquote>
-
-<p>If you run startup.sh, add the following after line 111:</p>
-
-<blockquote>
- <pre>CLASSPATH=path-to-xerces/xerces.jar:${CLASSPATH}</pre>
-</blockquote>
-
-<p>The easiest way to set up for Tomcat is to add a
-<Context> to conf/server.xml:</p>
-
-<pre><Context path="/xml-soap" docBase="path-to-xml-soap/XML-SOAP-1.2/webapp"
- debug="1" reloadable="true" >
-</Context></pre>
-
-<p>Now, make sure you have the jar files from the lib directory
-of this distribution on your classpath and startup tomcat. Also
-you will want to have on the classpath any of your code that you
-want to deploy as services.</p>
-
-<p>You should be able to deploy services by pointing a browser to</p>
-
-<blockquote>
- <pre><a href="http://hostname:port/xml-soap">http://hostname:port/xml-soap</a></pre>
-</blockquote>
-
-<p>where hostname is the host on which Tomcat is running and port
-is the port. See the next section for details on the
-aministration tool. The SOAP end-point for invoking services on
-this server is:</p>
-
-<blockquote>
- <pre><a href="http://hostname:port/xml-soap">http://hostname:port/xml-soap/rpcrouter.jsp</a></pre>
-</blockquote>
-
-<p>Happy SOAP-ing!</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>
-
-<h2><a name="Bugs">Bugs</a></h2>
-
-<p>None that we know of right now ..</p>
-
-<p>While not strictly a bug, the docs are pretty lacking yet. We
-are working on much improved documentation (both external and
-within the source)!</p>
-
-<h2><a name="Authors">Authors</a></h2>
-
-<blockquote>
- <p>Matthew J. Duftler, <a href="mailto:duftler@us.ibm.com">duftler@us.ibm.com</a>,<br>
- Sanjiva Weerawarana, <a href="mailto:sanjiva@watson.ibm.com">sanjiva@watson.ibm.com</a>,<br>
- Francisco Curbera, <a href="mailto:curbera@us.ibm.com">curbera@us.ibm.com</a><br>
- <br>
- Component Systems Group<br>
- IBM TJ Watson Research Center<br>
- Hawthorne, NY 10532. <br>
- </p>
- Sam Ruby, <a href="mailto:rubys@us.ibm.com">rubys@us.ibm.com</a><br>
- <br>
- Software Solutions<br>
- IBM Research Triangle Park<br>
- Raleigh, NC 27709<br>
-</blockquote>
+<p align="left">See <a href="http://xml.apache.org/soap">here</a>
+for information about the Apache SOAP project.</p>
</body>
</html>