# == Author and Copyright

[0] Fix | Delete

#

[1] Fix | Delete

# Copyright (C) 2001-2004 by Michael Neumann (mailto:mneumann@ntecs.de)

[2] Fix | Delete

#

[3] Fix | Delete

# Released under the same term of license as Ruby.

[4] Fix | Delete

#

[5] Fix | Delete

# == Overview

[6] Fix | Delete

#

[7] Fix | Delete

# XMLRPC is a lightweight protocol that enables remote procedure calls over

[8] Fix | Delete

# HTTP. It is defined at http://www.xmlrpc.com.

[9] Fix | Delete

#

[10] Fix | Delete

# XMLRPC allows you to create simple distributed computing solutions that span

[11] Fix | Delete

# computer languages. Its distinctive feature is its simplicity compared to

[12] Fix | Delete

# other approaches like SOAP and CORBA.

[13] Fix | Delete

#

[14] Fix | Delete

# The Ruby standard library package 'xmlrpc' enables you to create a server that

[15] Fix | Delete

# implements remote procedures and a client that calls them. Very little code

[16] Fix | Delete

# is required to achieve either of these.

[17] Fix | Delete

#

[18] Fix | Delete

# == Example

[19] Fix | Delete

#

[20] Fix | Delete

# Try the following code. It calls a standard demonstration remote procedure.

[21] Fix | Delete

#

[22] Fix | Delete

# require 'xmlrpc/client'

[23] Fix | Delete

# require 'pp'

[24] Fix | Delete

#

[25] Fix | Delete

# server = XMLRPC::Client.new2("http://xmlrpc-c.sourceforge.net/api/sample.php")

[26] Fix | Delete

# result = server.call("sample.sumAndDifference", 5, 3)

[27] Fix | Delete

# pp result

[28] Fix | Delete

#

[29] Fix | Delete

# == Documentation

[30] Fix | Delete

#

[31] Fix | Delete

# See http://www.ntecs.de/ruby/xmlrpc4r/. There is plenty of detail there to

[32] Fix | Delete

# use the client and implement a server.

[33] Fix | Delete

#

[34] Fix | Delete

# == Features of XMLRPC for Ruby

[35] Fix | Delete

#

[36] Fix | Delete

# * Extensions

[37] Fix | Delete

# * Introspection

[38] Fix | Delete

# * multiCall

[39] Fix | Delete

# * optionally nil values and integers larger than 32 Bit

[40] Fix | Delete

#

[41] Fix | Delete

# * Server

[42] Fix | Delete

# * Standalone XML-RPC server

[43] Fix | Delete

# * CGI-based (works with FastCGI)

[44] Fix | Delete

# * Apache mod_ruby server

[45] Fix | Delete

# * WEBrick servlet

[46] Fix | Delete

#

[47] Fix | Delete

# * Client

[48] Fix | Delete

# * synchronous/asynchronous calls

[49] Fix | Delete

# * Basic HTTP-401 Authentication

[50] Fix | Delete

# * HTTPS protocol (SSL)

[51] Fix | Delete

#

[52] Fix | Delete

# * Parsers

[53] Fix | Delete

# * NQXML (XMLParser::NQXMLStreamParser, XMLParser::NQXMLTreeParser)

[54] Fix | Delete

# * Expat (XMLParser::XMLStreamParser, XMLParser::XMLTreeParser)

[55] Fix | Delete

# * REXML (XMLParser::REXMLStreamParser)

[56] Fix | Delete

# * xml-scan (XMLParser::XMLScanStreamParser)

[57] Fix | Delete

# * Fastest parser is Expat's XMLParser::XMLStreamParser!

[58] Fix | Delete

#

[59] Fix | Delete

# * General

[60] Fix | Delete

# * possible to choose between XMLParser module (Expat wrapper) and REXML/NQXML (pure Ruby) parsers

[61] Fix | Delete

# * Marshalling Ruby objects to Hashs and reconstruct them later from a Hash

[62] Fix | Delete

# * SandStorm component architecture XMLRPC::Client interface

[63] Fix | Delete

#

[64] Fix | Delete

# == Howto

[65] Fix | Delete

#

[66] Fix | Delete

# === Client

[67] Fix | Delete

#

[68] Fix | Delete

# require "xmlrpc/client"

[69] Fix | Delete

#

[70] Fix | Delete

