class XMLRPC::BasicServer
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.
Constants
- ERR_MC_EXPECTED_STRUCT
- ERR_MC_MISSING_METHNAME
- ERR_MC_MISSING_PARAMS
- ERR_MC_RECURSIVE_CALL
- ERR_MC_WRONG_PARAM
- ERR_MC_WRONG_PARAM_PARAMS
- ERR_METHOD_MISSING
- ERR_UNCAUGHT_EXCEPTION
Public Class Methods
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 #add_handler, when an
object is added as a handler, to delimit the object-prefix and the
method-name.
# File lib/xmlrpc/server.rb, line 56 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
Public Instance Methods
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, Time.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 ::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 lib/xmlrpc/server.rb, line 115 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 the introspection handlers
"system.listMethods"
,
"system.methodSignature"
and
"system.methodHelp"
, where only the first one works.
# File lib/xmlrpc/server.rb, line 236 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 multi-call handler "system.multicall"
.
# File lib/xmlrpc/server.rb, line 191 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
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 lib/xmlrpc/server.rb, line 170 def get_default_handler @default_handler end
Returns the service-hook, which is called on each service request (RPC)
unless it's nil
.
# File lib/xmlrpc/server.rb, line 137 def get_service_hook @service_hook end
# File lib/xmlrpc/server.rb, line 283 def process(data) method, params = parser().parseMethodCall(data) handle(method, *params) 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 lib/xmlrpc/server.rb, line 185 def set_default_handler(&handler) @default_handler = 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 }
# File lib/xmlrpc/server.rb, line 161 def set_service_hook(&handler) @service_hook = handler self end
Private Instance Methods
# File lib/xmlrpc/server.rb, line 334 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
Returns true
, if the arity of obj
matches
n_args
# File lib/xmlrpc/server.rb, line 322 def check_arity(obj, n_args) ary = obj.arity if ary >= 0 n_args == ary else n_args >= (ary+1).abs end end
# File lib/xmlrpc/server.rb, line 294 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 lib/xmlrpc/server.rb, line 344 def handle(methodname, *args) create().methodResponse(*call_method(methodname, *args)) end
# File lib/xmlrpc/server.rb, line 290 def multicall_fault(nr, str) {"faultCode" => nr, "faultString" => str} end