From 1df7862b2bf2ba3ebd9d33c6be4882e727fb64f4 Mon Sep 17 00:00:00 2001 From: zzak Date: Thu, 13 Sep 2012 02:22:10 +0000 Subject: * 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 --- lib/xmlrpc/client.rb | 552 ++++++++++++++++++++++++--------------------------- 1 file changed, 260 insertions(+), 292 deletions(-) (limited to 'lib/xmlrpc/client.rb') diff --git a/lib/xmlrpc/client.rb b/lib/xmlrpc/client.rb index 54f721fd37..c1c2da054c 100644 --- a/lib/xmlrpc/client.rb +++ b/lib/xmlrpc/client.rb @@ -1,279 +1,11 @@ -=begin -= xmlrpc/client.rb -Copyright (C) 2001, 2002, 2003 by Michael Neumann (mneumann@ntecs.de) - -Released under the same term of license as Ruby. - -= Classes -* (()) -* (()) - - -= 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 (()) which -creates a new (({XMLRPC::Client})) instance, you can execute a remote procedure -by sending the (()) or (()) -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 (()) 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 (()) 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 (()). - - 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 (()), but returns like (()) 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 (()), 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 (()) only that a call on the returned - (({XMLRPC::Client::Proxy})) object behaves like (()), 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 (()) 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 nicer! -You can call any method onto objects of that class - the object handles -(({method_missing})) and will forward the method call to a XML-RPC server. -Don't use this class directly, but use instead method (()) or -(()). - -== Class Methods ---- XMLRPC::Client::Proxy.new( server, prefix, args=[], meth=:call, delim="." ) - Creates an object which provides (({method_missing})). - - ((|server|)) must be of type (({XMLRPC::Client})), which is the XML-RPC server to be used - for a XML-RPC call. ((|prefix|)) and ((|delim|)) will be prepended to the methodname - called onto this object. - - Parameter ((|meth|)) is the method (call, call2, call_async, call2_async) to use for - a RPC. - - ((|args|)) are arguments which are automatically given - to every XML-RPC call before the arguments provides through (({method_missing})). - -== Instance Methods -Every method call is forwarded to the XML-RPC server defined in (()). - -Note: Inherited methods from class (({Object})) cannot be used as XML-RPC names, because they get around -(({method_missing})). - - - -= History - $Id$ - -=end - - - +# xmlrpc/client.rb +# Copyright (C) 2001, 2002, 2003 by Michael Neumann (mneumann@ntecs.de) +# +# Released under the same term of license as Ruby. +# +# History +# $Id$ +# require "xmlrpc/parser" require "xmlrpc/create" require "xmlrpc/config" @@ -281,8 +13,43 @@ require "xmlrpc/utils" # ParserWriterChooseMixin require "net/http" require "uri" -module XMLRPC - +module XMLRPC # :nodoc: + + # 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 XMLRPC::Client#call or 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. + # + # 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 class Client USER_AGENT = "XMLRPC::Client (Ruby #{RUBY_VERSION})" @@ -291,8 +58,28 @@ module XMLRPC include ParseContentType - # Constructors ------------------------------------------------------------------- - + # Creates an object which represents the remote XML-RPC server on the + # given +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 sent, + # an Authorization header is sent. Currently only Basic Authentication is + # implemented, no Digest. + # + # If +use_ssl+ is set to +true+, communication 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. def initialize(host=nil, path=nil, port=nil, proxy_host=nil, proxy_port=nil, user=nil, password=nil, use_ssl=nil, timeout=nil) @@ -337,6 +124,16 @@ module XMLRPC class << self + # Creates an object which represents the remote XML-RPC server at the + # given +uri+. The URI should have a host, port, path, user and password. + # Example: https://user:password@host:port/path + # + # Raises an ArgumentError if the +uri+ is invalid, + # or if the protocol isn't http or https. + # + # If a +proxy+ is given it should be in the form of "host:port". + # + # The optional +timeout+ defaults to 30 seconds. def new2(uri, proxy=nil, timeout=nil) begin url = URI(uri) @@ -363,6 +160,19 @@ module XMLRPC alias new_from_uri new2 + # Receives a Hash and calls XMLRPC::Client.new + # with the corresponding values. + # + # The +hash+ parameter has following case-insensitive keys: + # * host + # * path + # * port + # * proxy_host + # * proxy_port + # * user + # * password + # * use_ssl + # * timeout def new3(hash={}) # convert all keys into lowercase strings @@ -378,38 +188,76 @@ module XMLRPC end - # Attribute Accessors ------------------------------------------------------------------- - - # add additional HTTP headers to the request + # Add additional HTTP headers to the request attr_accessor :http_header_extra - # makes last HTTP response accessible + # Returns the Net::HTTPResponse object of the last RPC. attr_reader :http_last_response - # Cookie support + # Get and set the HTTP Cookie header. attr_accessor :cookie + # Return the corresponding attributes. attr_reader :timeout, :user, :password + # Sets the Net::HTTP#read_timeout and Net::HTTP#open_timeout to + # +new_timeout+ def timeout=(new_timeout) @timeout = new_timeout @http.read_timeout = @timeout @http.open_timeout = @timeout end + # Changes the user for the Basic Authentication header to +new_user+ def user=(new_user) @user = new_user set_auth end + # Changes the password for the Basic Authentication header to + # +new_password+ def password=(new_password) @password = new_password set_auth end - # Call methods -------------------------------------------------------------- - + # Invokes the method named +method+ with the parameters given by + # +args+ on the XML-RPC server. + # + # The +method+ parameter 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 that object later. + # + # The method returns the return-value from the Remote Procedure Call. + # + # The type of the return-value is one of the types shown above. + # + # A Bignum is only allowed when it fits in 32-bit. A XML-RPC + # +dateTime.iso8601+ type is always returned as a XMLRPC::DateTime object. + # Struct is never returned, only a Hash, the same for a Symbol, where as a + # String is always returned. 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+ an Integer, and +faultString+ a String. def call(method, *args) ok, param = call2(method, *args) if ok @@ -419,12 +267,37 @@ module XMLRPC end end + # The difference between this method and XMLRPC::Client#call is, that + # this method will NOT raise a XMLRPC::FaultException exception. + # + # The method returns an array of two values. The first value indicates if + # the second value is +true+ or an XMLRPC::FaultException. + # + # Both are explained in XMLRPC::Client#call. + # + # Simple to remember: The "2" in "call2" denotes the number of values it returns. def call2(method, *args) request = create().methodCall(method, *args) data = do_rpc(request, false) parser().parseMethodResponse(data) end + # Similar to XMLRPC::Client#call, however can be called concurrently and + # use a new connection for each request. In contrast to the corresponding + # method without the +_async+ suffix, which use connect-alive (one + # connection for all requests). + # + # Note, that you have to use Thread 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) + # } + # def call_async(method, *args) ok, param = call2_async(method, *args) if ok @@ -434,6 +307,9 @@ module XMLRPC end end + # Same as XMLRPC::Client#call2, but can be called concurrently. + # + # See also XMLRPC::Client#call_async def call2_async(method, *args) request = create().methodCall(method, *args) data = do_rpc(request, true) @@ -441,8 +317,14 @@ module XMLRPC end - # Multicall methods -------------------------------------------------------------- - + # You can use this method to execute several methods on a XMLRPC server + # which support the multi-call extension. + # + # s.multicall( + # ['michael.add', 3, 4], + # ['michael.sub', 4, 5] + # ) + # # => [7, -1] def multicall(*methods) ok, params = multicall2(*methods) if ok @@ -452,10 +334,30 @@ module XMLRPC end end + # Same as XMLRPC::Client#multicall, but returns two parameters instead of + # raising an XMLRPC::FaultException. + # + # See XMLRPC::Client#call2 def multicall2(*methods) gen_multicall(methods, false) end + # Similar to XMLRPC::Client#multicall, however can be called concurrently and + # use a new connection for each request. In contrast to the corresponding + # method without the +_async+ suffix, which use connect-alive (one + # connection for all requests). + # + # Note, that you have to use Thread to call these methods concurrently. + # The following example calls two methods concurrently: + # + # Thread.new { + # p client.multicall_async("michael.add", 4, 5) + # } + # + # Thread.new { + # p client.multicall_async("michael.div", 7, 9) + # } + # def multicall_async(*methods) ok, params = multicall2_async(*methods) if ok @@ -465,31 +367,61 @@ module XMLRPC end end + # Same as XMLRPC::Client#multicall2, but can be called concurrently. + # + # See also XMLRPC::Client#multicall_async def multicall2_async(*methods) gen_multicall(methods, true) end - # Proxy generating methods ------------------------------------------ - + # 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. def proxy(prefix=nil, *args) Proxy.new(self, prefix, args, :call) end + # Almost the same like XMLRPC::Client#proxy only that a call on the returned + # XMLRPC::Client::Proxy object will return two parameters. + # + # See XMLRPC::Client#call2 def proxy2(prefix=nil, *args) Proxy.new(self, prefix, args, :call2) end + # Similar to XMLRPC::Client#proxy, however can be called concurrently and + # use a new connection for each request. In contrast to the corresponding + # method without the +_async+ suffix, which use connect-alive (one + # connection for all requests). + # + # Note, that you have to use Thread to call these methods concurrently. + # The following example calls two methods concurrently: + # + # Thread.new { + # p client.proxy_async("michael.add", 4, 5) + # } + # + # Thread.new { + # p client.proxy_async("michael.div", 7, 9) + # } + # def proxy_async(prefix=nil, *args) Proxy.new(self, prefix, args, :call_async) end + # Same as XMLRPC::Client#proxy2, but can be called concurrently. + # + # See also XMLRPC::Client#proxy_async def proxy2_async(prefix=nil, *args) Proxy.new(self, prefix, args, :call2_async) end - private # ---------------------------------------------------------- + private def net_http(host, port, proxy_host, proxy_port) Net::HTTP.new host, port, proxy_host, proxy_port @@ -611,8 +543,39 @@ module XMLRPC + # XML-RPC calls look nicer! + # + # You can call any method onto objects of that class - the object handles + # XMLRPC::Client::Proxy#method_missing and will forward the method call to + # a XML-RPC server. + # + # Don't use this class directly, instead use the public instance method + # XMLRPC::Client#proxy or XMLRPC::Client#proxy2. + # + # 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) class Proxy + # Creates an object which provides XMLRPC::Client::Proxy#method_missing. + # + # The given +server+ must be an instance of XMLRPC::Client, which is the + # XML-RPC server to be used for a XML-RPC call. + # + # +prefix+ and +delim+ will be prepended to the method name called onto this object. + # + # An optional parameter +meth+ is the method to use for a RPC. + # It can be either, call, call2, call_async, call2_async + # + # +args+ are arguments which are automatically given to every XML-RPC + # call before being provided through +method_missing+. def initialize(server, prefix, args=[], meth=:call, delim=".") @server = server @prefix = prefix ? prefix + delim : "" @@ -620,6 +583,11 @@ module XMLRPC @meth = meth end + # Every method call is forwarded to the XML-RPC server defined in + # XMLRPC::Client::Proxy#new. + # + # Note: Inherited methods from class Object cannot be used as XML-RPC + # names, because they get around +method_missing+. def method_missing(mid, *args) pre = @prefix + mid.to_s arg = @args + args -- cgit v1.2.3