Permalink
Browse files

* 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]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@36958 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
  • Loading branch information...
1 parent d11ef85 commit 1df7862b2bf2ba3ebd9d33c6be4882e727fb64f4 @zzak zzak committed Sep 13, 2012
Showing with 1,015 additions and 1,147 deletions.
  1. +17 −0 ChangeLog
  2. +301 −0 lib/xmlrpc.rb
  3. +0 −300 lib/xmlrpc/README.rdoc
  4. +0 −31 lib/xmlrpc/README.txt
  5. +22 −41 lib/xmlrpc/base64.rb
  6. +260 −292 lib/xmlrpc/client.rb
  7. +14 −12 lib/xmlrpc/config.rb
  8. +9 −12 lib/xmlrpc/create.rb
  9. +53 −66 lib/xmlrpc/datetime.rb
  10. +20 −25 lib/xmlrpc/httpserver.rb
  11. +4 −14 lib/xmlrpc/marshal.rb
  12. +47 −21 lib/xmlrpc/parser.rb
  13. +243 −314 lib/xmlrpc/server.rb
  14. +25 −19 lib/xmlrpc/utils.rb
View
@@ -1,3 +1,20 @@
+Thu Sep 13 11:20:00 2012 Zachary Scott <zzak@ruby-lang.org>
+
+ * 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@gmail.com>
* configure.in: Don't use PIE on Haiku because loader support is not
View
@@ -0,0 +1,301 @@
+# == Author and Copyright
+#
+# Copyright (C) 2001-2004 by Michael Neumann (mailto:mneumann@ntecs.de)
+#
+# 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 (XMLParser::NQXMLStreamParser, XMLParser::NQXMLTreeParser)
+# * Expat (XMLParser::XMLStreamParser, XMLParser::XMLTreeParser)
+# * REXML (XMLParser::REXMLStreamParser)
+# * xml-scan (XMLParser::XMLScanStreamParser)
+# * Fastest parser is Expat's XMLParser::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 XMLRPC::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}"
+#
+# === XMLRPC::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
+#
+# === Using XMLRPC::Client::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
+# _proxy2_. 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 using XMLRPC::CGIServer
+#
+# 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 XMLRPC::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::Service::PublicInstanceMethodsInterface 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 XMLRPC::Server
+#
+# Same as CGI-based server, the only difference being
+#
+# 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 XMLParser or XMLWriter
+#
+# The examples above all use the default parser (which is now since 1.8
+# XMLParser::REXMLStreamParser) and a default XMLRPC::XMLWriter.
+# If you want to use a different XMLParser, then you have to call the
+# ParserWriterChooseMixin#set_parser method of XMLRPC::Client instances
+# or instances of subclasses of XMLRPC::BasicServer or by editing
+# xmlrpc/config.rb.
+#
+# XMLRPC::Client Example:
+#
+# # ...
+# server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")
+# server.set_parser(XMLRPC::XMLParser::XMLParser.new)
+# # ...
+#
+# XMLRPC::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 XMLParser::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, XMLParser::XMLStreamParser is ~350 (!) times faster than
+# XMLParser::NQXMLTreeParser and still ~18 times as fast as XMLParser::XMLTreeParser.
+#
+# You can change the XML-writer by calling method ParserWriterChooseMixin#set_writer.
+module XMLRPC; end
Oops, something went wrong.

0 comments on commit 1df7862

Please sign in to comment.