ruby-changes:24906
From: zzak <ko1@a...>
Date: Thu, 13 Sep 2012 11:22:23 +0900 (JST)
Subject: [ruby-changes:24906] zzak:r36958 (trunk): * lib/xmlrpc.rb: Documentation for XMLRPC
zzak 2012-09-13 11:22:10 +0900 (Thu, 13 Sep 2012) New Revision: 36958 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=36958 Log: * lib/xmlrpc.rb: Documentation for XMLRPC * lib/xmlrpc/datetime.rb: ditto. * lib/xmlrpc/parser.rb: ditto. * lib/xmlrpc/client.rb: ditto. * lib/xmlrpc/utils.rb: ditto. * lib/xmlrpc/README.rdoc: ditto. * lib/xmlrpc/create.rb: ditto. * lib/xmlrpc/base64.rb: ditto. * lib/xmlrpc/config.rb: ditto. * lib/xmlrpc/httpserver.rb: ditto. * lib/xmlrpc/server.rb: ditto. * lib/xmlrpc/marshal.rb: ditto. * lib/xmlrpc/README.txt: ditto. [Bug #6909] [ruby-core:47286] Added files: trunk/lib/xmlrpc.rb Removed files: trunk/lib/xmlrpc/README.rdoc trunk/lib/xmlrpc/README.txt Modified files: trunk/ChangeLog trunk/lib/xmlrpc/base64.rb trunk/lib/xmlrpc/client.rb trunk/lib/xmlrpc/config.rb trunk/lib/xmlrpc/create.rb trunk/lib/xmlrpc/datetime.rb trunk/lib/xmlrpc/httpserver.rb trunk/lib/xmlrpc/marshal.rb trunk/lib/xmlrpc/parser.rb trunk/lib/xmlrpc/server.rb trunk/lib/xmlrpc/utils.rb Index: ChangeLog =================================================================== --- ChangeLog (revision 36957) +++ ChangeLog (revision 36958) @@ -1,3 +1,20 @@ +Thu Sep 13 11:20:00 2012 Zachary Scott <zzak@r...> + + * lib/xmlrpc.rb: Documentation for XMLRPC + * lib/xmlrpc/datetime.rb: ditto. + * lib/xmlrpc/parser.rb: ditto. + * lib/xmlrpc/client.rb: ditto. + * lib/xmlrpc/utils.rb: ditto. + * lib/xmlrpc/README.rdoc: ditto. + * lib/xmlrpc/create.rb: ditto. + * lib/xmlrpc/base64.rb: ditto. + * lib/xmlrpc/config.rb: ditto. + * lib/xmlrpc/httpserver.rb: ditto. + * lib/xmlrpc/server.rb: ditto. + * lib/xmlrpc/marshal.rb: ditto. + * lib/xmlrpc/README.txt: ditto. + [Bug #6909] [ruby-core:47286] + Thu Sep 13 10:22:11 2012 Takashi Toyoshima <toyoshim@g...> * configure.in: Don't use PIE on Haiku because loader support is not Index: lib/xmlrpc/README.rdoc =================================================================== --- lib/xmlrpc/README.rdoc (revision 36957) +++ lib/xmlrpc/README.rdoc (revision 36958) @@ -1,300 +0,0 @@ -= XMLRPC for Ruby - -== Author and Copyright - -Copyright (C) 2001-2004 by Michael Neumann (mailto:mneumann@n...) - -Released under the same term of license as Ruby. - -== Overview - -XMLRPC is a lightweight protocol that enables remote procedure calls over -HTTP. It is defined at http://www.xmlrpc.com. - -XMLRPC allows you to create simple distributed computing solutions that span -computer languages. Its distinctive feature is its simplicity compared to -other approaches like SOAP and CORBA. - -The Ruby standard library package 'xmlrpc' enables you to create a server that -implements remote procedures and a client that calls them. Very little code -is required to achieve either of these. - -== Example - -Try the following code. It calls a standard demonstration remote procedure. - - require 'xmlrpc/client' - require 'pp' - - server = XMLRPC::Client.new2("http://xmlrpc-c.sourceforge.net/api/sample.php") - result = server.call("sample.sumAndDifference", 5, 3) - pp result - -== Documentation - -See http://www.ntecs.de/projects/xmlrpc4r. There is plenty of detail there to -use the client and implement a server. - -== Features of XMLRPC for Ruby - -* Extensions - * Introspection - * multiCall - * optionally nil values and integers larger than 32 Bit - -* Server - * Standalone XML-RPC server - * CGI-based (works with FastCGI) - * Apache mod_ruby server - * WEBrick servlet - -* Client - * synchronous/asynchronous calls - * Basic HTTP-401 Authentification - * HTTPS protocol (SSL) - -* Parsers - * NQXML (NQXMLStreamParser, NQXMLTreeParser) - * Expat (XMLStreamParser, XMLTreeParser) - * REXML (REXMLStreamParser) - * xml-scan (XMLScanStreamParser) - * Fastest parser is Expat's XMLStreamParser! - -* General - * possible to choose between XMLParser module (Expat wrapper) and REXML/NQXML (pure Ruby) parsers - * Marshalling Ruby objects to Hashs and reconstruct them later from a Hash - * SandStorm component architecture Client interface - -== Howto - -=== Client - - require "xmlrpc/client" - - # Make an object to represent the XML-RPC server. - server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php") - - # Call the remote server and get our result - result = server.call("sample.sumAndDifference", 5, 3) - - sum = result["sum"] - difference = result["difference"] - - puts "Sum: #{sum}, Difference: #{difference}" - -=== Client with XML-RPC fault-structure handling - -There are two possible ways, of handling a fault-structure: - -==== by catching a XMLRPC::FaultException exception - - require "xmlrpc/client" - - # Make an object to represent the XML-RPC server. - server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php") - - begin - # Call the remote server and get our result - result = server.call("sample.sumAndDifference", 5, 3) - - sum = result["sum"] - difference = result["difference"] - - puts "Sum: #{sum}, Difference: #{difference}" - - rescue XMLRPC::FaultException => e - puts "Error: " - puts e.faultCode - puts e.faultString - end - -==== by calling "call2" which returns a boolean - - require "xmlrpc/client" - - # Make an object to represent the XML-RPC server. - server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php") - - # Call the remote server and get our result - ok, result = server.call2("sample.sumAndDifference", 5, 3) - - if ok - sum = result["sum"] - difference = result["difference"] - - puts "Sum: #{sum}, Difference: #{difference}" - else - puts "Error: " - puts result.faultCode - puts result.faultString - end - -=== Client using Proxy - -You can create a +Proxy+ object onto which you can call methods. This way it -looks nicer. Both forms, _call_ and _call2_ are supported through _proxy_ and -<i>proxy2</i>. You can additionally give arguments to the Proxy, which will be -given to each XML-RPC call using that Proxy. - - require "xmlrpc/client" - - # Make an object to represent the XML-RPC server. - server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php") - - # Create a Proxy object - sample = server.proxy("sample") - - # Call the remote server and get our result - result = sample.sumAndDifference(5,3) - - sum = result["sum"] - difference = result["difference"] - - puts "Sum: #{sum}, Difference: #{difference}" - -=== CGI-based Server - -There are also two ways to define handler, the first is -like C/PHP, the second like Java, of course both ways -can be mixed: - -==== C/PHP-like (handler functions) - - require "xmlrpc/server" - - s = XMLRPC::CGIServer.new - - s.add_handler("sample.sumAndDifference") do |a,b| - { "sum" => a + b, "difference" => a - b } - end - - s.serve - -==== Java-like (handler classes) - - require "xmlrpc/server" - - s = XMLRPC::CGIServer.new - - class MyHandler - def sumAndDifference(a, b) - { "sum" => a + b, "difference" => a - b } - end - end - - # NOTE: Security Hole (read below)!!! - s.add_handler("sample", MyHandler.new) - s.serve - - -To return a fault-structure you have to raise an FaultException e.g.: - - raise XMLRPC::FaultException.new(3, "division by Zero") - -===== Security Note - -From Brian Candler: - - Above code sample has an extremely nasty security hole, in that you can now call - any method of 'MyHandler' remotely, including methods inherited from Object - and Kernel! For example, in the client code, you can use - - puts server.call("sample.send","`","ls") - - (backtick being the method name for running system processes). Needless to - say, 'ls' can be replaced with something else. - - The version which binds proc objects (or the version presented below in the next section) - doesn't have this problem, but people may be tempted to use the second version because it's - so nice and 'Rubyesque'. I think it needs a big red disclaimer. - - -From Michael: - -A solution is to undef insecure methods or to use (({XMLRPC::iPIMethods})) as shown below: - - class MyHandler - def sumAndDifference(a, b) - { "sum" => a + b, "difference" => a - b } - end - end - - # ... server initialization ... - - s.add_handler(XMLRPC::iPIMethods("sample"), MyHandler.new) - - # ... - -This adds only public instance methods explicitly declared in class MyHandler -(and not those inherited from any other class). - -==== With interface declarations - -Code sample from the book Ruby Developer's Guide: - - require "xmlrpc/server" - - class Num - INTERFACE = XMLRPC::interface("num") { - meth 'int add(int, int)', 'Add two numbers', 'add' - meth 'int div(int, int)', 'Divide two numbers' - } - - def add(a, b) a + b end - def div(a, b) a / b end - end - - - s = XMLRPC::CGIServer.new - s.add_handler(Num::INTERFACE, Num.new) - s.serve - -=== Standalone server - -Same as CGI-based server, only that the line - - server = XMLRPC::CGIServer.new - -must be changed to - - server = XMLRPC::Server.new(8080) - -if you want a server listening on port 8080. -The rest is the same. - -=== Choosing a different XML Parser or XML Writer - -The examples above all use the default parser (which is now since 1.8 -REXMLStreamParser) and a default XML writer. If you want to use a different -XML parser, then you have to call the <i>set_parser</i> method of -<tt>XMLRPC::Client</tt> instances or instances of subclasses of -<tt>XMLRPC::BasicServer</tt> or by editing xmlrpc/config.rb. - -Client Example: - - # ... - server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php") - server.set_parser(XMLRPC::XMLParser::XMLParser.new) - # ... - -Server Example: - - # ... - s = XMLRPC::CGIServer.new - s.set_parser(XMLRPC::XMLParser::XMLStreamParser.new) - # ... - -or: - - # ... - server = XMLRPC::Server.new(8080) - server.set_parser(XMLRPC::XMLParser::NQXMLParser.new) - # ... - - -Note that XMLStreamParser is incredible faster (and uses less memory) than any -other parser and scales well for large documents. For example for a 0.5 MB XML -document with many tags, XMLStreamParser is ~350 (!) times faster than -NQXMLTreeParser and still ~18 times as fast as XMLTreeParser. - -You can change the XML-writer by calling method <i>set_writer</i>. Index: lib/xmlrpc/README.txt =================================================================== --- lib/xmlrpc/README.txt (revision 36957) +++ lib/xmlrpc/README.txt (revision 36958) @@ -1,31 +0,0 @@ -= XMLRPC for Ruby, Standard Library Documentation - -== Overview - -XMLRPC is a lightweight protocol that enables remote procedure calls over -HTTP. It is defined at http://www.xmlrpc.com. - -XMLRPC allows you to create simple distributed computing solutions that span -computer languages. Its distinctive feature is its simplicity compared to -other approaches like SOAP and CORBA. - -The Ruby standard library package 'xmlrpc' enables you to create a server that -implements remote procedures and a client that calls them. Very little code -is required to achieve either of these. - -== Example - -Try the following code. It calls a standard demonstration remote procedure. - - require 'xmlrpc/client' - require 'pp' - - server = XMLRPC::Client.new2("http://xmlrpc-c.sourceforge.net/api/sample.php") - result = server.call("sample.sumAndDifference", 5, 3) - pp result - -== Documentation - -See http://www.ntecs.de/projects/xmlrpc4r. There is plenty of detail there to -use the client and implement a server. - Index: lib/xmlrpc/client.rb =================================================================== --- lib/xmlrpc/client.rb (revision 36957) +++ lib/xmlrpc/client.rb (revision 36958) @@ -1,279 +1,11 @@ -=begin -= xmlrpc/client.rb -Copyright (C) 2001, 2002, 2003 by Michael Neumann (mneumann@n...) - -Released under the same term of license as Ruby. - -= Classes -* ((<XMLRPC::Client>)) -* ((<XMLRPC::Client::Proxy>)) - - -= XMLRPC::Client -== Synopsis - require "xmlrpc/client" - - server = XMLRPC::Client.new("www.ruby-lang.org", "/RPC2", 80) - begin - param = server.call("michael.add", 4, 5) - puts "4 + 5 = #{param}" - rescue XMLRPC::FaultException => e - puts "Error:" - puts e.faultCode - puts e.faultString - end - -or - - require "xmlrpc/client" - - server = XMLRPC::Client.new("www.ruby-lang.org", "/RPC2", 80) - ok, param = server.call2("michael.add", 4, 5) - if ok then - puts "4 + 5 = #{param}" - else - puts "Error:" - puts param.faultCode - puts param.faultString - end - -== Description -Class (({XMLRPC::Client})) provides remote procedure calls to a XML-RPC server. -After setting the connection-parameters with ((<XMLRPC::Client.new>)) which -creates a new (({XMLRPC::Client})) instance, you can execute a remote procedure -by sending the ((<call|XMLRPC::Client#call>)) or ((<call2|XMLRPC::Client#call2>)) -message to this new instance. The given parameters indicate which method to -call on the remote-side and of course the parameters for the remote procedure. - -== Class Methods ---- XMLRPC::Client.new( host=nil, path=nil, port=nil, proxy_host=nil, proxy_port=nil, user=nil, password=nil, use_ssl=false, timeout =nil) - Creates an object which represents the remote XML-RPC server on the - given host ((|host|)). If the server is CGI-based, ((|path|)) is the - path to the CGI-script, which will be called, otherwise (in the - case of a standalone server) ((|path|)) should be (({"/RPC2"})). - ((|port|)) is the port on which the XML-RPC server listens. - If ((|proxy_host|)) is given, then a proxy server listening at - ((|proxy_host|)) is used. ((|proxy_port|)) is the port of the - proxy server. - - Default values for ((|host|)), ((|path|)) and ((|port|)) are 'localhost', '/RPC2' and - '80' respectively using SSL '443'. - - If ((|user|)) and ((|password|)) are given, each time a request is send, - a Authorization header is send. Currently only Basic Authentification is - implemented no Digest. - - If ((|use_ssl|)) is set to (({true})), comunication over SSL is enabled. - Note, that you need the SSL package from RAA installed. - - Parameter ((|timeout|)) is the time to wait for a XML-RPC response, defaults to 30. - ---- XMLRPC::Client.new2( uri, proxy=nil, timeout=nil) ---- XMLRPC::Client.new_from_uri( uri, proxy=nil, timeout=nil) -: uri - URI specifying protocol (http or https), host, port, path, user and password. - Example: https://user:password@host:port/path - -: proxy - Is of the form "host:port". - -: timeout - Defaults to 30. - ---- XMLRPC::Client.new3( hash={} ) ---- XMLRPC::Client.new_from_hash( hash={} ) - Parameter ((|hash|)) has following case-insensitive keys: - * host - * path - * port - * proxy_host - * proxy_port - * user - * password - * use_ssl - * timeout - - Calls ((<XMLRPC::Client.new>)) with the corresponding values. - -== Instance Methods ---- XMLRPC::Client#call( method, *args ) - Invokes the method named ((|method|)) with the parameters given by - ((|args|)) on the XML-RPC server. - The parameter ((|method|)) is converted into a (({String})) and should - be a valid XML-RPC method-name. - Each parameter of ((|args|)) must be of one of the following types, - where (({Hash})), (({Struct})) and (({Array})) can contain any of these listed ((:types:)): - * (({Fixnum})), (({Bignum})) - * (({TrueClass})), (({FalseClass})) ((({true})), (({false}))) - * (({String})), (({Symbol})) - * (({Float})) - * (({Hash})), (({Struct})) - * (({Array})) - * (({Date})), (({Time})), (({XMLRPC::DateTime})) - * (({XMLRPC::Base64})) - * A Ruby object which class includes XMLRPC::Marshallable (only if Config::ENABLE_MARSHALLABLE is (({true}))). - That object is converted into a hash, with one additional key/value pair "___class___" which contains the class name - for restoring later that object. - - The method returns the return-value from the RPC - ((-stands for Remote Procedure Call-)). - The type of the return-value is one of the above shown, - only that a (({Bignum})) is only allowed when it fits in 32-bit and - that a XML-RPC (('dateTime.iso8601')) type is always returned as - a ((<(({XMLRPC::DateTime}))|URL:datetime.html>)) object and - a (({Struct})) is never returned, only a (({Hash})), the same for a (({Symbol})), where - always a (({String})) is returned. - A (({XMLRPC::Base64})) is returned as a (({String})) from xmlrpc4r version 1.6.1 on. - - If the remote procedure returned a fault-structure, then a - (({XMLRPC::FaultException})) exception is raised, which has two accessor-methods - (({faultCode})) and (({faultString})) of type (({Integer})) and (({String})). - ---- XMLRPC::Client#call2( method, *args ) - The difference between this method and ((<call|XMLRPC::Client#call>)) is, that - this method do ((*not*)) raise a (({XMLRPC::FaultException})) exception. - The method returns an array of two values. The first value indicates if - the second value is a return-value ((({true}))) or an object of type - (({XMLRPC::FaultException})). - Both are explained in ((<call|XMLRPC::Client#call>)). - - Simple to remember: The "2" in "call2" denotes the number of values it returns. - ---- XMLRPC::Client#multicall( *methods ) - You can use this method to execute several methods on a XMLRPC server which supports - the multi-call extension. - Example: - - s.multicall( - ['michael.add', 3, 4], - ['michael.sub', 4, 5] - ) - # => [7, -1] - ---- XMLRPC::Client#multicall2( *methods ) - Same as ((<XMLRPC::Client#multicall>)), but returns like ((<XMLRPC::Client#call2>)) two parameters - instead of raising an (({XMLRPC::FaultException})). - ---- XMLRPC::Client#proxy( prefix, *args ) - Returns an object of class (({XMLRPC::Client::Proxy})), initialized with - ((|prefix|)) and ((|args|)). A proxy object returned by this method behaves - like ((<XMLRPC::Client#call>)), i.e. a call on that object will raise a - (({XMLRPC::FaultException})) when a fault-structure is returned by that call. - ---- XMLRPC::Client#proxy2( prefix, *args ) - Almost the same like ((<XMLRPC::Client#proxy>)) only that a call on the returned - (({XMLRPC::Client::Proxy})) object behaves like ((<XMLRPC::Client#call2>)), i.e. - a call on that object will return two parameters. - - - - ---- XMLRPC::Client#call_async(...) ---- XMLRPC::Client#call2_async(...) ---- XMLRPC::Client#multicall_async(...) ---- XMLRPC::Client#multicall2_async(...) ---- XMLRPC::Client#proxy_async(...) ---- XMLRPC::Client#proxy2_async(...) - In contrast to corresponding methods without "_async", these can be - called concurrently and use for each request a new connection, where the - non-asynchronous counterparts use connection-alive (one connection for all requests) - if possible. - - Note, that you have to use Threads to call these methods concurrently. - The following example calls two methods concurrently: - - Thread.new { - p client.call_async("michael.add", 4, 5) - } - - Thread.new { - p client.call_async("michael.div", 7, 9) - } - - ---- XMLRPC::Client#timeout ---- XMLRPC::Client#user ---- XMLRPC::Client#password - Return the corresponding attributes. - ---- XMLRPC::Client#timeout= (new_timeout) ---- XMLRPC::Client#user= (new_user) ---- XMLRPC::Client#password= (new_password) - Set the corresponding attributes. - - ---- XMLRPC::Client#set_writer( writer ) - Sets the XML writer to use for generating XML output. - Should be an instance of a class from module (({XMLRPC::XMLWriter})). - If this method is not called, then (({XMLRPC::Config::DEFAULT_WRITER})) is used. - ---- XMLRPC::Client#set_parser( parser ) - Sets the XML parser to use for parsing XML documents. - Should be an instance of a class from module (({XMLRPC::XMLParser})). - If this method is not called, then (({XMLRPC::Config::DEFAULT_PARSER})) is used. - ---- XMLRPC::Client#cookie ---- XMLRPC::Client#cookie= (cookieString) - Get and set the HTTP Cookie header. - ---- XMLRPC::Client#http_header_extra= (additionalHeaders) - Set extra HTTP headers that are included in the request. - ---- XMLRPC::Client#http_header_extra - Access the via ((<XMLRPC::Client#http_header_extra=>)) assigned header. - ---- XMLRPC::Client#http_last_response - Returns the (({Net::HTTPResponse})) object of the last RPC. - -= XMLRPC::Client::Proxy -== Synopsis - require "xmlrpc/client" - - server = XMLRPC::Client.new("www.ruby-lang.org", "/RPC2", 80) - - michael = server.proxy("michael") - michael2 = server.proxy("michael", 4) - - # both calls should return the same value '9'. - p michael.add(4,5) - p michael2.add(5) - -== Description -Class (({XMLRPC::Client::Proxy})) makes XML-RPC calls look (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/