This chapter describes:
- Quick introduction to SOAP.
- Overview of SOAP::Lite modules.
- Introduction to SOAP::Transport::TCP Module and sample SOAP server program.
- Introduction to SOAP::Lite and sample SOAP client program.
- How to use the trace feature in SOAP::Lite.
What is SOAP?
SOAP (Simple Object Accessing Protocol) - A client-server communication protocol to allow the client side to accessing programming objects on the server side, and execute methods against those objects, and receiving execution result. All these functionalities are archived by sending and receiving XML messages over various transportation protocols, like TCP, HTTP, FTP, etc.
There are two options for an application program, client side or server side, to use SOAP:
1. Follow the SOAP protocol, and do everything yourself. Here is the communication diagram:
| SOAP on TCP | Client Prog.|<-------------->|Server Prog.
Here is the steps involved to complet a single SOAP communication:
Step Client Program Server Program
1 Prepare server socket 2 Listen on server socket 3 Wait 4 Prepare SOAP request Wait 5 Prepare client socket Wait 6 Connect to server Connect with client 7 Transmit SOAP request Receive SOAP request 8 Wait Process SOAP request 9 Wait Prepare SOAP response 10 Receive SOAP response Transmit SOAP response 11 Close client socket Wait
2. Use SOAP client API (Application Program Interface) package to help your client program to:
- Use SOAP technology with a simple API.
- Prepare the SOAP request XML message.
- Transmit the SOAP request.
- Receive the SOAP response.
- Parse the SOAP response.
3. Use SOAP server API (Application Program Interface) package to help your server program to:
- Use SOAP technology with a simple API.
- Receive the SOAP request XML message.
- Parse the SOAP resquest.
- Prepare the SOAP response XML message.
- Transmit the SOAP response.
Here is the communication diagram, if you are using SOAP API packages:
Client System Server System
API | TCP/HTTP/... |
Client Prog.<--->SOAP Client|<-------------->|TCP/HTTP/... Server
^
| Attached
v
SOAP Server
^
| API
v
Server Prog.
To learn more about SOAP, see my other book: "Herong's Notes on SOAP".
What is SOAP::Lite?
SOAP::Lite - A collection of Perl modules developed by Paul Kulchenko to server as both a SOAP client API package and a SOAP server API package. It offers:
- SOAP::Lite - Client API.
- SOAP::Transport::HTTP - Serve API for HTTP transportation, standalone and CGI
- SOAP::Transport::TCP - Serve API for TCP transportation
- Server API for other transportation protocols
- Utilities related to SOAP technology
SOAP::Transport::TCP Module
Let's look at one of the SOAP server API module first. SOAP::Transport::TCP has sub module called SOAP::Transport::TCP::Server. It offers two functionalites: 1. Taking SOAP requests as a SOAP server; 2. Interacting with application modules to handle the requests as a SOAP server side API.
Main functions of SOAP::Transport::TCP::Server are:
new(LocalAddr=>'hostname', LocalPort=>'port', Listen=>'queueSize') - Constructs and returns SOAP server object that listens on the specified host name at the specified port with the specified queue size.
dispatch_to('Module::method') - Defines the module name and the method name that can be called by the incoming SOAP request for this server, and returns this server object.
handle() - Puts this server in waiting mode for incoming SOAP request. Whenever a SOAP request comes, it will be automatically passed to the module name and the method name defined by the dispatch_to() function based on the SOAP action name in the request.
Here is a sample program to show you how to create a SOAP server with TCP as the transportation protocol:
#- SoapTcpServer.pl
#- Copyright (c) 2002 by Dr. Herong Yang
use SOAP::Transport::TCP;
my $daemon = SOAP::Transport::TCP::Server
->new(LocalAddr => 'localhost', LocalPort => 8001, Listen => 5);
$daemon->dispatch_to('Hello::hello');
print "SOAP TCP server listening...\n";
print " Host: ", $daemon->sockhost, "\n";
print " Port: ", $daemon->sockport, "\n";
$daemon->handle();
This program will create a SOAP server on localhost at 8001, and dispatch SOAP request to Hello::hello, if the SOAP action name matches it. Here is my Hello module code:
#- Hello.pm
#- Copyright (c) 2002 by Dr. Herong Yang
package Hello;
sub hello {
shift;
return "Hello " . shift;
}
1;
If you run SoapTcpServer.pl, you will get this:
SOAP TCP server listening... Host: 127.0.0.1 Port: 8001
The SOAP server is ready. Now you need a SOAP client program to talk the SOAP server. See the next section to know how to write a SOAP client program.
SOAP::Lite Module
SOAP:Lite represents the SOAP client API that allows you to send a Perl function call as a SOAP request to the specified SOAP server, and receive the result of the call as a SOAP response from the server. Main functions of SOAP::Lite are:
new() - Constructs a new SOAP::Lite object, and returns it.
uri('uri') - Defines the URI (Universal Resource Identifier) of the target module to be called, and returns the same object.
proxy('url') - Defines the URL (Universal Resource Locator) of the SOAP server, and returns the same object.
'method'() - Allows to call the method from the target module on the SOAP server, and returns a new SOAP::SOM object representing the outcome of the call.
$som->result - A property of a SOAP::SOM object representing the returning scalar value of the call.
Here is a sample program to show you how to use SOAP::LITE module to request a function call to the SOAP server I created in the previous section.
#- SoapTcpClient.pl
#- Copyright (c) 2002 by Dr. Herong Yang
use SOAP::Lite;
# use SOAP::Lite +trace;
my $client = SOAP::Lite->new();
$client->uri('urn:Hello');
$client->proxy('tcp://localhost:8001');
my $som = $client->hello("Herong");
my $output = $som->result;
print $output . "\n";
Run it while the SoapTcpServer.pl is running, you will get:
Hello Herong
This is amazing. You can create a simple SOAP server and client in less than 20 lines of source code!
Note that the proxy URL must have "tcp" as the protocol name, since the SOAP server is running with TCP as the transportation protocol.
SOAP::Lite Tracing
In the sample programs shown in the previous section, you don't see any SOAP XML messages. And you don't see how the server and the client send messages to each other. All of these are hidden behind SOAP::Lite modules. If you want to know more about how SOAP::Lite modules work, you can turn on the trace function on the SOAP::Lite module.
Here is the revised server program with trace on:
#- SoapTcpServerTrace.pl
#- Copyright (c) 2002 by Dr. Herong Yang
use SOAP::Lite +trace;
use SOAP::Transport::TCP;
my $daemon = SOAP::Transport::TCP::Server
->new(LocalAddr => 'localhost', LocalPort => 8001, Listen => 5);
$daemon->dispatch_to('Hello::hello');
print "SOAP TCP server listening...\n";
print " Host: ", $daemon->sockhost, "\n";
print " Port: ", $daemon->sockport, "\n";
$daemon->handle();
Here is the revised client program with trace on:
#- SoapTcpClientTrace.pl
#- Copyright (c) 2002 by Dr. Herong Yang
use SOAP::Lite +trace;
my $client = SOAP::Lite->new();
$client->uri('urn:Hello');
$client->proxy('tcp://localhost:8001');
my $som = $client->hello("Herong");
my $output = $som->result;
print $output . "\n";
Running the server first, and then the client, you will get on the client side:
SOAP::Transport::new: () SOAP::Serializer::new: () SOAP::Deserializer::new: () SOAP::Parser::new: () SOAP::Lite::new: () SOAP::Transport::TCP::Client::new: () SOAP::Lite::call: () SOAP::Serializer::envelope: () SOAP::Serializer::envelope: hello Herong SOAP::Data::new: () SOAP::Data::new: () SOAP::Data::new: () SOAP::Data::new: () SOAP::Data::new: () SOAP::Transport::TCP::Client::send_receive: <?xml version="1.0" encodi ng="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap. org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org /soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envel ope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd= "http://www.w3.org/1999/XMLSchema"><SOAP-ENV:Body><namesp1:hello xmlns :namesp1="urn:Hello"><c-gensym3 xsi:type="xsd:string">Herong</c-gensym 3></namesp1:hello></SOAP-ENV:Body></SOAP-ENV:Envelope> SOAP::Transport::TCP::Client::send_receive: <?xml version="1.0" encodi ng="UTF-8"?><SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap. org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org /soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envel ope/" xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" xmlns:xsd= "http://www.w3.org/1999/XMLSchema"><SOAP-ENV:Body><namesp1:helloRespon se xmlns:namesp1="urn:Hello"><s-gensym3 xsi:type="xsd:string">Hello He rong</s-gensym3></namesp1:helloResponse></SOAP-ENV:Body></SOAP-ENV:Env elope> SOAP::Deserializer::deserialize: () SOAP::Parser::decode: () SOAP::SOM::new: () Hello Herong SOAP::Lite::DESTROY: () SOAP::Serializer::DESTROY: () SOAP::Data::DESTROY: () SOAP::Data::DESTROY: () SOAP::Data::DESTROY: () SOAP::Data::DESTROY: () SOAP::Data::DESTROY: () SOAP::Transport::DESTROY: () SOAP::Transport::TCP::Client::DESTROY: () SOAP::SOM::DESTROY: () SOAP::Deserializer::DESTROY: () SOAP::Parser::DESTROY: ()
On the server side, you will get:
SOAP::Serializer::new: () SOAP::Deserializer::new: () SOAP::Parser::new: () SOAP::Server::new: () SOAP::Transport::TCP::Server::new: () SOAP TCP server listening... Host: 127.0.0.1 Port: 8001 SOAP::Server::handle: () SOAP::Deserializer::deserialize: () SOAP::Parser::decode: () SOAP::SOM::new: () SOAP::Data::new: () SOAP::Data::DESTROY: () (eval): Herong SOAP::Server::handle: Hello Herong SOAP::Serializer::envelope: () SOAP::Serializer::envelope: helloResponse Hello Herong SOAP::Data::new: () SOAP::Data::new: () SOAP::Data::new: () SOAP::Data::new: () SOAP::Data::new: () SOAP::SOM::DESTROY: ()
Now you see the SOAP XML request, and the response generated by SOAP::Lite modules.
discuss this topic to forum
