U:RDoc::NormalModule[iI"XMLRPC:EF@0o:RDoc::Markup::Document:@parts[o;;[kS:RDoc::Markup::Heading:
leveli:	textI"Author and Copyright;To:RDoc::Markup::BlankLineo:RDoc::Markup::Paragraph;[I"JCopyright (C) 2001-2004 by Michael Neumann (mailto:mneumann@ntecs.de);T@o;
;[I"5Released under the same term of license as Ruby.;T@S;	;
i;I"
Overview;T@o;
;[I"OXMLRPC is a lightweight protocol that enables remote procedure calls over ;TI"3HTTP.  It is defined at http://www.xmlrpc.com.;T@o;
;[I"RXMLRPC allows you to create simple distributed computing solutions that span ;TI"Pcomputer languages.  Its distinctive feature is its simplicity compared to ;TI"*other approaches like SOAP and CORBA.;T@o;
;[I"TThe Ruby standard library package 'xmlrpc' enables you to create a server that ;TI"Rimplements remote procedures and a client that calls them.  Very little code ;TI",is required to achieve either of these.;T@S;	;
i;I"Example;T@o;
;[I"QTry the following code.  It calls a standard demonstration remote procedure.;T@o:RDoc::Markup::Verbatim;[I"require 'xmlrpc/client'
;TI"require 'pp'
;TI"
;TI"Tserver = XMLRPC::Client.new2("http://xmlrpc-c.sourceforge.net/api/sample.php")
;TI";result = server.call("sample.sumAndDifference", 5, 3)
;TI"pp result
;T:@format0S;	;
i;I"Documentation;T@o;
;[I"QSee http://www.ntecs.de/ruby/xmlrpc4r/.  There is plenty of detail there to ;TI"+use the client and implement a server.;T@S;	;
i;I" Features of XMLRPC for Ruby;T@o:RDoc::Markup::List:
@type:BULLET:@items[
o:RDoc::Markup::ListItem:@label0;[o;
;[I"Extensions;To;;;;[o;;0;[o;
;[I"Introspection;To;;0;[o;
;[I"multiCall;To;;0;[o;
;[I":optionally nil values and integers larger than 32 Bit;T@o;;0;[o;
;[I"Server;To;;;;[	o;;0;[o;
;[I"Standalone XML-RPC server;To;;0;[o;
;[I"#CGI-based (works with FastCGI);To;;0;[o;
;[I"Apache mod_ruby server;To;;0;[o;
;[I"WEBrick servlet;T@o;;0;[o;
;[I"Client;To;;;;[o;;0;[o;
;[I"#synchronous/asynchronous calls;To;;0;[o;
;[I""Basic HTTP-401 Authentication;To;;0;[o;
;[I"HTTPS protocol (SSL);T@o;;0;[o;
;[I"Parsers;To;;;;[
o;;0;[o;
;[I"ENQXML (XMLParser::NQXMLStreamParser, XMLParser::NQXMLTreeParser);To;;0;[o;
;[I"AExpat (XMLParser::XMLStreamParser, XMLParser::XMLTreeParser);To;;0;[o;
;[I")REXML (XMLParser::REXMLStreamParser);To;;0;[o;
;[I".xml-scan (XMLParser::XMLScanStreamParser);To;;0;[o;
;[I":Fastest parser is Expat's XMLParser::XMLStreamParser!;T@o;;0;[o;
;[I"General;To;;;;[o;;0;[o;
;[I"dpossible to choose between XMLParser module (Expat wrapper) and REXML/NQXML (pure Ruby) parsers;To;;0;[o;
;[I"MMarshalling Ruby objects to Hashs and reconstruct them later from a Hash;To;;0;[o;
;[I">SandStorm component architecture XMLRPC::Client interface;T@S;	;
i;I"
Howto;T@S;	;
i;I"Client;T@o;;[I"require "xmlrpc/client"
;TI"
;TI"7# Make an object to represent the XML-RPC server.
;TI"Qserver = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")
;TI"
;TI"1# Call the remote server and get our result
;TI";result = server.call("sample.sumAndDifference", 5, 3)
;TI"
;TI"sum = result["sum"]
;TI"'difference = result["difference"]
;TI"
;TI"3puts "Sum: #{sum}, Difference: #{difference}"
;T;0S;	;
i;I"9XMLRPC::Client with XML-RPC fault-structure handling;T@o;
;[I"@There are two possible ways, of handling a fault-structure:;T@S;	;
i	;I"3by catching a XMLRPC::FaultException exception;T@o;;[I"require "xmlrpc/client"
;TI"
;TI"7# Make an object to represent the XML-RPC server.
;TI"Qserver = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")
;TI"
;TI"begin
;TI"3  # Call the remote server and get our result
;TI"=  result = server.call("sample.sumAndDifference", 5, 3)
;TI"
;TI"  sum = result["sum"]
;TI")  difference = result["difference"]
;TI"
;TI"5  puts "Sum: #{sum}, Difference: #{difference}"
;TI"
;TI"(rescue XMLRPC::FaultException => e
;TI"  puts "Error: "
;TI"  puts e.faultCode
;TI"  puts e.faultString
;TI"	end
;T;0S;	;
i	;I"/by calling "call2" which returns a boolean;T@o;;[I"require "xmlrpc/client"
;TI"
;TI"7# Make an object to represent the XML-RPC server.
;TI"Qserver = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")
;TI"
;TI"1# Call the remote server and get our result
;TI"@ok, result = server.call2("sample.sumAndDifference", 5, 3)
;TI"
;TI"if ok
;TI"  sum = result["sum"]
;TI")  difference = result["difference"]
;TI"
;TI"5  puts "Sum: #{sum}, Difference: #{difference}"
;TI"
else
;TI"  puts "Error: "
;TI"  puts result.faultCode
;TI"  puts result.faultString
;TI"	end
;T;0S;	;
i;I" Using XMLRPC::Client::Proxy;T@o;
;[	I"PYou can create a Proxy object onto which you can call methods. This way it ;TI"Slooks nicer. Both forms, _call_ and _call2_ are supported through _proxy_ and ;TI"P_proxy2_.  You can additionally give arguments to the Proxy, which will be ;TI"1given to each XML-RPC call using that Proxy.;T@o;;[I"require "xmlrpc/client"
;TI"
;TI"7# Make an object to represent the XML-RPC server.
;TI"Qserver = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")
;TI"
;TI"# Create a Proxy object
;TI"%sample = server.proxy("sample")
;TI"
;TI"1# Call the remote server and get our result
;TI"+result = sample.sumAndDifference(5,3)
;TI"
;TI"sum = result["sum"]
;TI"'difference = result["difference"]
;TI"
;TI"3puts "Sum: #{sum}, Difference: #{difference}"
;T;0S;	;
i;I"-CGI-based server using XMLRPC::CGIServer;T@o;
;[I"=There are also two ways to define handler, the first is ;TI";like C/PHP, the second like Java, of course both ways ;TI"can be mixed:;T@S;	;
i	;I"#C/PHP-like (handler functions);T@o;;[I"require "xmlrpc/server"
;TI"
;TI"s = XMLRPC::CGIServer.new
;TI"
;TI"7s.add_handler("sample.sumAndDifference") do |a,b|
;TI"1  { "sum" => a + b, "difference" => a - b }
;TI"	end
;TI"
;TI"
s.serve
;T;0S;	;
i	;I" Java-like (handler classes);T@o;;[I"require "xmlrpc/server"
;TI"
;TI"s = XMLRPC::CGIServer.new
;TI"
;TI"class MyHandler
;TI""  def sumAndDifference(a, b)
;TI"3    { "sum" => a + b, "difference" => a - b }
;TI"  end
;TI"	end
;TI"
;TI"+# NOTE: Security Hole (read below)!!!
;TI",s.add_handler("sample", MyHandler.new)
;TI"
s.serve
;T;0o;
;[I"RTo return a fault-structure you have to raise an XMLRPC::FaultException e.g.:;T@o;;[I"=raise XMLRPC::FaultException.new(3, "division by Zero")
;T;0S;	;
i
;I"Security Note;T@o;
;[I"From Brian Candler:;T@o;;[I"VAbove code sample has an extremely nasty security hole, in that you can now call
;TI"Qany method of 'MyHandler' remotely, including methods inherited from Object
;TI">and Kernel! For example, in the client code, you can use
;TI"
;TI"0  puts server.call("sample.send","`","ls")
;TI"
;TI"P(backtick being the method name for running system processes). Needless to
;TI"4say, 'ls' can be replaced with something else.
;TI"
;TI"_The version which binds proc objects (or the version presented below in the next section)
;TI"adoesn't have this problem, but people may be tempted to use the second version because it's
;TI"Eso nice and 'Rubyesque'. I think it needs a big red disclaimer.
;T;0o;
;[I"From Michael:;T@o;
;[I"7A solution is to undef insecure methods or to use ;TI"DXMLRPC::Service::PublicInstanceMethodsInterface as shown below:;T@o;;[I"class MyHandler
;TI""  def sumAndDifference(a, b)
;TI"3    { "sum" => a + b, "difference" => a - b }
;TI"  end
;TI"	end
;TI"
;TI"%# ... server initialization ...
;TI"
;TI"@s.add_handler(XMLRPC::iPIMethods("sample"), MyHandler.new)
;TI"
;TI"# ...
;T;0o;
;[I"SThis adds only public instance methods explicitly declared in class MyHandler ;TI"4(and not those inherited from any other class).;T@S;	;
i	;I" With interface declarations;T@o;
;[I"6Code sample from the book Ruby Developer's Guide:;T@o;;[I"require "xmlrpc/server"
;TI"
;TI"class Num
;TI".  INTERFACE = XMLRPC::interface("num") {
;TI"<    meth 'int add(int, int)', 'Add two numbers', 'add'
;TI"8    meth 'int div(int, int)', 'Divide two numbers'
;TI"	  }
;TI"
;TI"  def add(a, b) a + b end
;TI"  def div(a, b) a / b end
;TI"	end
;TI"
;TI"s = XMLRPC::CGIServer.new
;TI",s.add_handler(Num::INTERFACE, Num.new)
;TI"
s.serve
;T;0S;	;
i;I"Standalone XMLRPC::Server;T@o;
;[I"8Same as CGI-based server, the only difference being;T@o;;[I"$server = XMLRPC::CGIServer.new
;T;0o;
;[I"must be changed to;T@o;;[I"'server = XMLRPC::Server.new(8080)
;T;0o;
;[I"2if you want a server listening on port 8080. ;TI"The rest is the same.;T@S;	;
i;I"0Choosing a different XMLParser or XMLWriter;T@o;
;[I"KThe examples above all use the default parser (which is now since 1.8 ;TI"DXMLParser::REXMLStreamParser) and a default XMLRPC::XMLWriter. ;TI"IIf you want to use a different XMLParser, then you have to call the ;TI"KParserWriterChooseMixin#set_parser method of XMLRPC::Client instances ;TI"Eor instances of subclasses of XMLRPC::BasicServer or by editing ;TI"xmlrpc/config.rb.;T@o;
;[I"XMLRPC::Client Example:;T@o;;[	I"# ...
;TI"Qserver = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")
;TI"9server.set_parser(XMLRPC::XMLParser::XMLParser.new)
;TI"# ...
;T;0o;
;[I"XMLRPC::Server Example:;T@o;;[	I"# ...
;TI"s = XMLRPC::CGIServer.new
;TI":s.set_parser(XMLRPC::XMLParser::XMLStreamParser.new)
;TI"# ...
;T;0o;
;[I"or:;T@o;;[	I"# ...
;TI"'server = XMLRPC::Server.new(8080)
;TI";server.set_parser(XMLRPC::XMLParser::NQXMLParser.new)
;TI"# ...
;T;0o;
;[	I"_Note that XMLParser::XMLStreamParser is incredible faster (and uses less memory) than any ;TI"Tother parser and scales well for large documents. For example for a 0.5 MB XML ;TI"Wdocument with many tags, XMLParser::XMLStreamParser is ~350 (!) times faster than ;TI"XXMLParser::NQXMLTreeParser and still ~18 times as fast as XMLParser::XMLTreeParser.;T@o;
;[I"XYou can change the XML-writer by calling method ParserWriterChooseMixin#set_writer.;T:
@fileI"lib/xmlrpc.rb;T:0@omit_headings_from_table_of_contents_below0;0;0[[[[[I"
class;T[[:public[[:protected[[:private[[I"
instance;T[[;[[;[[;[[[U:RDoc::Context::Section[i0o;;[;0;0[@½
I"lib/xmlrpc/base64.rb;TI"lib/xmlrpc/client.rb;TI"lib/xmlrpc/config.rb;TI"lib/xmlrpc/create.rb;TI"lib/xmlrpc/datetime.rb;TI"lib/xmlrpc/marshal.rb;TI"lib/xmlrpc/parser.rb;TI"lib/xmlrpc/server.rb;TI"lib/xmlrpc/utils.rb;T@ã
cRDoc::TopLevel