| Current File : //opt/RZperl536/man/man3/RPC::XML::Procedure.3 |
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "RPC::XML::Procedure 3"
.TH RPC::XML::Procedure 3 "2016-05-15" "perl v5.36.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
RPC::XML::Procedure \- Object encapsulation of server\-side RPC procedures
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& require RPC::XML::Procedure;
\&
\& ...
\& $procedure = RPC::XML::Procedure\->new({ name => \*(Aqsystem.identity\*(Aq,
\& code => sub { ... },
\& signature => [ \*(Aqstring\*(Aq ] });
\& $method = RPC::XML::Method\->new(\*(Aq/path/to/status.xpl\*(Aq);
\& $function = RPC::XML::Function\->new(name => \*(Aqadd\*(Aq,
\& code => sub { ... });
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBRPC::XML::Procedure\fR package is designed primarily for behind-the-scenes
use by the \fBRPC::XML::Server\fR class and any subclasses of it. It is
documented here in case a project chooses to sub-class it for their purposes
(which would require setting the \f(CW\*(C`method_class\*(C'\fR attribute when creating
server objects, see RPC::XML::Server).
.PP
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.
.SH "CLASSES"
.IX Header "CLASSES"
This module provides three classes, representing the three types of procedures
that servers can use:
.IP "Methods (\fBRPC::XML::Method\fR)" 4
.IX Item "Methods (RPC::XML::Method)"
Code that is considered a \*(L"method\*(R" 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 (\*(L"How Procedures Are Called\*(R") for more
on the invocation of code as methods.
.IP "Procedures (\fBRPC::XML::Procedure\fR)" 4
.IX Item "Procedures (RPC::XML::Procedure)"
Code that is considered a \*(L"procedure\*(R" 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.
.IP "Functions (\fBRPC::XML::Function\fR)" 4
.IX Item "Functions (RPC::XML::Function)"
Lastly, code that is considered a \*(L"function\*(R" 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.
.PP
There is (currently) no version that is called like a method but ignores
signatures like a function.
.SH "SUBROUTINES/METHODS"
.IX Header "SUBROUTINES/METHODS"
The following methods are provided by this class:
.IP "new(FILE|HASHREF|LIST)" 4
.IX Item "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:
.RS 4
.IP "\s-1FILE\s0" 8
.IX Item "FILE"
If there is exactly on argument that is not a reference, it is assumed to be a
filename from which the method is to be loaded. This is presumed to be in the
\&\fB\s-1XPL\s0\fR format described below (see \*(L"\s-1XPL\s0 File Structure\*(R"). If the file
cannot be opened, or if once opened cannot be parsed, an error is raised.
.IP "\s-1HASHREF\s0" 8
.IX Item "HASHREF"
If there is exactly one argument that is a reference, it is assumed to be a
hash with the relevant information on the same keys as the object itself
uses. This is primarily to support backwards-compatibility to code written
when methods were implemented simply as hash references.
.IP "\s-1LIST\s0" 8
.IX Item "LIST"
If there is more than one argument in the list, then the list is assumed to be
a sort of \*(L"ersatz\*(R" hash construct, in that one of the keys (\f(CW\*(C`signature\*(C'\fR) is
allowed to \*(L"stack\*(R" if it occurs multiple times. Otherwise, any keys that occur
multiple times overwrite the previous value:
.RS 8
.IP "name" 12
.IX Item "name"
The name of the method, as it will be presented to clients
.IP "code" 12
.IX Item "code"
A reference to a subroutine, or an anonymous subroutine, that will receive
calls for the method
.IP "signature" 12
.IX Item "signature"
Provides one calling-signature for the method, as either a space-separated
string of types or a list-reference
.IP "help" 12
.IX Item "help"
The help-text for a method, which is generally used as a part of the
introspection interface for a server
.IP "version" 12
.IX Item "version"
The version number/string for the method
.IP "hidden" 12
.IX Item "hidden"
A boolean (true or false) value indicating whether the method should be hidden
from introspection and similar listings
.RE
.RS 8
.Sp
Note that all of these correspond to the values that can be changed via the
accessor methods detailed later.
.RE
.RE
.RS 4
.Sp
If any error occurs during object creation, an error message is returned in
lieu of the object reference.
.RE
.IP "clone" 4
.IX Item "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
\&\f(CW\*(C`code\*(C'\fR hash key. The clone will point to the same code reference as the
original. Elements such as \f(CW\*(C`signature\*(C'\fR are copied, so that changes to the
clone will not impact the original.
.IP "name" 4
.IX Item "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.
.IP "namespace" 4
.IX Item "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 \fBcode\fR method is used to replace the code
routine).
.IP "code([\s-1NEW\s0])" 4
.IX Item "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.
.IP "signature([\s-1NEW\s0])" 4
.IX Item "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.
.IP "help([\s-1NEW\s0])" 4
.IX Item "help([NEW])"
Returns or sets the help-text for the method. As with \fBcode\fR, the previous
value is lost.
.IP "hidden([\s-1NEW\s0])" 4
.IX Item "hidden([NEW])"
Returns or sets the hidden status of the method. Setting it loses the previous
value.
.IP "version([\s-1NEW\s0])" 4
.IX Item "version([NEW])"
Returns or sets the version string for the method (overwriting as with the
other accessors).
.IP "add_signature(\s-1LIST\s0)" 4
.IX Item "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.
.IP "delete_signature(\s-1LIST\s0)" 4
.IX Item "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.
.IP "match_signature(\s-1SIGNATURE\s0)" 4
.IX Item "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) \fB\f(BIdoes not
include the return type\fB\fR. 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 \f(CW\*(Aqint int\*(Aq\fR would be tested for by calling
\&\f(CW\*(C`$M\->match_signature(\*(Aqint\*(Aq)\*(C'\fR and expecting the return value to be \f(CW\*(C`int\*(C'\fR.
.IP "call(\s-1SERVER, PARAMLIST\s0)" 4
.IX Item "call(SERVER, PARAMLIST)"
Execute the code that this object encapsulates, using the list of parameters
passed in \s-1PARAMLIST.\s0 The \s-1SERVER\s0 argument should be an object derived from the
\&\fBRPC::XML::Server\fR 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 \fBRPC::XML::fault\fR), but may not always be pre-encoded. Errors
trapped in \f(CW$@\fR are converted to fault objects. This method is generally used
in the \f(CW\*(C`dispatch\*(C'\fR method of the server class, where the return value is
subsequently wrapped within a \fBRPC::XML::response\fR object.
.IP "reload" 4
.IX Item "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.
.SS "Additional Hash Data"
.IX Subsection "Additional Hash Data"
In addition to the attributes managed by the accessors documented earlier, the
following hash keys are also available for use. These are also not strongly
protected, and the same care should be taken before altering any of them:
.IP "file" 4
.IX Item "file"
When the method was loaded from a file, this key contains the path to the file
used.
.IP "namespace" 4
.IX Item "namespace"
If the code is loaded from a file, this hash key will reflect what namespace
the code executes in. If the file specified a namespace, that is the value
you will get (any occurrence of \f(CW\*(C`.\*(C'\fR in the specified namespace will have been
converted to \f(CW\*(C`::\*(C'\fR). If no explicit namespace was provided, the namespace
of the class you called \fBnew\fR from will be used. See \*(L"Namespaces\*(R".
.IP "mtime" 4
.IX Item "mtime"
When the method was loaded from a file, this key contains the
modification-time of the file, as a UNIX-style \f(CW\*(C`time\*(C'\fR value. This is used to
check for changes to the file the code was originally read from.
.IP "called" 4
.IX Item "called"
When the method is being used by one of the server classes provided in this
software suite, this key is incremented each time the server object dispatches
a request to the method. This can later be checked to provide some indication
of how frequently the method is being invoked.
.SS "\s-1XPL\s0 File Structure"
.IX Subsection "XPL File Structure"
This section focuses on the way in which methods are expressed in these files,
referred to here as \*(L"\s-1XPL\s0 files\*(R" due to the \f(CW\*(C`*.xpl\*(C'\fR filename extension
(which stands for \*(L"\s-1XML\s0 Procedure Layout\*(R"). This mini-dialect, based on \s-1XML,\s0
is meant to provide a simple means of specifying method definitions separate
from the code that comprises the application itself. Thus, methods may
theoretically be added, removed, debugged or even changed entirely without
requiring that the server application itself be rebuilt (or, possibly, without
it even being restarted).
.IP "The XML-based file structure" 4
.IX Item "The XML-based file structure"
The \fB\s-1XPL\s0 Procedure Layout\fR dialect is a very simple application of \s-1XML\s0 to the
problem of expressing the method in such a way that it could be useful to
other packages than this one, or useful in other contexts than this one.
.Sp
The lightweight \s-1DTD\s0 for the layout can be summarized as:
.Sp
.Vb 10
\& <!ELEMENT proceduredef (name, namespace?, version?, hidden?,
\& signature+, help?, code)>
\& <!ELEMENT methoddef (name, namespace?, version?, hidden?,
\& signature+, help?, code)>
\& <!ELEMENT functiondef (name, namespace?, version?, hidden?,
\& signature+, help?, code)>
\& <!ELEMENT name (#PCDATA)>
\& <!ELEMENT namespace (#PCDATA)>
\& <!ELEMENT version (#PCDATA)>
\& <!ELEMENT hidden EMPTY>
\& <!ELEMENT signature (#PCDATA)>
\& <!ELEMENT help (#PCDATA)>
\& <!ELEMENT code (#PCDATA)>
\& <!ATTLIST code language (#PCDATA)>
.Ve
.Sp
The containing tag is always one of \f(CW\*(C`<methoddef>\*(C'\fR, \f(CW\*(C`<proceduredef>\*(C'\fR
or \f(CW\*(C`<functiondef>\*(C'\fR. The tags that specify name, signatures and the code
itself must always be present. Some optional information may also be
supplied. The \*(L"help\*(R" text, or what an introspection \s-1API\s0 would expect to use to
document the method, is also marked as optional. Having some degree of
documentation for all the methods a server provides is a good rule of thumb,
however.
.Sp
The default methods that this package provides are turned into \s-1XPL\s0 files by the
\&\fBmake_method\fR tool (see make_method). The final forms of these
may serve as examples of what the file should look like.
.IP "Information used only for book-keeping" 4
.IX Item "Information used only for book-keeping"
Some of the information in the \s-1XPL\s0 file is only for book-keeping: the version
stamp of a method is never involved in the invocation. The server also keeps
track of the last-modified time of the file the method is read from, as well
as the full directory path to that file. The \f(CW\*(C`<hidden />\*(C'\fR tag is used
to identify those methods that should not be exposed to the outside world
through any sort of introspection/documentation \s-1API.\s0 They are still available
and callable, but the client must possess the interface information in order
to do so.
.IP "The information crucial to the method" 4
.IX Item "The information crucial to the method"
The name, signatures and code must be present for obvious reasons. The
\&\f(CW\*(C`<name>\*(C'\fR tag tells the server what external name this procedure is
known by. The \f(CW\*(C`<signature>\*(C'\fR tag, which may appear more than once,
provides the definition of the interface to the function in terms of what
types and quantity of arguments it will accept, and for a given set of
arguments what the type of the returned value is. Lastly is the
\&\f(CW\*(C`<code>\*(C'\fR tag, without which there is no procedure to remotely call.
.IP "Why the <code> tag allows multiple languages" 4
.IX Item "Why the <code> tag allows multiple languages"
Note that the \f(CW\*(C`<code>\*(C'\fR tag is the only one with an attribute, in this
case \*(L"language\*(R". This is designed to allow for one \s-1XPL\s0 file to provide a given
method in multiple languages. Why, one might ask, would there be a need for
this?
.Sp
It is the hope behind this package that collections of \s-1RPC\s0 suites may one day
be made available as separate entities from this specific software package.
Given this hope, it is not unreasonable to suggest that such a suite of code
might be implemented in more than one language (each of Perl, Python, Ruby and
Tcl, for example). Languages which all support the means by which to take new
code and add it to a running process on demand (usually through an "\f(CW\*(C`eval\*(C'\fR"
keyword or something similar). If the file \fIA.xpl\fR is provided with
implementations in all four of the above languages, the name, help text,
signature and even hidden status would likely be identical. So, why not share
the non-language-specific elements in the spirit of re-use?
.ie n .SS "The ""make_method"" Utility"
.el .SS "The \f(CWmake_method\fP Utility"
.IX Subsection "The make_method Utility"
The utility script \f(CW\*(C`make_method\*(C'\fR is provided as a part of this software
suite. It allows for the automatic creation of \s-1XPL\s0 files from either
command-line information or from template files. It has a wide variety of
features and options, and is out of the scope of this particular manual
page. The package \fIMakefile.PL\fR features an example of engineering the
automatic generation of \s-1XPL\s0 files and their delivery as a part of the normal
Perl module build process. Using this tool is highly recommended over managing
\&\s-1XPL\s0 files directly. For the full details, see make_method.
.SH "NAMESPACES"
.IX Header "NAMESPACES"
As default behavior, Perl code that is passed to \f(CW\*(C`eval\*(C'\fR when a \s-1XPL\s0 file is
loaded gets put into the same namespace as the package used to load the \s-1XPL.\s0
It is not an issue when you create your own \fBRPC::XML::Procedure\fR (or
\&\fB::Method\fR or \fB::Function\fR) objects, as the code is already instantiated
into a given namespace. This can be important if your code expects to call
routines in other loaded packages, utilize package-level globals, etc.
.PP
To give developers control over the namespace in \s-1XPL\s0 code, a new optional
tag \f(CW\*(C`<namespace>\*(C'\fR was added in the 0.65 release. If this tag is present
in the \s-1XPL\s0 being read, it defines the namespace that the \f(CW\*(C`<code>\*(C'\fR block
is evaluated in.
.PP
The value of the namespace tag is a string providing the namespace in either
the Perl-style of hierarchy parts separated by \f(CW\*(C`::\*(C'\fR, or the style used by
Java, Perl6, etc., in which the parts are separated by \f(CW\*(C`.\*(C'\fR. The latter
form is converted to Perl style for the evaluation of the code. If there is
no namespace declaration in a \s-1XPL\s0 file, the namespace of the class that
loads the \s-1XPL\s0 is used.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
Unless otherwise noted in the individual documentation sections, all methods
return the object reference on success, or a (non-reference) text string
containing the error message upon failure.
.SH "CAVEATS"
.IX Header "CAVEATS"
Moving the method management to a separate class adds a good deal of overhead
to the general system. The trade-off in reduced complexity and added
maintainability should offset this.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs or feature requests to
\&\f(CW\*(C`bug\-rpc\-xml at rt.cpan.org\*(C'\fR, or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC\-XML>. I will be
notified, and then you'll automatically be notified of progress on
your bug as I make changes.
.SH "SUPPORT"
.IX Header "SUPPORT"
.IP "\(bu" 4
\&\s-1RT: CPAN\s0's request tracker
.Sp
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC\-XML>
.IP "\(bu" 4
AnnoCPAN: Annotated \s-1CPAN\s0 documentation
.Sp
<http://annocpan.org/dist/RPC\-XML>
.IP "\(bu" 4
\&\s-1CPAN\s0 Ratings
.Sp
<http://cpanratings.perl.org/d/RPC\-XML>
.IP "\(bu" 4
Search \s-1CPAN\s0
.Sp
<http://search.cpan.org/dist/RPC\-XML>
.IP "\(bu" 4
MetaCPAN
.Sp
<https://metacpan.org/release/RPC\-XML>
.IP "\(bu" 4
Source code on GitHub
.Sp
<http://github.com/rjray/rpc\-xml>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
This file and the code within are copyright (c) 2011 by Randy J. Ray.
.PP
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 \s-1GNU LGPL 2.1\s0 (<http://www.opensource.org/licenses/lgpl\-2.1.php>).
.SH "CREDITS"
.IX Header "CREDITS"
The \fBXML-RPC\fR standard is Copyright (c) 1998\-2001, UserLand Software, Inc.
See <http://www.xmlrpc.com> for more information about the \fBXML-RPC\fR
specification.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
RPC::XML::Server, make_method
.SH "AUTHOR"
.IX Header "AUTHOR"
Randy J. Ray \f(CW\*(C`<rjray@blackperl.com>\*(C'\fR