# xmlrpc/server.rb

Copyright (C) 2001, 2002 by Michael Neumann (neumann@s-direktnet.de)

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 *1. 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 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 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. 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. 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 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.

  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
        resuce
          # rescue exceptions
        end
      }

# XMLRPC::CGIServer

## Synopsis

    require "xmlrpc/server"

    s = XMLRPC::CGIServer.new

    s.add_handler("michael.add") do |a,b|
      a + b
    end

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

    s.set_default_handler do |name, *args|
      raise XMLRPC::FaultException.new(-99, "Method #{name} missing" +
                                       " or wrong number of parameters!")
    end

    s.serve

## Description

Implements a CGI-based XML-RPC server.

## Superclass

XMLRPC::BasicServer

## Class Methods

`XMLRPC::CGIServer.new( *a )`

  Creates a new `XMLRPC::CGIServer` instance. All parameters given are by-passed to XMLRPC::BasicServer.new. You can only create one `XMLRPC::CGIServer` instance, because more than one makes no sense.

## Instance Methods

`XMLRPC::CGIServer#serve`

  Call this after you have added all you handlers to the server. This method processes a XML-RPC methodCall and sends the answer back to the client. Make sure that you don't write to standard-output in a handler, or in any other part of your program, this would case a CGI-based server to fail!

# XMLRPC::ModRubyServer

## Description

Implements a XML-RPC server, which works with Apache mod_ruby.

Use it in the same way as CGIServer!

## Superclass

XMLRPC::BasicServer

# XMLRPC::Server

## Synopsis

    require "xmlrpc/server"

    s = XMLRPC::Server.new(8080)

    s.add_handler("michael.add") do |a,b|
      a + b
    end

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

    s.set_default_handler do |name, *args|
      raise XMLRPC::FaultException.new(-99, "Method #{name} missing" +
                                       " or wrong number of parameters!")
    end

    s.serve

## Description

Implements a standalone XML-RPC server. The method `serve`) is left if a SIGHUP is sent to the program.

## Superclass

XMLRPC::BasicServer

## Class Methods

`XMLRPC::Server.new( port=8080, host="127.0.0.1", maxConnections=4, stdlog=$stdout, audit=true, debug=true, *a )`

  Creates a new `XMLRPC::Server` instance, which is a XML-RPC server listening on port port and accepts requests for the host host, which is by default only the localhost. The server is not started, to start it you have to call serve.

  The parameters maxConnections, stdlog, audit and debug are passed to the HTTP server and specify it's behaviour more precise.

  All additionally given parameters in *a are by-passed to XMLRPC::BasicServer.new.

## Instance Methods

`XMLRPC::Server#serve`

  Call this after you have added all you handlers to the server. This method starts the server to listen for XML-RPC requests and answer them.

`XMLRPC::Server#shutdown`

  Stops and shuts the server down.

# XMLRPC::WEBrickServlet

## Synopsis

    require "webrick"
    require "xmlrpc/server"

    s = XMLRPC::WEBrickServlet.new
    s.add_handler("michael.add") do |a,b|
      a + b
    end

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

    s.set_default_handler do |name, *args|
      raise XMLRPC::FaultException.new(-99, "Method #{name} missing" +
                                       " or wrong number of parameters!")
    end

    httpserver = WEBrick::HTTPServer.new(:Port => 8080)
    httpserver.mount("RPC2", s)
    trap("HUP") { httpserver.shutdown }   # use 1 instead of "HUP" on Windows
    httpserver.start

## Description

Implements a servlet for use with WEBrick, a pure Ruby (HTTP-) server framework.

## Superclass

XMLRPC::BasicServer

# History

    $Id: server.rb,v 1.47 2002/01/08 23:00:53 michael Exp $

*1 Remote Procedure Call