The following example illustrates how to write an XML-RPC client using the XML_RPC pack- age from PEAR. The following client interacts with the stock server created using the xmlrpc extension in PHP. It performs only a single transaction, but it works in the same manner as the previous stock client does.
<?php
require_once 'XML/RPC.php';
$userid = 1;
$stockSymbol = "YHOO";
$stockQuantity = 100;
$params = array(new XML_RPC_Value($userid, 'int'),
new XML_RPC_Value($stockSymbol, 'string'), new XML_RPC_Value($stockQuantity, 'int'));
$msg = new XML_RPC_Message('stockPurchase', $params);
$objStock = new XML_RPC_Client('/stocktrader.php', 'localhost');
$retVal = $objStock->send($msg);
if (!$retVal) {
echo 'Error: ' . $objStock->errstr;
} else {
if (!$retVal->faultCode()) {
$xmlrpcValue = $retVal->value();
echo $xmlrpcValue->scalarval()."\n";
} else {
echo "Unable to Purchase $stockQuantity shares of $stockSymbol";
echo "Error Code: ".$retVal->faultCode()."\n";
echo "Error Message: ".$retVal->faultString()."\n";
} }
?>
Bought 100 shares of Yahoo!
Seeing Some Examples in Action
Throughout this chapter, you have seen a few examples of interaction using XML-PRC. For a final example, I will use a real-world scenario. You may not be aware of this, but interacting with the PEAR repository using its tools occurs over XML-RPC.
■ Note As of PEAR 1.4.0, REST, covered in the next chapter, is now the service of choice for interacting with PEAR and its channels. XML-RPC is still available for supporting earlier versions of PEAR.
Leveraging this fact, you can create a custom interface to interact with PEAR directly. This example will demonstrate how to retrieve information for a specific package from the PEAR database. You can retrieve the full list of publicly accessible functions, which you could use to expand upon this example, by calling the remote system.listMethodsfunction. I will use the xmlrpc extension in PHP to create the client.
This example has two files. The file pearxmlrpclib.php, shown in Listing 16-6, is the code that performs all the work.
■ Note I have omitted the code for the call_using_sockets()function from the example because you can find it in Listing 16-1. If sockets are unavailable on your system, you can exchange it with the call_using_curl()function as long as you change the appropriate call within the library as well.
Listing 16-6.Search Library Referenced As pearxmlrpclib.php
<?php
function call_using_sockets($remote_server, $remote_server_port,
$remote_path, $request) { /* Code for this function found in Listing 16-1. */
}
/* Initialize variables */
$results = NULL;
$cur_package = '';
$pear_server = 'pear.php.net';
$pear_server_port = 80;
$pear_rpc_page = '/xmlrpc.php';
/* If form posted, then request the package information from PEAR Invalid submissions are not being checked in this example */
if (! empty($_POST['submit'])) {
$cur_package = (string)$_POST['pkg_name'];
$request_xml = xmlrpc_encode_request('package.info', array($cur_package));
/* call_using_curl may be substituted here */
$retval = call_using_sockets($pear_server, $pear_server_port,
$pear_rpc_page, $request_xml);
$results = xmlrpc_decode($retval);
}
?>
You need to place the code for the Web page, shown in Listing 16-7, somewhere within a Web site where it can be called from a browser. If the library file from Listing 16-6 is not placed in the same directory, make sure to correctly change the reference so the Web page can include it.
Listing 16-7.Web Page for Search Referenced As pearxmlrpc.php
<?php include('pearxmlrpclib.php'); ?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<body>
<p><b>PEAR Package Information</b></p>
<form name="pear_search" method="post">
Package Name: <input type="text" name="pkg_name"
value="<?php echo $cur_package; ?>">
<input type="submit" name="submit" value="Search">
</form>
<?php
/* If we have results and it is an array, then output the key/value pairs */
if ($results && is_array($results)) {
?>
<table border="0">
<tr>
<th colspan="2">Package Information for <?php echo $cur_package; ?></th>
</tr>
<?php
foreach($results AS $key=>$value) {
/* Skip output of empty and complex values */
if (empty($value) || is_array($value)) continue;
?>
<tr>
<td align="right"><?php echo $key; ?>:</td>
<td align="left"><?php echo $value; ?></td>
</tr>
<?php } /* End foreach */
} /* End if */
?>
</table>
</body>
</html>
Entering XML_RPC as the package on which to search results in the page shown in Figure 16-1.
Conclusion
Calling remote procedures is not something new. Many technologies, such as DCOM and CORBA, allow for RPC to take place. However, many of these are difficult to implement and are even tied to specific platforms. XML-RPC was developed as a platform- and language-neutral mechanism of exchanging data and allowing remote functions to be called, marshaling the data in XML format. It also defined a universal transport agent, HTTP POST, allowing virtually every computer to be able to interact with each other.
XML-RPC was pretty much the first official Web service. I say official, as you will see in the next chapter, because XML has been exchanged between systems since it was conceived, although no official nomenclature was ever given to the method until recently. With SOAP and REST becoming more popular, XML-RPC usage has been on a decline, with many serv- ices switching over to these other technologies. This does not mean XML-RPC is no longer used. When compared to the other technologies, XML-RPC does have its place. For instance, compared to using REST, XML-RPC provides a defined format for marshaling data, while REST does not. SOAP, on the other hand, provides all the features of XML-RPC and then some, but many feel overwhelmed by the complexity of it; XML-RPC is much easier to use.
The next chapter will begin the coverage of the common methods for using and imple- menting Web services. The first of these is REST.
Figure 16-1.Example output information for the XML_RPC package
Representational State Transfer (REST)
Representational State Transfer (REST) is not a specific standard like many of the other technologies covered in this book. Instead, it is an architectural style utilizing commonly found technologies and protocols that in this case will be used to implement and utilize REST-based Web services. This chapter will provide some background and information regarding REST, but it focuses more on utilizing REST for Web services and uses the services available from Yahoo and Amazon as examples.