# # Make an object to represent the XML-RPC server.

[71] Fix | Delete

# server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")

[72] Fix | Delete

#

[73] Fix | Delete

# # Call the remote server and get our result

[74] Fix | Delete

# result = server.call("sample.sumAndDifference", 5, 3)

[75] Fix | Delete

#

[76] Fix | Delete

# sum = result["sum"]

[77] Fix | Delete

# difference = result["difference"]

[78] Fix | Delete

#

[79] Fix | Delete

# puts "Sum: #{sum}, Difference: #{difference}"

[80] Fix | Delete

#

[81] Fix | Delete

# === XMLRPC::Client with XML-RPC fault-structure handling

[82] Fix | Delete

#

[83] Fix | Delete

# There are two possible ways, of handling a fault-structure:

[84] Fix | Delete

#

[85] Fix | Delete

# ==== by catching a XMLRPC::FaultException exception

[86] Fix | Delete

#

[87] Fix | Delete

# require "xmlrpc/client"

[88] Fix | Delete

#

[89] Fix | Delete

# # Make an object to represent the XML-RPC server.

[90] Fix | Delete

# server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")

[91] Fix | Delete

#

[92] Fix | Delete

# begin

[93] Fix | Delete

# # Call the remote server and get our result

[94] Fix | Delete

# result = server.call("sample.sumAndDifference", 5, 3)

[95] Fix | Delete

#

[96] Fix | Delete

# sum = result["sum"]

[97] Fix | Delete

# difference = result["difference"]

[98] Fix | Delete

#

[99] Fix | Delete

# puts "Sum: #{sum}, Difference: #{difference}"

[100] Fix | Delete

#

[101] Fix | Delete

# rescue XMLRPC::FaultException => e

[102] Fix | Delete

# puts "Error: "

[103] Fix | Delete

# puts e.faultCode

[104] Fix | Delete

# puts e.faultString

[105] Fix | Delete

# end

[106] Fix | Delete

#

[107] Fix | Delete

# ==== by calling "call2" which returns a boolean

[108] Fix | Delete

#

[109] Fix | Delete

# require "xmlrpc/client"

[110] Fix | Delete

#

[111] Fix | Delete

# # Make an object to represent the XML-RPC server.

[112] Fix | Delete

# server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")

[113] Fix | Delete

#

[114] Fix | Delete

# # Call the remote server and get our result

[115] Fix | Delete

# ok, result = server.call2("sample.sumAndDifference", 5, 3)

[116] Fix | Delete

#

[117] Fix | Delete

# if ok

[118] Fix | Delete

# sum = result["sum"]

[119] Fix | Delete

# difference = result["difference"]

[120] Fix | Delete

#

[121] Fix | Delete

# puts "Sum: #{sum}, Difference: #{difference}"

[122] Fix | Delete

# else

[123] Fix | Delete

# puts "Error: "

[124] Fix | Delete

# puts result.faultCode

[125] Fix | Delete

# puts result.faultString

[126] Fix | Delete

# end

[127] Fix | Delete

#

[128] Fix | Delete

# === Using XMLRPC::Client::Proxy

[129] Fix | Delete

#

[130] Fix | Delete

# You can create a Proxy object onto which you can call methods. This way it

[131] Fix | Delete

# looks nicer. Both forms, _call_ and _call2_ are supported through _proxy_ and

[132] Fix | Delete

# _proxy2_. You can additionally give arguments to the Proxy, which will be

[133] Fix | Delete

# given to each XML-RPC call using that Proxy.

[134] Fix | Delete

#

[135] Fix | Delete

# require "xmlrpc/client"

[136] Fix | Delete

#

[137] Fix | Delete

# # Make an object to represent the XML-RPC server.

[138] Fix | Delete

# server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")

[139] Fix | Delete

#

[140] Fix | Delete

# # Create a Proxy object

[141] Fix | Delete

# sample = server.proxy("sample")

[142] Fix | Delete

#

[143] Fix | Delete

# # Call the remote server and get our result

[144] Fix | Delete

# result = sample.sumAndDifference(5,3)

[145] Fix | Delete

#

[146] Fix | Delete

# sum = result["sum"]

[147] Fix | Delete

# difference = result["difference"]

[148] Fix | Delete

#

[149] Fix | Delete

# puts "Sum: #{sum}, Difference: #{difference}"

[150] Fix | Delete

