rubysl-xmlrpc 1.0.0 → 2.0.0

data/lib/xmlrpc/base64.rb

@@ -1,46 +1,23 @@
-=begin
-= xmlrpc/base64.rb
-Copyright (C) 2001, 2002, 2003 by Michael Neumann (mneumann@ntecs.de)
-
-Released under the same term of license as Ruby.
-
-= Classes
-* ((<XMLRPC::Base64>))
-
-= XMLRPC::Base64
-== Description
-This class is necessary for (('xmlrpc4r')) to determine that a string should 
-be transmitted base64-encoded and not as a raw-string. 
-You can use (({XMLRPC::Base64})) on the client and server-side as a 
-parameter and/or return-value.
-
-== Class Methods
---- XMLRPC::Base64.new( str, state = :dec )
-    Creates a new (({XMLRPC::Base64})) instance with string ((|str|)) as the
-    internal string. When ((|state|)) is (({:dec})) it assumes that the 
-    string ((|str|)) is not in base64 format (perhaps already decoded), 
-    otherwise if ((|state|)) is (({:enc})) it decodes ((|str|)) 
-    and stores it as the internal string.
-    
---- XMLRPC::Base64.decode( str )
-    Decodes string ((|str|)) with base64 and returns that value.
-
---- XMLRPC::Base64.encode( str )
-    Encodes string ((|str|)) with base64 and returns that value.
-
-== Instance Methods
---- XMLRPC::Base64#decoded
-    Returns the internal string decoded.
-
---- XMLRPC::Base64#encoded
-    Returns the internal string encoded with base64.
-
-=end
-
-module XMLRPC
-
+#
+# xmlrpc/base64.rb
+# Copyright (C) 2001, 2002, 2003 by Michael Neumann (mneumann@ntecs.de)
+#
+# Released under the same term of license as Ruby.
+
+module XMLRPC # :nodoc:
+
+# This class is necessary for 'xmlrpc4r' to determine that a string should
+# be transmitted base64-encoded and not as a raw-string.
+#
+# You can use XMLRPC::Base64 on the client and server-side as a
+# parameter and/or return-value.
 class Base64
-  
+
+  # Creates a new XMLRPC::Base64 instance with string +str+ as the
+  # internal string. When +state+ is +:dec+ it assumes that the
+  # string +str+ is not in base64 format (perhaps already decoded),
+  # otherwise if +state+ is +:enc+ it decodes +str+
+  # and stores it as the internal string.
   def initialize(str, state = :dec)
     case state
     when :enc
@@ -51,20 +28,24 @@ class Base64
       raise ArgumentError, "wrong argument; either :enc or :dec"
     end
   end
-  
+
+  # Returns the decoded internal string.
   def decoded
-    @str  
+    @str
   end
-  
+
+  # Returns the base64 encoded internal string.
   def encoded
     Base64.encode(@str)
   end
 
 
+  # Decodes string +str+ with base64 and returns that value.
   def Base64.decode(str)
     str.gsub(/\s+/, "").unpack("m")[0]
   end
 
+  # Encodes string +str+ with base64 and returns that value.
   def Base64.encode(str)
     [str].pack("m")
   end
@@ -77,5 +58,5 @@ end # module XMLRPC
 
 =begin
 = History
-    $Id: base64.rb 11708 2007-02-12 23:01:19Z shyouhei $
+    $Id$
 =end

data/lib/xmlrpc/client.rb

