A.2 XMLRPC::Lite

The XMLRPC::Lite package and related classes are part of the larger SOAP::Lite package, which is described in greater detail in Appendix B. The coverage will focus on only the XML-RPC aspects. Many classes described here inherit from SOAP::Lite counterparts. In these cases a basic definition is provided, leaving the main definitions to accompany their classes in Appendix B.

The following is based on Release 0.55 of SOAP::Lite .

A.2.1 XMLRPC::Lite

The following classes are all made available by loading the XMLRPC::Lite module. There are also some behind-the-scenes classes that aren't documented here, because they aren't intended to be replaced or extended.

A.2.1.1 XMLRPC::Lite

Inherits from: SOAP::Lite .

This class is used for creating client objects that in turn communicate with remote servers. There are more methods available to this class than are listed here, because it inherits directly from SOAP::Lite . Many methods in that class aren't relevant to implementing XML-RPC, so the object attributes they manipulate are ignored by the serializer.

One noteworthy feature that XMLRPC::Lite inherits from its parent class is the automatic creation of object as needed, when methods are called as class methods. In most applications, an explicit creation of the client object with new is generally not needed. Some of the methods may also be used at compile-time to influence global behavior. This will be explained after the method listing. All methods return the object reference on success unless otherwise specified. Errors trigger either the fault handler or a call to die .

new( optional argument list )

This is the class constructor, which creates new objects. It requires no arguments itself, and treats any arguments passed in as key/value pairs in which the key is one of the following method names , and the value is the argument to pass in when calling that method (if a method requires two or more parameters, the value would be an array reference). All methods are invoked after the new object has been allocated and blessed into the appropriate class.

proxy( URL )

Set or retrieve the current value of the address the client is to connect to. The value may also be changed with the next method, but proxy must be called first because it handles the loading of the appropriate support for the transport scheme (HTTP, etc.). Returns the current value if called with no argument.

endpoint( URL )

Change the address the client connects to, without reloading the transport code. The new address must use the same scheme as the previous value. Returns the current endpoint if called with no argument.

call( method name , optional parameters )

Call a remote method by name, optionally with the parameters specified in the rest of the parameter list. XMLRPC::Lite objects can call remote methods as if they are local methods on the object itself, but some method names may contain characters Perl doesn't permit in a subroutine name.

serializer( optional value )

Sets (or returns, if called with no argument) the serializer object used by this object for turning requests into XML. Applications should rarely need to change this value, but retrieving the object makes it possible to call the methods detailed later under XMLRPC::Serializer .

deserializer( optional value )

Like serializer but operates on the deserialization object, which turns incoming XML into Perl data for handling by the rest of the application.

readable( boolean )

A shortcut for $obj->serializer->readable($boolean) . If set to true , the serializer puts extra line breaks and space in the XML to make it visually appealing.

on_fault( optional value )

Sets or returns (when called with no parameter) the value of the code reference used when a fault happens. The subroutine reference (if set) is invoked with a single parameter, the XMLRPC::SOM object that contains the fault. If no on_fault handler is set, the default action is to call die with the text of the fault.

A.2.1.2 XMLRPC::Data

Inherits from: SOAP::Data .

The XMLRPC::Data class is made available to aid in serializing Perl data that is ambiguous enough that the serializer can't always automatically identify the type. Unlike SOAP, data in XML-RPC is relatively free of metadata, so using this class is much simpler and clearer than its parent class.

Objects need only be created when the value in question needs explicit typing. Once an object is created, the type and value may be manipulated with these methods:

new( arguments )

Creates a new data object. If there is only one argument, it is taken as the value to encapsulate, and the type is inferred from the appearance. If the argument is a series of key/value pairs, the keys must correspond to available XMLRPC::Data class methods, and the values are arguments. The keys may be either of type or value , though there are some methods that are ignored by XML-RPC (but will not cause a runtime error if present).

type( new type, optional value )

Sets the type for the data object or gets the current value if no arguments are passed. The type should be one of: int , i4 , double , string , dateTime , or base64 . If a second value is included, it is assumed to be a new value for the object and replaces any current value.

value( new value )

Sets the value for the object, or if called with no arguments, returns the current value.

XMLRPC::Data objects may be passed as parameters when using the call method on a XMLRPC::Lite object (or when using the indirect or autodispatch approaches).

A.2.1.3 XMLRPC::SOM

Inherits from: SOAP::SOM .

All values returned from calls made by a client object are instances of this class. While this class has access to all the methods from SOAP::SOM, the convenience methods listed here are recommended rather than using match and valueof with various arguments.

match( path )

Matches the expression passed in, returning a new XMLRPC::SOM object for the node that is matched. The path syntax is based on XPath. Refer to the documentation for this method under SOAP::SOM for more information.

valueof( node )

