123456789_123456789_123456789_123456789_123456789_

Class: XMLRPC::BasicServer

Relationships & Source Files
Extension / Inclusion / Inheritance Descendants
Subclasses:
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
Inherits: Object
Defined in: lib/xmlrpc/server.rb

Overview

This is the base class for all XML-RPC server-types (CGI, standalone). You can add handler and set a default handler. Do not use this server, as this is/should be an abstract class.

How the method to call is found

The arity (number of accepted arguments) of a handler (method or Proc object) is compared to the given arguments submitted by the client for a RPC, or Remote Procedure Call.

A handler is only called if it accepts the number of arguments, otherwise the search for another handler will go on. When at the end no handler was found, the default_handler, #set_default_handler will be called.

With this technique it is possible to do overloading by number of parameters, but only for Proc handler, because you cannot define two methods of the same name in the same class.

Constant Summary

Class Method Summary

Instance Method Summary

ParseContentType - Included

ParserWriterChooseMixin - Included

#set_parser

Sets the XMLParser to use for parsing XML documents.

#set_writer

Sets the XMLWriter to use for generating XML output.

#create, #parser

Constructor Details

.new(class_delim = ".") ⇒ BasicServer

Creates a new BasicServer instance, which should not be done, because BasicServer is an abstract class. This method should be called from a subclass indirectly by a super call in the initialize method.

The parameter class_delim is used by add_handler, see #add_handler, when an object is added as a handler, to delimit the object-prefix and the method-name.

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 57

def initialize(class_delim=".")
  @handler = []
  @default_handler = nil
  @service_hook = nil

  @class_delim = class_delim
  @create = nil
  @parser = nil

  add_multicall     if Config::ENABLE_MULTICALL
  add_introspection if Config::ENABLE_INTROSPECTION
end

Instance Method Details

#add_handler(prefix, obj_or_signature = nil, help = nil, &block)

Adds aBlock to the list of handlers, with name as the name of the method.

Parameters signature and help are used by the Introspection method if specified, where signature is either an Array containing strings each representing a type of it's signature (the first is the return value) or an Array of Arrays if the method has multiple signatures.

Value type-names are “int, boolean, double, string, dateTime.iso8601, base64, array, struct”.

Parameter help is a String with information about how to call this method etc.

When a method fails, it can tell the client by throwing an FaultException like in this example:

s.add_handler("michael.div") do |a,b|
  if b == 0
    raise XMLRPC::FaultException.new(1, "division by zero")
  else
    a / b
  end
end

In the case of b==0 the client gets an object back of type FaultException that has a faultCode and faultString field.

