NAME

SYNOPSIS

    require RPC::XML::Procedure;

    ...
    $procedure = RPC::XML::Procedure->new({ name => 'system.identity',
                                            code => sub { ... },
                                            signature => [ 'string' ] });
    $method    = RPC::XML::Method->new('/path/to/status.xpl');
    $function  = RPC::XML::Function->new(name => 'add',
                                         code => sub { ... });

DESCRIPTION

This package grew out of the increasing need to abstract the operations that related to the methods a given server instance was providing. Previously, methods were passed around simply as hash references. It was a small step then to move them into a package and allow for operations directly on the objects themselves. In the spirit of the original hashes, all the key data is kept in clear, intuitive hash keys (rather than obfuscated as the other classes do). Thus it is important to be clear on the interface here before sub-classing this package.

CLASSES

Methods (RPC::XML::Method)

Code that is considered a "method" by the server is called as though it were, in fact, a method in that class. The first argument in the list is the server object itself, with the arguments to the call making up the rest of the list. The server checks the signature of the method against the arguments list before the call is made. See below ("How Procedures Are Called") for more on the invocation of code as methods.

Procedures (RPC::XML::Procedure)

Code that is considered a "procedure" by the server is called like a normal (non-method) subroutine call. The server object is not injected into the arguments list. The signature of the procedure is checked again the list of arguments before the call is made, as with methods.

Functions (RPC::XML::Function)

Lastly, code that is considered a "function" is the simplest of the three: it does not have the server object injected into the arguments list, and no check of signatures is done before the call is made. It is the responsibility of the function to properly understand the arguments list, and to return a value that the caller will understand.

There is (currently) no version that is called like a method but ignores signatures like a function.

SUBROUTINES/METHODS

new(FILE|HASHREF|LIST)

Creates a new object of the class, and returns a reference to it. The arguments to the constructor are variable in nature, depending on the type:

clone

Create a copy of the calling object, and return the new reference. All elements are copied over cleanly, except for the code reference stored on the "code" hash key. The clone will point to the same code reference as the original. Elements such as "signature" are copied, so that changes to the clone will not impact the original.

name

Returns the name by which the server is advertising the method. Unlike the next few accessors, this cannot be changed on an object. In order to streamline the management of methods within the server classes, this must persist. However, the other elements may be used in the creation of a new object, which may then be added to the server, if the name absolutely must change.

namespace

If the procedure object was created from a file, or if the instantiation included namespace information, this accessor will return the namespace that the underlying code executes in. Otherwise, it returns an empty string. This cannot be altered (even if the code method is used to replace the code routine).

code([NEW])

Returns or sets the code-reference that will receive calls as marshalled by the server. The existing value is lost, so if it must be preserved, then it should be retrieved prior to the new value being set.

signature([NEW])

Return a list reference containing the signatures, or set it. Each element of the list is a string of space-separated types (the first of which is the return type the method produces in that calling context). If this is being used to set the signature, then an array reference must be passed that contains one or more strings of this nature. Nested list references are not allowed at this level. If the new signatures would cause a conflict (a case in which the same set of input types are specified for different output types), the old set is silently restored.

help([NEW])

Returns or sets the help-text for the method. As with code, the previous value is lost.

hidden([NEW])

Returns or sets the hidden status of the method. Setting it loses the previous value.

version([NEW])

Returns or sets the version string for the method (overwriting as with the other accessors).

add_signature(LIST)

Add one or more signatures (which may be a list reference or a string) to the internal tables for this method. Duplicate signatures are ignored. If the new signature would cause a conflict (a case in which the same set of input types are specified for different output types), the old set is restored and an error message is returned.

delete_signature(LIST)

Deletes the signature or signatures (list reference or string) from the internal tables. Quietly ignores any signature that does not exist. If the new signature would cause a conflict (a case in which the same set of input types are specified for different output types), the old set is restored and an error message is returned.

match_signature(SIGNATURE)

Check that the passed-in signature is known to the method, and if so returns the type that the method should be returning as a result of the call. Returns a zero (0) otherwise. This differs from other signature operations in that the passed-in signature (which may be a list-reference or a string) does not include the return type . This method is provided so that servers may check a list of arguments against type when marshalling an incoming call. For example, a signature of 'int int' would be tested for by calling "$M->match_signature('int')" and expecting the return value to be "int".

call(SERVER, PARAMLIST)

Execute the code that this object encapsulates, using the list of parameters passed in PARAMLIST. The SERVER argument should be an object derived from the RPC::XML::Server class. For some types of procedure objects, this becomes the first argument of the parameter list to simulate a method call as if it were on the server object itself. The return value should be a data object (possibly a RPC::XML::fault), but may not always be pre-encoded. Errors trapped in $@ are converted to fault objects. This method is generally used in the "dispatch" method of the server class, where the return value is subsequently wrapped within a RPC::XML::response object.

reload

Instruct the object to reload itself from the file it originally was loaded from, assuming that it was loaded from a file to begin with. Returns an error if the method was not originally loaded from a file, or if an error occurs during the reloading operation.

NAMESPACES

To give developers control over the namespace in XPL code, a new optional tag "<namespace>" was added in the 0.65 release. If this tag is present in the XPL being read, it defines the namespace that the "<code>" block is evaluated in.

The value of the namespace tag is a string providing the namespace in either the Perl-style of hierarchy parts separated by "::", or the style used by Java, Perl6, etc., in which the parts are separated by ".". The latter form is converted to Perl style for the evaluation of the code. If there is no namespace declaration in a XPL file, the namespace of the class that loads the XPL is used.

DIAGNOSTICS

CAVEATS

BUGS

SUPPORT

• RT: CPAN's request tracker

  <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>

• AnnoCPAN: Annotated CPAN documentation

  <http://annocpan.org/dist/RPC-XML>

• CPAN Ratings

  <http://cpanratings.perl.org/d/RPC-XML>

• Search CPAN

  <http://search.cpan.org/dist/RPC-XML>

• MetaCPAN

  <https://metacpan.org/release/RPC-XML>

• Source code on GitHub

  <http://github.com/rjray/rpc-xml>

LICENSE AND COPYRIGHT

Copying and distribution are permitted under the terms of the Artistic License 2.0 (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).

CREDITS

SEE ALSO

AUTHOR