XML-SOAP v1.2 Release Notes
May 25, 2000.
Table of Contents
- Supports most of the SOAP v1.1 specification
- Provides server-side infrastructure for deploying,
managing and running SOAP enabled services
- Provides client-side API for invoking SOAP services
- Release includes full source under the Apache Software License
- Supports three encoding styles: SOAP v1.1 Encoding,
Literal XML and XMI.
- XMI encoding (available when using Java 1.2.2) supports
automatic marshalling and unmarshalling of arbitrary
objects
- SOAP encoding: built-in support is provided for
encoding/decoding primitive types, Strings, arbitrary
JavaBeans (using reflection) and
1-dimensional arrays of these types. For other types user
can hand-write encoder/decoder and register with XML-SOAP
runtime.
- 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).
- Supports messaging and RPC over two transports: HTTP and
SMTP
- Supports authoring services in
scripting languages
The org.apache.soap.rpc package supports performing RPC over
SOAP. The XML-SOAP model is as follows:
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.
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.
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.
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.
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.
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 POP3
bean from alphaWorks 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.
NOTE: We strongly recommend against
using your own email address for testing RPC over SMTP. There are
many free POP3 email providers on the Web (such as www.mailandnews.com, for
example) if you are unable to set up multiple POP3 accounts
yourself.
IMPORTANT: 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.
If you run startup.bat, then line 38 of tomcat.bat should look
like this:
set CLASSPATH=path-to-xerces\xerces.jar;%CLASSPATH%;%cp%
If you run startup.sh, add the following after line 111:
CLASSPATH=path-to-xerces/xerces.jar:${CLASSPATH}
The easiest way to set up for Tomcat is to add a
<Context> to conf/server.xml:
<Context path="/xml-soap" docBase="path-to-xml-soap/XML-SOAP-1.2/webapp"
debug="1" reloadable="true" >
</Context>
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.
You should be able to deploy services by pointing a browser to
http://hostname:port/xml-soap
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:
http://hostname:port/xml-soap/rpcrouter.jsp
Happy SOAP-ing!
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.
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.
Running the Server Side Admin Tool to Manage Services
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.
Point your browse to http://hostname:port/xml-soap
(see above) and you will get the "XML-SOAP Admin"
screen with three options:
- Deploy to deploy a new service.
- Un-deploy to remove a deployed service.
- List shows the list of services currently deployed
in the server.
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.
Service Deployment Information
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.
- ID. 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.
- Scope. 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:
- page: 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).
- request: the object is available for the
complete duration of the request, regardless of
forwarding.
- session: the object is available for the
complete duration of the session.
- application: 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.
- Method list. Defines the names of the method that
can be invoked on this service object.
- Provider type. Indicates whether
the service is implemented using Java or a scripting
language.
- For Java services, Provider class. Fully specified
class name of the target object servicing the request.
- For Java services, Use static class. If set to "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.
- For script services, Script language.
Indicates the scripting language used to implement the
service.
- For script services, Script filename.
Name of file containing the script, or
- For script services, Script. The actual
script to run.
- Type mappings. 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 .
Using the Command Line Tool to Manage Services
The command line tool is run by typing java
org.apache.soap.server.ServiceManagerClient. Running this yields:
% 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
To deploy a service, for example, type:
% java org.apache.soap.server.ServiceManagerClient http://hostname:port/xml-soap/rpcrouter.jsp deploy foo.xml
where foo.xml is the deployment descriptor and the URL is
appropriate for your installation.
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!
The following features of the SOAP v1.1 specification are not
currently supported:
- encodingStyle attribute must have only one encoding style
given (see section 4.1.1 of the spec)
- mustUnderstand attribute
- root attribute
- actor attribute and SOAP intermediaries
- ID/href links and multi-ref accessors
- all but the following XML Schema simple types: string,
boolean, double, float, long, int, short, byte
- 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 in that order.
- Implementing services in scripting languages requires the
use of BSF.
When you download BSF, note carefully the versions of the
various scripting languages supported! [A new release of
BSF is upcoming very shortly.]
None that we know of right now ..
While not strictly a bug, the docs are pretty lacking yet. We
are working on much improved documentation (both external and
within the source)!
Matthew J. Duftler, duftler@us.ibm.com,
Sanjiva Weerawarana, sanjiva@watson.ibm.com,
Francisco Curbera, curbera@us.ibm.com
Component Systems Group
IBM TJ Watson Research Center
Hawthorne, NY 10532.
Sam Ruby, rubys@us.ibm.com
Software Solutions
IBM Research Triangle Park
Raleigh, NC 27709