xmlrpc/server.rb

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

Released under the same term of license as Ruby.

Classes

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( prefix, obj=nil, &block )

This method has two forms, one for adding an object and one to add a code block as a handler of a XML-RPC call. 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". To add a code block as a handler, write:

server.add_handler("michael.add") {|a,b| a+b}

Here the prefix is the full name of the method.

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#get_default_handler

Returns the default-handler, which is called when no handler for a method-name is found. It is a Proc object.

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.

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

Superclass

XMLRPC::BasicServer

Class Methods

XMLRPC::Server.new( port=8080, host="127.0.0.1", *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. 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#stop

Stops the server.

History

$Id: server.rb,v 1.21 2001/02/04 12:49:29 michael Exp $    

*1Remote Procedure Call