perl-xml-commits Mailing List for Perl XML (Page 16)

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

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





2002	Jan (8)	Feb (22)	Mar (3)	Apr (13)	May (1)	Jun (4)	Jul	Aug (5)	Sep (9)	Oct (36)	Nov (7)	Dec (15)
2003	Jan (4)	Feb (1)	Mar (55)	Apr (25)	May (25)	Jun (4)	Jul (2)	Aug	Sep (12)	Oct (6)	Nov (14)	Dec (1)
2004	Jan (1)	Feb (8)	Mar (6)	Apr (5)	May	Jun	Jul	Aug (1)	Sep (1)	Oct (3)	Nov (11)	Dec
2005	Jan (14)	Feb (3)	Mar (4)	Apr (14)	May (1)	Jun	Jul (1)	Aug	Sep (1)	Oct (2)	Nov (2)	Dec (1)
2006	Jan	Feb	Mar	Apr (3)	May	Jun	Jul	Aug (1)	Sep (8)	Oct (19)	Nov (5)	Dec
2007	Jan (5)	Feb (1)	Mar	Apr (4)	May	Jun	Jul	Aug (8)	Sep	Oct	Nov	Dec
2008	Jan	Feb	Mar (2)	Apr	May	Jun	Jul (1)	Aug	Sep	Oct	Nov	Dec

perl-xml-commits Mailing List for Perl XML (Page 16)

perl-xml-commits — the list to which CVS commits go