Clean up your wire protocol with SOAP, Part 2 - JavaWorld April 2001
Tutorial Details:
Clean up your wire protocol with SOAP, Part 2
Clean up your wire protocol with SOAP, Part 2
By: By Tarak Modi
Use Apache SOAP to create SOAP-based applications
OAP (Simple Object Access Protocol) is a wire protocol that uses XML for data encoding. It is a minimalist specification of sorts; it only defines the most critical pieces required by a wire protocol, and purposefully omits the details of garbage collection, object activation, and so forth.
SOAP is especially important for Java developers because it adds to Java's value proposition by making platform independence and portability more interoperable. In fact, I would not be surprised if future releases of Java 2 Platform, Enterprise Edition (J2EE) make SOAP one of the mandatory wire protocols that all J2EE-compliant application servers must support. But that's enough speculation for now.
In Part 2 of this four-part series, I will introduce you to Apache's SOAP implementation.
Read the whole series on SOAP:
Part 1: An introduction to SOAP basics
Part 2: Use Apache SOAP to create SOAP-based applications
Part 3: Create SOAP services in Apache SOAP with JavaScript
Part 4: Dynamic proxies make Apache SOAP client development easy
Introducing Apache SOAP
Apache SOAP, the Apache Software Foundation's implementation of the SOAP specification, is based on IBM's SOAP4J. Like all Apache projects, Apache SOAP is open source and available under the Apache license. I think it is currently one of the best implementations of SOAP. Though Apache SOAP conforms to version 1.1 of the SOAP specification, it lacks support for some features included in SOAP 1.1. (See Resources for a list of Apache SOAP'S available features.)
Download and install Apache SOAP
As I mentioned above, you can download Apache SOAP free of charge. (See Resources for a link.) For my Windows NT laptop, I downloaded the file soap-bin-2.0.zip , which contains Apache SOAP 2.0, the latest version as of this writing. Installing Apache SOAP is a breeze. It consists of three easy steps:
Unzip the downloaded zip file : This results in the creation of a soap-2_0 subdirectory. I unzipped the contents into the root directory of my E drive, so I now have a directory E:\soap-2_0 that contains Apache SOAP.
Set up your Web environment : You will need a Web server that supports servlets and JavaServer Pages (JSPs). At this point, you will fall into one the following two categories:
Category 1: You already have a Web server that supports servlets and JSPs, and you feel comfortable configuring it. In this case, set up your Web server so that you can point your browser to http://localhost:8080/apache-soap/. The browser will access the index.html file in the directory soap-2_0 \webapps\soap\ .
Category 2: You don't have a Web server that supports servlets and JSPs, or you have one but don't want to fool around with it. In this case, I suggest downloading the latest version of Tomcat (3.1 at the time of this writing). (See Resources for a link.) Tomcat is yet another example of the excellent software that Apache creates and makes available for free to the software development community. Once you've downloaded the appropriate zip file ( jakarta-tomcat-3.1.1.zip ), unzip it. A jakarta-tomcat subdirectory will be created. Once again, I've unzipped the contents into the root directory of my E drive. Add a new context to the jakarta-tomcat\conf\server.xml configuration file like this:
debug="1" reloadable="true">
You will need to replace E: in the docBase attribute of the Context element with the location of your soap-2_0 directory. To start Tomcat, execute the startup.bat ( startup.sh for Unix) file. To shut it down, execute the shutdown.bat ( shutdown.sh for Unix) file. But wait -- don't start Tomcat just yet.
Set up your Web server classpath : Apache SOAP requires Apache Xerces (Java) version 1.1.2 or higher, which supports the DOM (Document Object Model) level 2 candidate recommendation that provides namespace support. I use version 1.2 of Xerces, available from Apache as Xerces-J-bin.1.2.0.zip . Unzipping this file will result in the creation of a xerces-1_2_0 subdirectory. As before, I've unzipped the file into the root directory of my E drive. You must configure your Web server to use xerces.jar (which is in the xerces-1_2_0 subdirectory) -- as opposed to any native library/jar that came with your server -- for all XML parsing. For example, Tomcat comes with an XML parser ( jakarta-tomcat\lib\xml.jar ) that has the DOM level 1 interfaces. Even if you put the xerces.jar in your classpath, any Java code running in Tomcat will find the wrong interfaces because the shell script/batch file that you use to run Tomcat places your classpath at the end. So you must edit tomcat.bat ( tomcat.sh for Unix) in the jakarta-tomcat\bin\directory and put xerces.jar at the front of the classpath that the script builds. That is what I did in my jakarta-tomcat\bin\tomcat.bat file:
set CLASSPATH=E:\xerces-1_2_0\xerces.jar;%CLASSPATH%;%cp%
If you fall in Step 2's Category 2, then you must also configure your server to use xerces.jar .
Regardless of which category you fall into, in addition to xerces.jar , you must also set your Web server's classpath to use soap.jar from the soap-2_0\lib\ subdirectory.
Test your installation
Now, start your Web server and make sure that your installation is correct by pointing your browser to http://localhost:8080/apache-soap/admin. You should see an administration screen as shown in the figure below.
Apache SOAP administration tool
Click on thumbnail to view full-size image. (22 KB)
The HelloWorld example
Now that you have set up Apache SOAP, let's put it to use with a simple HelloWorld application. In SOAP lingo, applications are called services. Typically, services are created in two steps, which may or may not be performed by the same person/organization. The first step is to define and implement the service itself in the language of choice: in this case, Java. The second step is to create clients that actually need and invoke the service. Let's look at the HelloWorld service first.
The HelloWorld service
The HelloWorld service is the Apache SOAP implementation of the example I discussed in Part 1 . The service expects to obtain a person/user's name and returns a customized hello message to the caller. The code below shows the complete implementation of the HelloWorld service:
package hello;
public class HelloServer
{
public String sayHelloTo(String name)
{
System.out.println("sayHelloTo(String name)");
return "Hello " + name + ", How are you doing?";
}
}
Is that all? That is too simple to be true!
Apache SOAP makes creating services extremely easy. Basically, a service consists of the business logic, which is code that you would write regardless of how you made the service available to the rest of the world. In other words, the service is not tainted by any SOAP-related code, because the Apache SOAP infrastructure -- which consists of the rpcrouter servlet and soap.jar -- handles all the intricacies for you. Let's talk briefly about those intricacies. Just how does Apache SOAP handle remote procedure call (RPC) requests over HTTP? Understanding that will ease the creation of clients (yes, clients).
The org.apache.soap.rpc package provides support for performing RPC over SOAP in Apache SOAP. The central concept behind Apache SOAP's RPC support is that of an object ID. All Apache SOAP services must have a unique ID that acts as the service's object ID. As always, uniqueness is relative; in Apache SOAP, the uniqueness of these object IDs is related to the Apache SOAP server on which a service is deployed. That is, two services deployed on different Apache SOAP servers might have the same object ID.
A client interested in using a service sets up an org.apache.soap.rpc.Call object with the desired service's object ID, the name of the method to be invoked, and the parameters (if any) for that method. Once the Call object is set up, the client calls its invoke() method, which takes two parameters. The first is a URL to the rpcrouter servlet; in this case, the URL is http://localhost:8080/apache-soap/servlet/rpcrouter. The second parameter is the SOAPAction header. Refer to Part 1 for a refresher on the importance of the SOAPAction header and its possible values.
The invoke() method converts the Call object into an XML SOAP request (which is similar to the examples in Part 1) and sends that request to the rpcrouter servlet, as indicated by the URL. When the servlet returns a response, the invoke() method returns an org.apache.soap.rpc.Response object, which contains the service response (if any) or the fault (if a fault was generated). HTTP dictates that every request must have a response; so even if the service itself does not return anything, the rpcrouter servlet always does. Hence, the invoke() method will always return a Response object.
On the service side, the Apache SOAP server -- that is, the rpcrouter servlet -- receives the POSTed SOAP request from the client and rebuilds a Call object. The servlet uses the object ID from the rebuilt Call object to locate the object in the service manager.
The servlet then verifies the method name and invokes it on the located object. The servlet also serializes the return value from this call and sends it back in the HTTP response.
The above discussion raises an interesting question: How does Apache SOAP know how to serialize a given data type? Apache SOAP handles the marshalling and unmarshalling of Java data types to and from XML via a type-mapping registry ( org.apache.soap.encoding.SOAPMappingRegistry ), and via serialization ( org.apache.soap.util.xml.Serializer ) and deserialization ( org.apache.soap.util.xml.Deserialization ) interfaces that all marshallers and unmarshallers, respectively, must implement. Apache SOAP provides a number of
Read
Tutorial at: Click here to view the tutorial
Rate Tutorial: Clean up your wire protocol with SOAP, Part 2 - JavaWorld April 2001
View Tutorial: Clean up your wire protocol with SOAP, Part 2 - JavaWorld April 2001
Related
Tutorials:
 XML messaging, Part
3
XML messaging, Part
3
|
Connect the
enterprise with the JCA, Part 1
Connect the
enterprise with the JCA, Part 1
|
A birds-eye view of Web services
A birds-eye view of Web services
|
Cache SOAP services on
the client side
Cache SOAP services on
the client side
|
XML documents on
the run, Part 2
XML documents on
the run, Part 2
|
Jtrix: Web
services beyond SOAP
Jtrix: Web
services beyond SOAP
|
Discover and publish Web services with JAXR
Discover and publish Web services with JAXR
|
Jabber away with instant
messaging
Jabber away with instant
messaging
|
Yes, you can secure your Web services documents, Part 1
Yes, you can secure your Web services documents, Part 1
|
J2SE 1.4
breathes new life into the CORBA community, Part
1
J2SE 1.4
breathes new life into the CORBA community, Part
1
|
Business process
automation
made easy with
Java, Part 1
Business process
automation
made easy with
Java, Part 1
|
Yes, you can secure your Web services documents, Part 2
Yes, you can secure your Web services documents, Part 2
|
Sun boosts
Sun boosts enterprise Java
|
Publish and find UDDI tModels with JAXR and
WSDL
Publish and find UDDI tModels with JAXR and
WSDL
|
Secure Web
services
Secure Web
services
|
Axis-orizing objects for SOAP
Axis-orizing objects for SOAP
|
Test email components in your software
Test email components in your software
|
SAAJ: No strings attached
SAAJ: No strings attached
|
Clean Up Your Mess: Managing Temp Files in Java Apps
Clean Up Your Mess: Managing Temp Files in Java Apps
Creating and managing temporary files in a Java application can be a little tricky due to some open JVM bugs. Develop a workaround with some custom code and a clever design.
|
Using Timers in J2EE Applications
Using Timers in J2EE Applications
Job scheduling is nothing new--most enterprise applications require the scheduling of tasks and activities. For example, your application may need a timer service to run a business process once a day, or to clean up a te
|
|
|
|