#

[151] Fix | Delete

# === CGI-based server using XMLRPC::CGIServer

[152] Fix | Delete

#

[153] Fix | Delete

# There are also two ways to define handler, the first is

[154] Fix | Delete

# like C/PHP, the second like Java, of course both ways

[155] Fix | Delete

# can be mixed:

[156] Fix | Delete

#

[157] Fix | Delete

# ==== C/PHP-like (handler functions)

[158] Fix | Delete

#

[159] Fix | Delete

# require "xmlrpc/server"

[160] Fix | Delete

#

[161] Fix | Delete

# s = XMLRPC::CGIServer.new

[162] Fix | Delete

#

[163] Fix | Delete

# s.add_handler("sample.sumAndDifference") do |a,b|

[164] Fix | Delete

# { "sum" => a + b, "difference" => a - b }

[165] Fix | Delete

# end

[166] Fix | Delete

#

[167] Fix | Delete

# s.serve

[168] Fix | Delete

#

[169] Fix | Delete

# ==== Java-like (handler classes)

[170] Fix | Delete

#

[171] Fix | Delete

# require "xmlrpc/server"

[172] Fix | Delete

#

[173] Fix | Delete

# s = XMLRPC::CGIServer.new

[174] Fix | Delete

#

[175] Fix | Delete

# class MyHandler

[176] Fix | Delete

# def sumAndDifference(a, b)

[177] Fix | Delete

# { "sum" => a + b, "difference" => a - b }

[178] Fix | Delete

# end

[179] Fix | Delete

# end

[180] Fix | Delete

#

[181] Fix | Delete

# # NOTE: Security Hole (read below)!!!

[182] Fix | Delete

# s.add_handler("sample", MyHandler.new)

[183] Fix | Delete

# s.serve

[184] Fix | Delete

#

[185] Fix | Delete

#

[186] Fix | Delete

# To return a fault-structure you have to raise an XMLRPC::FaultException e.g.:

[187] Fix | Delete

#

[188] Fix | Delete

# raise XMLRPC::FaultException.new(3, "division by Zero")

[189] Fix | Delete

#

[190] Fix | Delete

# ===== Security Note

[191] Fix | Delete

#

[192] Fix | Delete

# From Brian Candler:

[193] Fix | Delete

#

[194] Fix | Delete

# Above code sample has an extremely nasty security hole, in that you can now call

[195] Fix | Delete

# any method of 'MyHandler' remotely, including methods inherited from Object

[196] Fix | Delete

# and Kernel! For example, in the client code, you can use

[197] Fix | Delete

#

[198] Fix | Delete

# puts server.call("sample.send","`","ls")

[199] Fix | Delete

#

[200] Fix | Delete

# (backtick being the method name for running system processes). Needless to

[201] Fix | Delete

# say, 'ls' can be replaced with something else.

[202] Fix | Delete

#

[203] Fix | Delete

# The version which binds proc objects (or the version presented below in the next section)

[204] Fix | Delete

# doesn't have this problem, but people may be tempted to use the second version because it's

[205] Fix | Delete

# so nice and 'Rubyesque'. I think it needs a big red disclaimer.

[206] Fix | Delete

#

[207] Fix | Delete

#

[208] Fix | Delete

# From Michael:

[209] Fix | Delete

#

[210] Fix | Delete

# A solution is to undef insecure methods or to use

[211] Fix | Delete

# XMLRPC::Service::PublicInstanceMethodsInterface as shown below:

[212] Fix | Delete

#

[213] Fix | Delete

# class MyHandler

[214] Fix | Delete

# def sumAndDifference(a, b)

[215] Fix | Delete

# { "sum" => a + b, "difference" => a - b }

[216] Fix | Delete

# end

[217] Fix | Delete

# end

[218] Fix | Delete

#

[219] Fix | Delete

# # ... server initialization ...

[220] Fix | Delete

#

[221] Fix | Delete

# s.add_handler(XMLRPC::iPIMethods("sample"), MyHandler.new)

[222] Fix | Delete

#

[223] Fix | Delete

# # ...

[224] Fix | Delete

#

[225] Fix | Delete

# This adds only public instance methods explicitly declared in class MyHandler

[226] Fix | Delete

# (and not those inherited from any other class).

[227] Fix | Delete

#

[228] Fix | Delete

# ==== With interface declarations

[229] Fix | Delete