This is the second form of ((<add_handler|XMLRPC::BasicServer#add_handler>)). To add an object write:

server.add_handler("michael", MyHandlerClass.new)

All public methods of MyHandlerClass are accessible to the XML-RPC clients by michael."name of method". This is where the class_delim in .new plays it's role, a XML-RPC method-name is defined by prefix + class_delim + "name of method".

The third form of +add_handler is to use Service::Interface to generate an object, which represents an interface (with signature and help text) for a handler class.

The XMLRPC.interface parameter must be an instance of Service::Interface. Adds all methods of obj which are defined in the XMLRPC.interface to the server.

This is the recommended way of adding services to a server!

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 116

def add_handler(prefix, obj_or_signature=nil, help=nil, &block)
  if block_given?
    # proc-handler
    @handler << [prefix, block, obj_or_signature, help]
  else
    if prefix.kind_of? String
      # class-handler
      raise ArgumentError, "Expected non-nil value" if obj_or_signature.nil?
      @handler << [prefix + @class_delim, obj_or_signature]
    elsif prefix.kind_of? XMLRPC::Service::BasicInterface
      # class-handler with interface
      # add all methods
      @handler += prefix.get_methods(obj_or_signature, @class_delim)
    else
      raise ArgumentError, "Wrong type for parameter 'prefix'"
    end
  end
  self
end

#add_introspection

Adds the introspection handlers "system.listMethods", "system.methodSignature" and "system.methodHelp", where only the first one works.

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 237

def add_introspection
  add_handler("system.listMethods",%w(array), "List methods available on this XML-RPC server") do
    methods = []
    @handler.each do |name, obj|
      if obj.kind_of? Proc
        methods << name
      else
        obj.class.public_instance_methods(false).each do |meth|
          methods << "#{name}#{meth}"
        end
      end
    end
    methods
  end

  add_handler("system.methodSignature", %w(array string), "Returns method signature") do |meth|
    sigs = []
    @handler.each do |name, obj, sig|
      if obj.kind_of? Proc and sig != nil and name == meth
        if sig[0].kind_of? Array
          # sig contains multiple signatures, e.g. [["array"], ["array", "string"]]
          sig.each {|s| sigs << s}
        else
          # sig is a single signature, e.g. ["array"]
          sigs << sig
        end
      end
    end
    sigs.uniq! || sigs  # remove eventually duplicated signatures
  end

  add_handler("system.methodHelp", %w(string string), "Returns help on using this method") do |meth|
    help = nil
    @handler.each do |name, obj, sig, hlp|
      if obj.kind_of? Proc and name == meth
        help = hlp
        break
      end
    end
    help || ""
  end

  self
end

#add_multicall

Adds the multi-call handler "system.multicall".

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 192

def add_multicall
  add_handler("system.multicall", %w(array array), "Multicall Extension") do |arrStructs|
    unless arrStructs.is_a? Array
      raise XMLRPC::FaultException.new(ERR_MC_WRONG_PARAM, "system.multicall expects an array")
    end

    arrStructs.collect {|call|
      if call.is_a? Hash
        methodName = call["methodName"]
        params     = call["params"]

        if params.nil?
          multicall_fault(ERR_MC_MISSING_PARAMS, "Missing params")
        elsif methodName.nil?
          multicall_fault(ERR_MC_MISSING_METHNAME, "Missing methodName")
        else
          if methodName == "system.multicall"
            multicall_fault(ERR_MC_RECURSIVE_CALL, "Recursive system.multicall forbidden")
          else
            unless params.is_a? Array
              multicall_fault(ERR_MC_WRONG_PARAM_PARAMS, "Parameter params have to be an Array")
            else
              ok, val = call_method(methodName, *params)
              if ok
                # correct return value
                [val]
              else
                # exception
                multicall_fault(val.faultCode, val.faultString)
              end
            end
          end
        end

      else
        multicall_fault(ERR_MC_EXPECTED_STRUCT, "system.multicall expected struct")
      end
    }
  end # end add_handler
  self
end

#call_method(methodname, *args) (private)

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 335

def call_method(methodname, *args)
  begin
    [true, dispatch(methodname, *args)]
  rescue XMLRPC::FaultException => e
    [false, e]
  rescue Exception => e
    [false, XMLRPC::FaultException.new(ERR_UNCAUGHT_EXCEPTION, "Uncaught exception #{e.message} in method #{methodname}")]
  end
end

#check_arity(obj, n_args) (private)

Returns true, if the arity of obj matches n_args

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 323

def check_arity(obj, n_args)
  ary = obj.arity

  if ary >= 0
    n_args == ary
  else
    n_args >= (ary+1).abs
  end
end

#dispatch(methodname, *args) (private)

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 295

def dispatch(methodname, *args)
  for name, obj in @handler
    if obj.kind_of? Proc
      next unless methodname == name
    else
      next unless methodname =~ /^#{name}(.+)$/
      next unless obj.respond_to? $1
      obj = obj.method($1)
    end

    if check_arity(obj, args.size)
      if @service_hook.nil?
        return obj.call(*args)
      else
        return @service_hook.call(obj, *args)
      end
    end
  end

  if @default_handler.nil?
    raise XMLRPC::FaultException.new(ERR_METHOD_MISSING, "Method #{methodname} missing or wrong number of parameters!")
  else
    @default_handler.call(methodname, *args)
  end
end

#get_default_handler

Returns the default-handler, which is called when no handler for a method-name is found.

It is either a Proc object or nil.

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 171

def get_default_handler
  @default_handler
end

#get_service_hook

Returns the service-hook, which is called on each service request (RPC) unless it's nil.

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 138

def get_service_hook
  @service_hook
end

#handle(methodname, *args) (private)

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 345

def handle(methodname, *args)
  create().methodResponse(*call_method(methodname, *args))
end

#multicall_fault(nr, str) (private)

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 291

def multicall_fault(nr, str)
  {"faultCode" => nr, "faultString" => str}
end

#process(data)

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 284

def process(data)
  method, params = parser().parseMethodCall(data)
  handle(method, *params)
end

#set_default_handler(&handler)

Sets handler as the default-handler, which is called when no handler for a method-name is found.

handler is a code-block.

The default-handler is called with the (XML-RPC) method-name as first argument, and the other arguments are the parameters given by the client-call.

If no block is specified the default of BasicServer is used, which raises a FaultException saying “method missing”.

[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 186

def set_default_handler(&handler)
  @default_handler = handler
  self
end

#set_service_hook(&handler)

A service-hook is called for each service request (RPC).

You can use a service-hook for example to wrap existing methods and catch exceptions of them or convert values to values recognized by ::XMLRPC.

You can disable it by passing nil as the handler parameter.

The service-hook is called with a Proc object along with any parameters.

An example:

server.set_service_hook {|obj, *args|
  begin
    ret = obj.call(*args)  # call the original service-method
    # could convert the return value
  rescue
    # rescue exceptions
  end
}
[ GitHub ]

  
# File 'lib/xmlrpc/server.rb', line 162

def set_service_hook(&handler)
  @service_hook = handler
  self
end