path: root/trunk/lib/xmlrpc/README.rdoc

= XMLRPC for Ruby

== 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 (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>.