#

[230] Fix | Delete

# Code sample from the book Ruby Developer's Guide:

[231] Fix | Delete

#

[232] Fix | Delete

# require "xmlrpc/server"

[233] Fix | Delete

#

[234] Fix | Delete

# class Num

[235] Fix | Delete

# INTERFACE = XMLRPC::interface("num") {

[236] Fix | Delete

# meth 'int add(int, int)', 'Add two numbers', 'add'

[237] Fix | Delete

# meth 'int div(int, int)', 'Divide two numbers'

[238] Fix | Delete

# }

[239] Fix | Delete

#

[240] Fix | Delete

# def add(a, b) a + b end

[241] Fix | Delete

# def div(a, b) a / b end

[242] Fix | Delete

# end

[243] Fix | Delete

#

[244] Fix | Delete

#

[245] Fix | Delete

# s = XMLRPC::CGIServer.new

[246] Fix | Delete

# s.add_handler(Num::INTERFACE, Num.new)

[247] Fix | Delete

# s.serve

[248] Fix | Delete

#

[249] Fix | Delete

# === Standalone XMLRPC::Server

[250] Fix | Delete

#

[251] Fix | Delete

# Same as CGI-based server, the only difference being

[252] Fix | Delete

#

[253] Fix | Delete

# server = XMLRPC::CGIServer.new

[254] Fix | Delete

#

[255] Fix | Delete

# must be changed to

[256] Fix | Delete

#

[257] Fix | Delete

# server = XMLRPC::Server.new(8080)

[258] Fix | Delete

#

[259] Fix | Delete

# if you want a server listening on port 8080.

[260] Fix | Delete

# The rest is the same.

[261] Fix | Delete

#

[262] Fix | Delete

# === Choosing a different XMLParser or XMLWriter

[263] Fix | Delete

#

[264] Fix | Delete

# The examples above all use the default parser (which is now since 1.8

[265] Fix | Delete

# XMLParser::REXMLStreamParser) and a default XMLRPC::XMLWriter.

[266] Fix | Delete

# If you want to use a different XMLParser, then you have to call the

[267] Fix | Delete

# ParserWriterChooseMixin#set_parser method of XMLRPC::Client instances

[268] Fix | Delete

# or instances of subclasses of XMLRPC::BasicServer or by editing

[269] Fix | Delete

# xmlrpc/config.rb.

[270] Fix | Delete

#

[271] Fix | Delete

# XMLRPC::Client Example:

[272] Fix | Delete

#

[273] Fix | Delete

# # ...

[274] Fix | Delete

# server = XMLRPC::Client.new( "xmlrpc-c.sourceforge.net", "/api/sample.php")

[275] Fix | Delete

# server.set_parser(XMLRPC::XMLParser::XMLParser.new)

[276] Fix | Delete

# # ...

[277] Fix | Delete

#

[278] Fix | Delete

# XMLRPC::Server Example:

[279] Fix | Delete

#

[280] Fix | Delete

# # ...

[281] Fix | Delete

# s = XMLRPC::CGIServer.new

[282] Fix | Delete

# s.set_parser(XMLRPC::XMLParser::XMLStreamParser.new)

[283] Fix | Delete

# # ...

[284] Fix | Delete

#

[285] Fix | Delete

# or:

[286] Fix | Delete

#

[287] Fix | Delete

# # ...

[288] Fix | Delete

# server = XMLRPC::Server.new(8080)

[289] Fix | Delete

# server.set_parser(XMLRPC::XMLParser::NQXMLParser.new)

[290] Fix | Delete

# # ...

[291] Fix | Delete

#

[292] Fix | Delete

#

[293] Fix | Delete

# Note that XMLParser::XMLStreamParser is incredible faster (and uses less memory) than any

[294] Fix | Delete

# other parser and scales well for large documents. For example for a 0.5 MB XML

[295] Fix | Delete

# document with many tags, XMLParser::XMLStreamParser is ~350 (!) times faster than

[296] Fix | Delete

# XMLParser::NQXMLTreeParser and still ~18 times as fast as XMLParser::XMLTreeParser.

[297] Fix | Delete

#

[298] Fix | Delete

# You can change the XML-writer by calling method ParserWriterChooseMixin#set_writer.

[299] Fix | Delete

module XMLRPC; end

[300] Fix | Delete

[301] Fix | Delete