RPC::XML Module

Part:   1   2  3  4 

This chapter describes:

• What is RPC::XML?
• How to install NMake 1.5.
• How to install RPC::XML 0.57.
• Example programs on how to use RPC::XML.
• More example programs on how to pass an array as an input argument.

What Is RPC::XML?

RPC::XML is a Perl implementation of the XML-RPC specification developed by Randy J. Ray. RPC::XML offers:

• An XML-RPC server, and a server side programming interface.
• An group of classes to represent various XML elements of XML-RPC value types.
• An XML-RPC client side programming interface.

RPC::XML contains the following classes:

1. RPC::XML::Server - A XML-RPC server and programming interface for remote method handlers. It supports the following methods:

new(host=>'hostName', port=>'port', queue=>'queueSize') - Constructs and returns a XML-RPC server object that listens on the specified host name at the specified port with the specified queue size. The following statement shows you an example of how to use this constructor:

   $server = RPC::XML::Server->new(host => 'localhost', 
      port => '8001', queue='5');

add_method({name=>'methodName', signature=>\@sigList, code=>\&function}) - Adds a method to the server with a hash to specify the method name, the signature list, and the actual function that handles the method. The following statement adds a method called "com.herong.getCelsius" to the server. This method has one signature of returning 'double' and taking one 'double'. The method handler is a function called "getCelsius".

   $server->add_method({ name => 'com.herong.getCelsius',
      signature => [ 'double double' ], code => \&getCelsius });

Rules on adding methods and dispatching method calls:

• A signature is a space delimited data types, with the first one being the return data type, and the rest being input parameters.
• Multiple signatures can be specified when adding a method to allow the method to be called in multiple ways. For example, if "signature => [ 'double', 'double double' ]" is used, the method can be called with no parameter, or with one 'double' parameter. Please note that the manual is very unclear about how signature should be used.
• When the server receives a XML-RPC request, it will validate the request against the specified signatures. The server will not dispatch the call if the request can not match any signature.
• If a XML-RPC request matches a signature, it will dispatch the call to the specified handler function with all given parameters in the request plus the server object as the first argument. This is similar to the function call behavior when using the '->' operator.
• When a handler function returns, the server will take returning value and convert it to the return data type specified in the method signature.
• The server will evaluate the handler function returning value in scalar context. This means that means if the handler function returns a list, the server will get one value, the number of values in the list.
• If the handler functions returns an object (really a reference), the server will take the content of the object and convert it to the return data type. For example, if the return data type is 'array', and the handler function is returning a reference to a list, all elements in the list will be returned as an 'array'.

server_loop() - Starts the server in listen mode.

2. RPC::XML::int - A data class representing the XML-RPC '*.value.int' element. It supports the following methods:

new($value) - Constructs and returns a XML-RPC 'int' object with the specified value.

type() - Returns the data type name as a string.

value() - Returns the value as a string

3. RPC::XML::$valueType - Other data classes representing other XML-RPC value type elements. All data classes supports the same methods as the RPC::XML::int class. For RPC::XML::array or RPC::XML::struct, method value() will return a reference of array or hash.

4. RPC::XML::request - A message class representing the XML-RPC 'methodCall' element. It supports the following methods:

new('methodName', param1, param2, ...) - Constructs and returns a XML-RPC request object with the specified method name and parameters. Specified parameters must be objects of RPC::XML data classes. The following statement shows you how to construct a request:

   $request = RPC::XML::request->new('com.herong.getCelsius',
      RPC::XML:double->new('100.0'));

as_string() - Returns the XML string representation of the request.

5. RPC::XML::Client - A XML-RPC client and programming interface for connecting to the server, sending method calls, and receiving returning values. It supports the following methods:

new('url') - Constructs and returns a XML-RPC client object that connects to a server at the specified URL.

send_request($request) - Sends the specified request to the server, and returns a RPC::XML data object representing the only "param" returned in the XML-RPC response. Here is an example of how to use send_request():

   $res = $client->send_request($request);

(Continued on next part...)

Part:   1   2  3  4