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
-
ERR_MC_EXPECTED_STRUCT =
# File 'lib/xmlrpc/server.rb', line 468
-
ERR_MC_MISSING_METHNAME =
# File 'lib/xmlrpc/server.rb', line 435
-
ERR_MC_MISSING_PARAMS =
# File 'lib/xmlrpc/server.rb', line 424
-
ERR_MC_RECURSIVE_CALL =
# File 'lib/xmlrpc/server.rb', line 446
-
ERR_MC_WRONG_PARAM =
# File 'lib/xmlrpc/server.rb', line 413
-
ERR_MC_WRONG_PARAM_PARAMS =
# File 'lib/xmlrpc/server.rb', line 457
-
ERR_METHOD_MISSING =
# File 'lib/xmlrpc/server.rb', line 391
-
ERR_UNCAUGHT_EXCEPTION =
# File 'lib/xmlrpc/server.rb', line 402
Class Method Summary
-
.new(class_delim = ".") ⇒ BasicServer
constructor
Creates a new
BasicServer
instance, which should not be done, becauseBasicServer
is an abstract class.
Instance Method Summary
-
#add_handler(prefix, obj_or_signature = nil, help = nil, &block)
Adds
aBlock
to the list of handlers, withname
as the name of the method. -
#add_introspection
Adds the introspection handlers
"system.listMethods"
,"system.methodSignature"
and"system.methodHelp"
, where only the first one works. -
#add_multicall
Adds the multi-call handler
"system.multicall"
. -
#get_default_handler
Returns the default-handler, which is called when no handler for a method-name is found.
-
#get_service_hook
Returns the service-hook, which is called on each service request (RPC) unless it's
nil
. - #process(data)
-
#set_default_handler(&handler)
Sets
handler
as the default-handler, which is called when no handler for a method-name is found. -
#set_service_hook(&handler)
A service-hook is called for each service request (RPC).
- #call_method(methodname, *args) private
-
#check_arity(obj, n_args)
private
Returns
true
, if the arity ofobj
matchesn_args
- #dispatch(methodname, *args) private
- #handle(methodname, *args) private
- #multicall_fault(nr, str) private
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.
# 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!
# 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.
# 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"
.
# 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.} in method #{methodname}")] end end
#check_arity(obj, n_args) (private)
Returns true
, if the arity of obj
matches n_args
# 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
.
# 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
.
# 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”.
# 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
}
# File 'lib/xmlrpc/server.rb', line 162
def set_service_hook(&handler) @service_hook = handler self end