Description

xmlrpc/server.rb

Released under the same term of license as Ruby.

Classes

((<XMLRPC::BasicServer>))
((<XMLRPC::CGIServer>))
((<XMLRPC::ModRubyServer>))
((<XMLRPC::Server>))
((<XMLRPC::WEBrickServlet>))

XMLRPC::BasicServer

Description

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 ((-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.

Class Methods

— XMLRPC::BasicServer.new( class_delim=“.” )

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 method (({initialize})). The paramter ((|class_delim|)) is used
in ((<add_handler|XMLRPC::BasicServer#add_handler>)) when an object is
added as handler, to delimit the object-prefix and the method-name.

Instance Methods

— XMLRPC::BasicServer#add_handler( name, signature=nil, help=nil ) { aBlock }

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 informations about how to call this method etc.

A handler method or code-block can return the types listed at
((<XMLRPC::Client#call|URL:client.html#index:0>)).
When a method fails, it can tell it 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
The client gets in the case of (({b==0})) an object back of type
(({XMLRPC::FaultException})) that has a ((|faultCode|)) and ((|faultString|))
field.

— XMLRPC::BasicServer#add_handler( prefix, obj )

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|XMLRPC::BasicServer.new>))
has it's role, a XML-RPC method-name is defined by
((|prefix|)) + ((|class_delim|)) + (('"name of method"')).

— XMLRPC::BasicServer#add_handler( interface, obj )

This is the third form of ((<add_handler|XMLRPC::BasicServer#add_handler>)).

Use (({XMLRPC::interface})) to generate an ServiceInterface object, which
represents an interface (with signature and help text) for a handler class.

Parameter ((|interface|)) must be of type (({XMLRPC::ServiceInterface})).
Adds all methods of ((|obj|)) which are defined in ((|interface|)) to the
server.

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

— XMLRPC::BasicServer#get_default_handler

Returns the default-handler, which is called when no handler for
a method-name is found.
It is a (({Proc})) object or (({nil})).

— XMLRPC::BasicServer#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 (({XMLRPC::BasicServer})) is used, which raises a
XMLRPC::FaultException saying "method missing".

— XMLRPC::BasicServer#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::BasicServer#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::BasicServer#add_introspection

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

— XMLRPC::BasicServer#add_multicall

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

— XMLRPC::BasicServer#get_service_hook

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

— XMLRPC::BasicServer#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 parameter
((|handler|)) .

The service-hook is called with a (({Proc})) object and with the parameters for this (({Proc})).
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
   }