Menu
▾
▴
[perl-xml-cvs] CVS: Frontier-RPC/lib/Frontier Responder.pm,1.1,1.2
|
From: Joe J. <jj...@us...> - 2002-03-26 17:54:38
|
Update of /cvsroot/perl-xml/Frontier-RPC/lib/Frontier
In directory usw-pr-cvs1:/tmp/cvs-serv32158
Modified Files:
Responder.pm
Log Message:
Added better POD
Index: Responder.pm
===================================================================
RCS file: /cvsroot/perl-xml/Frontier-RPC/lib/Frontier/Responder.pm,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- Responder.pm 9 Nov 2000 04:00:49 -0000 1.1
+++ Responder.pm 26 Mar 2002 17:54:35 -0000 1.2
@@ -1,20 +1,32 @@
+# File: Repsonder.pm
+# based heavily on Ken MacLeod's Frontier::Daemon
+# Author: Joe Johnston 7/2000
+# Revisions:
+# 11/2000 - Cleaned/Add POD. Took out 'use CGI'.
+#
+# Meant to be called from a CGI process to answer client
+# requests and emit the appropriate reponses. See POD for details.
#
-# Copyright (C) 2000 Joe Johnston
-# Responder.pm is free software; you can redistribute it
-# and/or modify it under the same terms as Perl itself.
-#
-# $Id$
+# LICENSE: This code is released under the same licensing
+# as Perl itself.
#
-# Meant to be called from a CGI process to answer client
-# requests and emit the appropriate reponses.
-
-use strict;
+# Use the code where ever you want, but due credit is appreciated.
package Frontier::Responder;
+use strict;
+use vars qw/@ISA/;
+
use Frontier::RPC2;
-use CGI qw{:all};
+my $snappy_answer = "Hey, I need to return true, don't I?";
+
+# Class constructor.
+# Input: (expects parameters to be passed in as a hash)
+# methods => hashref, keys are API procedure names, values are
+# subroutine references
+#
+# Output: blessed reference
sub new {
my $class = shift;
my %args = @_;
@@ -30,6 +42,8 @@
# Grabs input from CGI "stream", makes request
# if possible, packs up the response in purddy
# XML
+# Input: None
+# Output: A XML string suitable for printing from a CGI process
sub answer{
my $self = shift;
@@ -52,6 +66,7 @@
}
+# private function. No need to advertise this.
# Remember, this is just XML.
# CGI.pm doesn't grok this.
sub get_cgi_request{
@@ -68,38 +83,88 @@
return $in;
}
-1;
-
-__END__
+=pod
=head1 NAME
-Frontier::Responder - CGI responder for XML-RPC
+Frontier::Responder - Create XML-RPC listeners for normal CGI processes
=head1 SYNOPSIS
- use Frontier::Responder;
-
+ use Frontier::Responder;
my $res = Frontier::Responder->new( methods => {
- add => sub{ $_[0] + $_[1] },
- cat => sub{ $_[0] . $_[1] }, } );
-
+ add => sub{ $_[0] + $_[1] },
+ cat => sub{ $_[0] . $_[1] },
+ },
+ );
print $res->answer;
=head1 DESCRIPTION
-Meant to be called from a CGI process to answer client requests and
-emit the appropriate reponses.
+Use I<Frontier::Responder> whenever you need to create an XML-RPC listener
+using a standard CGI interface. To be effective, a script using this class
+will often have to be put a directory from which a web server is authorized
+to execute CGI programs. An XML-RPC listener using this library will be
+implementing the API of a particular XML-RPC application. Each remote
+procedure listed in the API of the user defined application will correspond
+to a hash key that is defined in the C<new> method of a I<Frontier::Responder>
+object. This is exactly the way I<Frontier::Daemon> works as well.
+In order to process the request and get the response, the C<answer> method
+is needed. Its return value is XML ready for printing.
-[NEED MORE USAGE INFO -- Help please, I don't know CGI.pm well, this
-is contributed code and I'm not familiar with how it should be used.]
+For those new to XML-RPC, here is a brief description of this protocol.
+XML-RPC is a way to execute functions on a different
+machine. Both the client's request and listeners response are wrapped
+up in XML and sent over HTTP. Because the XML-RPC conversation is in
+XML, the implementation languages of the server (here called a I<listener>),
+and the client can be different. This can be a powerful and simple way
+to have very different platforms work together without acrimony. Implicit
+in the use of XML-RPC is a contract or API that an XML-RPC listener
+implements and an XML-RPC client calls. The API needs to list not only
+the various procedures that can be called, but also the XML-RPC datatypes
+expected for input and output. Remember that although Perl is permissive
+about datatyping, other languages are not. Unforuntately, the XML-RPC spec
+doesn't say how to document the API. It is recomended that the author
+of a Perl XML-RPC listener should at least use POD to explain the API.
+This allows for the programmatic generation of a clean web page.
-=head1 AUTHOR
+=head1 METHODS
-Joe Johnston E<lt>jj...@or...E<gt>
+=over 4
+
+=item new( I<OPTIONS> )
+
+This is the class constructor. As is traditional, it returns
+a blessed reference to a I<Frontier::Responder> object. It expects
+arguments to be given like a hash (Perl's named parameter mechanism).
+To be effective, populate the C<methods> parameter with a hashref
+that has API procedure names as keys and subroutine references as
+values. See the SYNOPSIS for a sample usage.
+
+
+=item answer()
+
+In order to parse the request and execute the procedure, this method
+must be called. It returns a XML string that contains the procedure's
+response. In a typical CGI program, this string will simply be printed
+to STDOUT.
+
+
+=back
=head1 SEE ALSO
-perl(1), Frontier::RPC2(3).
+perl(1), Frontier::RPC2(3)
+
+<http://www.scripting.com/frontier5/xml/code/rpc.html>
+
+=head1 AUTHOR
+
+Ken MacLeod <ke...@bi...> wrote the underlying
+RPC library.
+
+Joe Johnston <jj...@cs...> wrote an adaptation
+of the Frontier::Daemon class to create this CGI XML-RPC
+listener class.
=cut
|
