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, XMLRPC::BasicServer#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.
# File tmp/rubies/ruby-2.3.8/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
Creates a new XMLRPC::BasicServer instance, which should not be done, because XMLRPC::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 XMLRPC::BasicServer#add_handler, when an object is added as a handler, to delimit the object-prefix and the method-name.
# File tmp/rubies/ruby-2.3.8/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
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 XMLRPC::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 XMLRPC::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 XMLRPC::BasicServer.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 XMLRPC::Service::Interface to generate an object, which represents an interface (with signature and help text) for a handler class.
The interface parameter must be an instance of XMLRPC::Service::Interface. Adds all methods of obj which are defined in the interface to the server.
This is the recommended way of adding services to a server!
# File tmp/rubies/ruby-2.3.8/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
Adds the introspection handlers "system.listMethods", "system.methodSignature" and "system.methodHelp", where only the first one works.
# File tmp/rubies/ruby-2.3.8/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
Adds the multi-call handler "system.multicall".
# File tmp/rubies/ruby-2.3.8/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
# File tmp/rubies/ruby-2.3.8/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
Returns true, if the arity of obj matches n_args
# File tmp/rubies/ruby-2.3.8/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
# File tmp/rubies/ruby-2.3.8/lib/xmlrpc/server.rb, line 171
def get_default_handler
@default_handler
end
Returns the default-handler, which is called when no handler for a method-name is found.
It is either a Proc object or nil.
# File tmp/rubies/ruby-2.3.8/lib/xmlrpc/server.rb, line 138
def get_service_hook
@service_hook
end
Returns the service-hook, which is called on each service request (RPC) unless it’s nil.
# File tmp/rubies/ruby-2.3.8/lib/xmlrpc/server.rb, line 345
def handle(methodname, *args)
create().methodResponse(*call_method(methodname, *args))
end
# File tmp/rubies/ruby-2.3.8/lib/xmlrpc/server.rb, line 291
def multicall_fault(nr, str)
{"faultCode" => nr, "faultString" => str}
end
# File tmp/rubies/ruby-2.3.8/lib/xmlrpc/server.rb, line 284
def process(data)
method, params = parser().parseMethodCall(data)
handle(method, *params)
end
# File tmp/rubies/ruby-2.3.8/lib/xmlrpc/server.rb, line 186
def set_default_handler(&handler)
@default_handler = handler
self
end
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 XMLRPC::BasicServer is used, which raises a XMLRPC::FaultException saying “method missing”.
# File tmp/rubies/ruby-2.3.8/lib/xmlrpc/server.rb, line 162
def set_service_hook(&handler)
@service_hook = handler
self
end
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 }