@@ -1,302 +1,90 @@
-=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>))
-* ((<XMLRPC::Client::Proxy>))
-
-
-= 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 ((<XMLRPC::Client.new>)) which
-creates a new (({XMLRPC::Client})) instance, you can execute a remote procedure 
-by sending the ((<call|XMLRPC::Client#call>)) or ((<call2|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.
-
-== 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 ((<XMLRPC::Client.new>)) 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 ((<call|XMLRPC::Client#call>)) 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 ((<call|XMLRPC::Client#call>)).
-
-    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 ((<XMLRPC::Client#multicall>)), but returns like ((<XMLRPC::Client#call2>)) 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 ((<XMLRPC::Client#call>)), 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 ((<XMLRPC::Client#proxy>)) only that a call on the returned
-    (({XMLRPC::Client::Proxy})) object behaves like ((<XMLRPC::Client#call2>)), 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 ((<XMLRPC::Client#http_header_extra=>)) 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 ((<XMLRPC::Client#proxy>)) or
-((<XMLRPC::Client#proxy2>)).
-
-== 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 ((<new|XMLRPC::Client::Proxy#new>)).
-    
-Note: Inherited methods from class (({Object})) cannot be used as XML-RPC names, because they get around
-(({method_missing})). 
-          
-
-
-= History
-    $Id: client.rb 18091 2008-07-16 17:07:44Z shyouhei $
-
-=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"
 require "xmlrpc/utils"     # ParserWriterChooseMixin
 require "net/http"
-
-module XMLRPC
-
+require "uri"
+
+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})"
 
     include ParserWriterChooseMixin
     include ParseContentType
 
 
-    # Constructors -------------------------------------------------------------------
-
-    def initialize(host=nil, path=nil, port=nil, proxy_host=nil, proxy_port=nil, 
+    # 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 <tt>"/RPC2"</tt>.
+    # +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)
 
       @http_header_extra = nil
-      @http_last_response = nil 
+      @http_last_response = nil
       @cookie = nil
 
       @host       = host || "localhost"
@@ -324,8 +112,7 @@ module XMLRPC
       @proxy_port = @proxy_port.to_i if @proxy_port != nil
 
       # HTTP object for synchronous calls
-      Net::HTTP.version_1_2
-      @http = Net::HTTP.new(@host, @port, @proxy_host, @proxy_port) 
+      @http = net_http(@host, @port, @proxy_host, @proxy_port)
       @http.use_ssl = @use_ssl if @use_ssl
       @http.read_timeout = @timeout
       @http.open_timeout = @timeout
@@ -337,28 +124,55 @@ 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)
-      if match = /^([^:]+):\/\/(([^@]+)@)?([^\/]+)(\/.*)?$/.match(uri)
-        proto = match[1]
-        user, passwd = (match[3] || "").split(":")
-        host, port = match[4].split(":") 
-        path = match[5]
-
-        if proto != "http" and proto != "https"
-          raise "Wrong protocol specified. Only http or https allowed!"
-        end
+      begin
+        url = URI(uri)
+      rescue URI::InvalidURIError => e
+        raise ArgumentError, e.message, e.backtrace
+      end
 
-      else
-        raise "Wrong URI as parameter!"
+      unless URI::HTTP === url
+        raise ArgumentError, "Wrong protocol specified. Only http or https allowed!"
       end
- 
+
+      proto  = url.scheme
+      user   = url.user
+      passwd = url.password
+      host   = url.host
+      port   = url.port
+      path   = url.path.empty? ? nil : url.request_uri
+
       proxy_host, proxy_port = (proxy || "").split(":")
+      proxy_port = proxy_port.to_i if proxy_port
 
       self.new(host, path, port, proxy_host, proxy_port, user, passwd, (proto == "https"), timeout)
     end
 
     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
@@ -374,62 +188,128 @@ 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 <code>___class___</code> 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) 
+      ok, param = call2(method, *args)
       if ok
         param
       else
         raise param
       end
-    end 
+    end
 
+    # The difference between this method and XMLRPC::Client#call is, that
+    # this method will <b>NOT</b> 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) 
+      ok, param = call2_async(method, *args)
       if ok
         param
       else
         raise param
       end
-    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)
@@ -437,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
@@ -448,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
@@ -461,31 +367,65 @@ 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
+    end
 
     def set_auth
       if @user.nil?
@@ -493,15 +433,15 @@ module XMLRPC
       else
         a =  "#@user"
         a << ":#@password" if @password != nil
-        @auth = ("Basic " + [a].pack("m")).chomp
+        @auth = "Basic " + [a].pack("m0")
       end
     end
 
     def do_rpc(request, async=false)
-      header = {  
+      header = {
        "User-Agent"     =>  USER_AGENT,
        "Content-Type"   => "text/xml; charset=utf-8",
-       "Content-Length" => request.size.to_s, 
+       "Content-Length" => request.bytesize.to_s,
        "Connection"     => (async ? "close" : "keep-alive")
       }
 
@@ -512,44 +452,45 @@ module XMLRPC
         # add authorization header
         header["Authorization"] = @auth
       end
- 
+
       resp = nil
       @http_last_response = nil
 
       if async
-        # use a new HTTP object for each call 
-        Net::HTTP.version_1_2
-        http = Net::HTTP.new(@host, @port, @proxy_host, @proxy_port) 
+        # use a new HTTP object for each call
+        http = net_http(@host, @port, @proxy_host, @proxy_port)
         http.use_ssl = @use_ssl if @use_ssl
         http.read_timeout = @timeout
         http.open_timeout = @timeout
-        
+
         # post request
         http.start {
-          resp = http.post2(@path, request, header) 
+          resp = http.request_post(@path, request, header)
         }
       else
         # reuse the HTTP object for each call => connection alive is possible
         # we must start connection explicitely first time so that http.request
         # does not assume that we don't want keepalive
         @http.start if not @http.started?
-        
+
         # post request
-        resp = @http.post2(@path, request, header) 
+        resp = @http.request_post(@path, request, header)
       end
-  
+
       @http_last_response = resp
 
       data = resp.body
 
       if resp.code == "401"
         # Authorization Required
-        raise "Authorization failed.\nHTTP-Error: #{resp.code} #{resp.message}" 
+        raise "Authorization failed.\nHTTP-Error: #{resp.code} #{resp.message}"
       elsif resp.code[0,1] != "2"
-        raise "HTTP-Error: #{resp.code} #{resp.message}" 
+        raise "HTTP-Error: #{resp.code} #{resp.message}"
       end
 
-      ct = parse_content_type(resp["Content-Type"]).first
+      # assume text/xml on instances where Content-Type header is not set
+      ct_expected = resp["Content-Type"] || 'text/xml'
+      ct = parse_content_type(ct_expected).first
       if ct != "text/xml"
         if ct == "text/html"
           raise "Wrong content-type (received '#{ct}' but expected 'text/xml'): \n#{data}"
@@ -559,10 +500,10 @@ module XMLRPC
       end
 
       expected = resp["Content-Length"] || "<unknown>"
-      if data.nil? or data.size == 0 
-        raise "Wrong size. Was #{data.size}, should be #{expected}" 
-      elsif expected != "<unknown>" and expected.to_i != data.size and resp["Transfer-Encoding"].nil?
-        raise "Wrong size. Was #{data.size}, should be #{expected}"
+      if data.nil? or data.bytesize == 0
+        raise "Wrong size. Was #{data.bytesize}, should be #{expected}"
+      elsif expected != "<unknown>" and expected.to_i != data.bytesize and resp["Transfer-Encoding"].nil?
+        raise "Wrong size. Was #{data.bytesize}, should be #{expected}"
       end
 
       set_cookies = resp.get_fields("Set-Cookie")
@@ -581,11 +522,11 @@ module XMLRPC
       meth = :call2
       meth = :call2_async if async
 
-      ok, params = self.send(meth, "system.multicall", 
+      ok, params = self.send(meth, "system.multicall",
         methods.collect {|m| {'methodName' => m[0], 'params' => m[1..-1]} }
       )
 
-      if ok 
+      if ok
         params = params.collect do |param|
           if param.is_a? Array
             param[0]
@@ -593,7 +534,7 @@ module XMLRPC
             XMLRPC::FaultException.new(param["faultCode"], param["faultString"])
           else
             raise "Wrong multicall return value"
-          end 
+          end
         end
       end
 
@@ -602,19 +543,55 @@ 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 : ""
-	@args   = args 
+        @server = server
+        @prefix = prefix ? prefix + delim : ""
+        @args   = args
         @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
-	@server.send(@meth, pre, *arg)
+        pre = @prefix + mid.to_s
+        arg = @args + args
+        @server.send(@meth, pre, *arg)
       end
 
     end # class Proxy