Programming Web Services with Perl

This is the Title of the Book, eMatter Edition

Copyright © 2007 O’Reilly & Associates, Inc. All rights reserved.

RPC::XML

|

323

match_signature(signature)

Attempts to match a signature to the object’s signature table. If found, the

expected return type is passed back. If it isn’t found, a

false value is returned.

call(server object, parameters)

Calls the underlying Perl code, with the parameters passed in the arguments list.

The first argument to

call must be an object that derives from RPC::XML::Server.

The server object is the initial parameter in the list when calling code that is sup-

posed to behave like a class method. The return value is a data object of the type

that matches the signature of the arguments passed in.

reload

Tells the object to reload the XPL file it was originally created from. If it isn’t

loaded from an XPL file, the method silently returns without doing anything.

RPC::XML::Method

Code objects created in the RPC::XML::Method class call their encapsulated code refer-

ences in a fashion that emulates a method call. The server object is passed as the first

parameter in the list to the Perl subroutine. Using this object reference, the code may

interact with the server to get information about how it was called (by what name,

and by what signature) or to call other routines on the server by their published

interface, rather than requiring internal knowledge.

RPC::XML::Method derives from RPC::XML::Procedure.

RPC::XML::Procedure

The RPC::XML::Procedure class of code objects calls its encapsulated subroutines with

an ordinary argument list. The server object isn’t available to the code being invoked.

RPC::XML::Function

This class of code objects doesn’t use signatures. It is designed for quick and simple

creation of XML-RPC wrappers around existing code and libraries. Calls to the

underlying Perl subroutine are done the same way as with the

XML::RPC::Procedure

class. As such, these routines don’t have access to the server object.

RPC::XML::Function derives from XML::RPC::Procedure.

Apache::RPC::Server

The Apache::RPC::Server class is a subclass of XML::RPC::Server that is engineered

especially for use as an

Apache/mod_perl location handler. The following methods are

unique to this package or significantly different from the parent class:

This is the Title of the Book, eMatter Edition

Copyright © 2007 O’Reilly & Associates, Inc. All rights reserved.

324

|

Appendix A: XML-RPC Toolkit Programming Reference

handler

This method is defined so that mod_perl can use the class directly as a location

handler. It’s prototyped as a method handler in

mod_perl terms, allowing

applications to subclass it if desired. It’s called as a method (meaning that an

object reference or package name is the first parameter passed in) with the

Apache object (the request) as a parameter.

init_handler

This method is provided as a possible handler for the mod_perl

PerlChildInitHandler

phase. As implemented, it calls the child_started method

only on each XML-RPC server object within the internal table

Apache::RPC::

Server

maintains. It is also prototyped as a method handler, so it too may be

overridden in a subclass.

new(key/value pairs)

The constructor for this class is a little different from its parent. It calls the par-

ent constructor to create the actual object, and most of the parameters are

passed through directly to the parent (along with setting

no_http). It also

attempts to configure itself as much as possible from the Apache environment

and then adds itself to an internal table that the class maintains, before return-

ing the new object reference. Here are the parameters directly used by this con-

structor (not passed to the parent):

apache

A reference to an Apache object reference, which is used to access location

configuration information and other needed internals.

server_id

The server ID is just a string that distinguishes XML-RPC servers within a

single Apache server. Because multiple servers may be set up from Apache

configuration blocks alone, this offers an alternative to using

<Perl> blocks

to set up such situations. If not passed, the URL location that Apache has

the handler mapped to is used.

prefix

Provides a prefix that is applied to all the directory-level configuration

options

new attempts to locate and use. Overrides any value that might be set

by the Apache configuration for the option prefix.

Configuration of the

Apache::RPC::Server objects using directory configuration

values is covered in detail in the manpage for this class.

child_started(optional boolean)

Similar to the started method in the parent class, but it keeps a separate value

from the start time. Under

mod_perl, the server objects may be created during

initialization and passed to child processes when Apache creates them. This

value notes when the given child started, versus when the server object itself may

have started.