CSE 134A, Fall 2002
Discussion section notes
Friday, 11/15/2002
TA: Greg Hamerly

RPC and SOAP

The fourth project will make use of more XML concepts. Recall that project 3 used VXML; for this project you will be using XML in two different ways:

You will define your own DTD (document type definition) for an XML document that describes a correspondance (a letter).
You will use SOAP (Simple Object Access Protocol) to build aserver and a client for doing mail address verification.

Today we will discuss the concepts of RPC in general, and SOAP in PHP in particular.

RPC: remote procedure call

RPC (remote procedure call) is a programming concept that comes from the UNIX world. The basic idea of RPC is to provide an abstraction layer for the programmer that allows a program to make function calls that will be serviced by another computer. For example, imagine that you have a client application that serves as a front-end for a database of automotive parts. The database is very large, and may change, so you don't want to store it on every computer that must access it across the country. But you want the client to be able to make a function call like:

function Id find_part_id(Description, Model, Year)

But you don't want to write a lot of complicated networking code to handle such a request. RPC is an answer to this problem.

In general, RPC consists of 4 parts:

client-side stubs (provided by the RPC software)
server-side stubs (written by the programmer)
client-side marshalling, unmarshalling, and network handling (provided by the RPC software)
server-side marshalling, unmarshalling, and network handling (provided by the RPC software)

Note that when a person refers to "RPC", they may be referring to the concept in general (as we will in this class), or they may be referring to the original model by Sun (which is still used today).

An example of an RPC at work:

the client makes a function call that is an RPC call (to what is called a "client-side stub")
the client's RPC software pretends to be a regular function, but actually it:

takes the arguments
packages them into a common format ("marshalling")
sends them to the server where they will be processed

the server's RPC software

receives the network request from the client

unpackages the arguments that were passed over the network ("unmarshalling")
calls the "server-side stub" function with the arguments that were

the server-side stub, written by the programmer, performs the function call, and may return data
the server's RPC software

receives the data returned by the stub

packages the returned data into the common format (marshalling)
sends the response back to the client

the client's RPC software

receives the data returned by the server
unpackages the data (unmarshalling)
returns the data from the client-side stub

the program continues

The beauty of the RPC system is that the programmer only needs to define the interface of a function, which he is used to doing. So for the example of the automotive parts database server, the programmer only needs to define the interface of the function given above (find_part_id()), and the RPC software handles the parts that include marshalling, unmarshalling, and networking. To the programmer, it is no different than making a normal function call. Of course, in practice things aren't always that easy.

Marshalling and unmarshalling

Since RPC is intended to be used between computers that may be very different (e.g. the client may be a macintosh running OSX, and the server might be a 386-based computer running linux), RPC needs a standard way to represent data between the client and the server. Simply put, a Sparc computer and a Macintosh and a 386-based computer may all represent an integer, or a floating point number, in different ways. The representations are architecture-dependant. Think about little-endian versus big-endian. If RPC didn't correct for these differences in data representation, the systems wouldn't be able to work together.

Therefore RPC systems have to standardize their data representation. In the original Sun model, this was called XDR (eXternal Data Representation). It allowed programmers to use their basic types (such as integer, floating point, and character), and define their own data types (such as an Automobile data type, represented as a C struct). Typically, when data is marshalled, each argument is converted from the native format of the computer it is coming from into a common format (often called network format). When it is unmarshalled, the opposite occurs -- data is converted from network format into the native format of the receiving computer. This must be done for every piece of data -- strings, integers, floating point numbers, etc.

SOAP: Simple Object Access Protocol

SOAP is a relatively new RPC protocol proposed primarily by Microsoft. There are two distinctions about SOAP:

SOAP can be invoked by web server software, rather than sitting around waiting for connections on a certain port (as Sun RPC did).
SOAP uses its own XML schema to handle data description, as opposed to something like XDR as used by Sun.

Thus SOAP is riding the popularity wave because of its use of two popular technologies: the web, and XML. The basic idea is that a SOAP client may issue a request to a SOAP server via the web, and the web server handles the request. So SOAP is built to work on top of HTTP.

Since a SOAP server may be invoked by a web server, PHP is a natural environment in which to write SOAP services. PHP doesn't currently have SOAP support built in, but there is a nice library available called "NuSoap" (http://dietrich.ganx4.com/nusoap/index.php) which allows you to add SOAP client and server functionality by including one PHP file. The basic way that this library works is:

the client creates a new SOAP client object, and points it to the SOAP server (e.g. "http://ieng9.ucsd.edu/php-cs134f/.../hello_server.php")
the client calls a named function on the server (like "hello(string)")
the NuSoap library handles the packaging of the arguments, and sends a SOAP request to the specified server
the SOAP server runs (invoked by the web server)

it registers a function hello(string) with NuSoap
tells NuSoap to service the RPC request
NuSoap unpackages the data, sees a request for the hello(string) function, and its arguments
NuSoap calls the hello(string) function, which the user wrote. It may have been defined as:
```
function hello($name) {
    return "Hello, $name!";
}
```
NuSoap receives the return values from the hello(string) function, marshalls it into the SOAP format, and sends it back to the client.

the NuSoap client receives the response of the server and unmarshalls the results, and returns them to the original caller.

That sounds like a lot, but it actually is pretty simple, because most of the work (major steps 3-5) is being done by NuSoap.

Simple example of a SOAP server and client

Here is an example that works on ieng9.

The client:

<?php

require_once('nusoap.php');
$parameters = array('name'=>'greg');
$soapclient = new soapclient('http://ieng9.ucsd.edu/php-cs134f/.../server.php');
$result = $soapclient->call('hello',$parameters);
print("$result\n");

?>

The server:

<?php

require_once('nusoap.php');
$s = new soap_server;
$s->register('hello');

function hello($name){
  // optionally catch an error and return a fault
  if($name == ''){
    return new soap_fault('Client','','Must supply a valid name.');
  }
  return "hello $name!";
}
$s->service($HTTP_RAW_POST_DATA);

?>

When the client is executed, it will connect to the server and communicate using the SOAP protocol. The server will service it's request, and return a value using SOAP.

Greg Hamerly 11/15/2002