Retrieves the data contained within the node passed in as an argument. The node value should be a XPath-like expression and is evaluated in the context of the node value calling the method. More detail is available under the SOAP::SOM section in Appendix B.

The following are the supported convenience methods that return data in Perl format rather than serialized or object-encapsulated format.

envelope

Returns the "envelope" of the message, which in the case of XML-RPC means a hash reference with one key. The key will be either methodCall or methodResponse , depending on the nature of the message. However, because this is most likely used on the client side, methodResponse will be more common. The value associated with the key will be a hash reference representing the rest of the message.

method

Returns the method name in a request message. Specifically, it is the data of the methodName element.

fault

If the message encapsulates a XML-RPC fault, this method returns a hash reference with two keys, faultCode and faultString . If the message contained no fault, undef is returned.

faultcode , faultstring

These methods are shortcuts to the two elements of a fault, without having to retrieve the fault first (using the previous method). If there is no fault, the return value from either of these is undef .

result

For an object that represents the result of a remote call, this method returns the actual result value (as Perl data). If the message is a fault, this method returns undef .

The following two methods provide access to the parameter lists of XMLRPC::SOM objects. They are defined here because they behave slightly differently from the inherited methods by the same name in SOAP::SOM .

paramsin

Returns a XMLRPC::SOM object containing all parameters to a methodCall message. Returns nothing if called on a response message.

paramsall

Returns a XMLRPC::SOM object encapsulating the return parameter from a response message. Returns nothing ( undef ) if called on a request message.

A.2.1.4 XMLRPC::Deserializer and XMLRPC::Serializer

Inherits from: SOAP::Deserializer and SOAP::Serializer , respectively.

The deserialization object is used by both client and server objects to transform XML messages into Perl data, while the serialization object transforms requests and responses from Perl data to XML messages. XML-RPC is much more stringent than SOAP because there are no permitted alternatives for encoding; for this reason, application developers shouldn't need to subclass or otherwise alter these objects. However, if such a need arises, you use the same set of methods as their SOAP::Lite counterparts, with some overridden for XML-RPC application.

A.2.1.5 XMLRPC::Server

Inherits from: SOAP::Server .

This class derives from the SOAP::Lite equivalent and overrides the initialization code to provide functionality geared towards XML-RPC. It isn't meant to be used directly by application developers but rather allows the server classes that are defined later a common initialization method that can be shared.

A.2.1.6 XMLRPC::Server::Parameters

Inherits from: SOAP::Server::Parameters .

This is an empty class for use when writing code for deployment through a server based on the XMLRPC::Server class. It inherits two methods from the parent class, but the primary purpose is to be a superclass to code written for a XML-RPC server. When a server derived from the server classes (that are detailed later) dispatches an incoming request, it checks to see if the class to which the receiving method belongs inherits from this class. If so, the XMLRPC::SOM object that represents the message's envelope is added at the end of the list of parameters to the local subroutine call.

A.2.2 XMLRPC::Transport::HTTP

This module provides the implementation of HTTP transport for servers. Clients don't use modules from the XMLRPC::Transport::* hierarchy because they can use the same transport code SOAP::Lite does.

This module provides three different server classes to use either directly or as parent classes for new code. All three classes inherit from their SOAP::Lite counterparts. None define any new methods of their own; methods should be taken from the class listings in Appendix B. In particular, the methods of note for the classes used for XML-RPC serving are new , dispatch_to , and handle .

A.2.2.1 XMLRPC::Transport::HTTP::CGI

Inherits from: SOAP::Transport::HTTP::CGI .

This class is designed for use in standard CGI environments.

A.2.2.2 XMLRPC::Transport::HTTP::Daemon

Inherits from: SOAP::Transport::HTTP::Daemon .

The implementation of this class uses an object of the HTTP::Daemon class, from the LWP module, to provide the actual server functionality.

A.2.2.3 XMLRPC::Transport::HTTP::Apache

Inherits from: SOAP::Transport::HTTP::Apache .

This class is designed to work as a basis for an Apache/ mod_perl content handler that serves XML-RPC requests. It doesn't operate in quite the same way as the daemon-based server described earlier; it expects the traditional server loop functionality to be handled by Apache rather than within the class.

A.2.3 XMLRPC::Transport::POP3

This module provides just the XMLRPC::Transport::POP3::Server class, which inherits from SOAP::Transport::POP3::Server . It implements a XML-RPC server that reads the incoming messages from a POP3 mailbox. XML-RPC clients may use the mailto: scheme to send such requests.

A.2.4 XMLRPC::Transport::TCP

This module provides just a XMLRPC::Transport::TCP::Server class, which inherits from SOAP::Transport::TCP::Server in this case. This implements a server that uses straight TCP/IP rather than HTTP for communication. Clients may also use a scheme of tcp: to communicate with such servers.