diff --git a/ChangeLog b/ChangeLog index e4441c2051..b09569b990 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Wed May 5 00:38:00 2004 Gavin Sinclair + + * lib/gserver.rb: documented + * lib/xmlrpc/README.txt: introduced for documentation purposes + Mon May 3 09:47:24 2004 Dave Thomas * lib/rdoc/parsers/parse_rb.rb (RDoc::RubyParser::parse_method_or_yield_parameters): diff --git a/lib/gserver.rb b/lib/gserver.rb index 14f765a90c..371fceb290 100644 --- a/lib/gserver.rb +++ b/lib/gserver.rb @@ -1,10 +1,84 @@ +# # Copyright (C) 2001 John W. Small All Rights Reserved -# mailto:jsmall@laser.net subject:ruby-generic-server -# Freeware +# +# Author:: John W. Small +# Documentation:: Gavin Sinclair +# Licence:: Freeware. +# +# See the class GServer for documentation. +# require "socket" require "thread" +# +# +GServer+ implements a generic server, featuring thread pool management, simple logging, and +# multi-server management. See xmlrpc/httpserver.rb in the Ruby standard library for +# an example of +GServer+ in action. +# +# Any kind of application-level server can be implemented using this class. It accepts +# multiple simultaneous connections from clients, up to an optional maximum number. Several +# _services_ (i.e. one service per TCP port) can be run simultaneously, and stopped at any time +# through the class method GServer.stop(port). All the threading issues are handled, +# saving you the effort. All events are optionally logged, but you can provide your own event +# handlers if you wish. +# +# === Example +# +# Using +GServer+ is simple. Below we implement a simple time server, run it, query it, and +# shut it down. Try this code in +irb+: +# +# require 'gserver' +# +# # +# # A server that returns the time in seconds since 1970. +# # +# class TimeServer < GServer +# def initialize(port=10001, *args) +# super(port, *args) +# end +# def serve(io) +# io.puts(Time.now.to_i) +# end +# end +# +# # Run the server with logging enabled (it's a separate thread). +# server = TimeServer.new +# server.audit = true # Turn logging on. +# server.start +# +# # *** Now point your browser to http://localhost:10001 to see it working *** +# +# # See if it's still running. +# GServer.in_service?(10001) # -> true +# server.stopped? # -> false +# +# # Shut the server down gracefully. +# server.shutdown +# +# # Alternatively, stop it immediately. +# GServer.stop(10001) +# # or, of course, "server.stop". +# +# All the business of accepting connections and exception handling is taken care of. All we +# have to do is implement the method that actually serves the client. +# +# === Advanced +# +# As the example above shows, the way to use +GServer+ is to subclass it to create a specific +# server, overriding the +serve+ method. You can override other methods as well if you wish, +# perhaps to collect statistics, or emit more detailed logging. +# +# connecting +# disconnecting +# starting +# stopping +# +# The above methods are only called if auditing is enabled. +# +# You can also override +log+ and +error+ if, for example, you wish to use a more sophisticated +# logging system. +# class GServer DEFAULT_HOST = "127.0.0.1" diff --git a/lib/xmlrpc/README.txt b/lib/xmlrpc/README.txt new file mode 100644 index 0000000000..ade842d8b1 --- /dev/null +++ b/lib/xmlrpc/README.txt @@ -0,0 +1,31 @@ += XMLRPC for Ruby, Standard Library Documentation + +== Overview + +XMLRPC is a lightweight protocol that enables remote procedure calls over +HTTP. It is defined at http://www.xmlrpc.com. + +XMLRPC allows you to create simple distributed computing solutions that span +computer languages. Its distinctive feature is its simplicity compared to +other approaches like SOAP and CORBA. + +The Ruby standard library package 'xmlrpc' enables you to create a server that +implements remote procedures and a client that calls them. Very little code +is required to achieve either of these. + +== Example + +Try the following code. It calls a standard demonstration remote procedure. + + require 'xmlrpc/client' + require 'pp' + + server = XMLRPC::Client.new2("http://xmlrpc-c.sourceforge.net/api/sample.php") + result = server.call("sample.sumAndDifference", 5, 3) + pp result + +== Documentation + +See http://www.ntecs.de/projects/xmlrpc4r. There is plenty of detail there to +use the client and implement a server. +