++ed by:

1 PAUSE user

Randy J Ray


Apache::RPC::Server - A subclass of RPC::XML::Server tuned for mod_perl


    # In httpd.conf:
    PerlModule Apache::RPC::Server
    PerlChildInitHandler Apache::RPC::Server->init_handler
    <Location /RPC>
        SetHandler perl-script
        PerlHandler Apache::RPC::Server
    </Location /RPC-limited>
        SetHandler perl-script
        PerlHandler Apache::RPC::Server
        PerlSetVar RPCOptPrefix RpcLimit
        PerlSetVar RpcLimitRpcServer Limited
        PerlSetVar RpcLimitRpcMethodDir /usr/lib/perl5/RPC-shared

    # In the start-up Perl file:
    use Apache::RPC::Server;

















The arguments to the constructor are regarded as a hash table (not a hash reference), and are mostly passed unchanged to the constructor for RPC::XML::Server. Three parameters are of concern to this class:


The value associated with this key is a reference to an Apache request object. If this is not passed, then it is assumed that this is being called in the start-up phase of the server and the value returned from Apache-server> (see Apache) is used.


This provides the server ID string for the RPC server (not to be confused with the Apache server) that is being configured.


The prefix is used in retrieving certain configuration settings from the Apache configuration file.

The server identification string and prefix concepts are explained in more detail in the next section. See RPC::XML::Server for a full list of what additional arguments may be passed to new for eventual proxy to the parent class constructor.






Apache configuration semantics




RpcServer [STRING]



RpcMethodDir [DIRECTORY]


RpcMethod [FILENAME]


RpcDefMethods [YES|NO]


RpcAutoMethods [YES|NO]


RpcAutoUpdates [YES|NO]

If specified and set to "yes", enables the checking of the modification time of the file from which a method was originally loaded. If the file has changed, the method is re-loaded before execution is handed off. As with the auto-loading of methods, this represents a potential security risk, and should only be permitted by a server administrator with fully informed acknowledgement and consent.

Specifying methods to the server(s)


Default methods


Configured directories


By specific inclusion



Usage Within <Perl> Sections

To truly unlock the power of having the RPC server attached to a mod_perl environment, the application and configuration of the server should be done within Perl-configuration blocks on the Apache server itself.

In doing this, two immediate benefits are gained:


The rpc-server object gets created in the master Apache process, rather than within each child as a side-effect of the first request. Especially in cases where there are going to be more than one server in use within the Apache environment, this boosts performance by allowing newly-created children to already have the server object and method table readily available.


It becomes possible to exert more detailed control over the creation and configuration of each server object. Combining the get_method and add_method operations permits "sharing" (of a sort) of methods between server objects. Recall from the RPC::XML::Server documentation that, when a method is invoked, the first argument is the server object that is marshalling it.

The following example illustrates these concepts in a fairly simple environment:

    # In httpd.conf:

    # First, create and configure some Apache::RPC::Server objects

    # One regular one, with the standard settings:
    $main::defobj = Apache::RPC::Server->new(path         => '/RPC',
                                             auto_methods => 1,
                                             auto_updates => 1);
    # One version without the default methods, and no auto-actions
    $main::secobj = Apache::RPC::Server->new(no_default => 1,
                                             path => '/rpc-secured');

    # Imagine that add_method and/or add_methods_in_dir has been used to
    # add to the methods tables for those objects. Now assign them to
    # locations managed by Apache:
    $Location{'/RPC'} =
            SetHandler  => 'perl-script',
            PerlHandler => '$main::defobj'
    $Location{'/rpc-secure'} =
            SetHandler   => 'perl-script',
            PerlHandler  => '$main::secobj',
            AuthUserFile => '/etc/some_file',
            AuthType     => 'Basic',
            AuthName     => 'SecuredRPC',
            'require'    => 'valid-user'


Note that the assignment of the PerlHandler value was a string representation of the object reference itself. mod_perl performs a sort of "thaw" of this string when the location is accessed. Since this class implements itself as a method handler, this causes the handler() method for each of the locations to be handed the Apache::RPC::Server object directly. Note also that the value assigned to PerlHandler cannot be a lexical variable, or it will be out of scope when the handler is called.











RPC::XML::Server, RPC::XML


Randy J. Ray <rjray@blackperl.com>