diff options
author | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2011-05-10 00:13:58 +0000 |
---|---|---|
committer | drbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e> | 2011-05-10 00:13:58 +0000 |
commit | 071a678a156dde974d8e470b659c89cb02b07b3b (patch) | |
tree | a0c846f48a5107c97261a117e7624edabe6feddd /lib/webrick/httpservlet | |
parent | 7e3ec1db0da950bf77bc3aa8d9b24b161cb60654 (diff) | |
download | ruby-071a678a156dde974d8e470b659c89cb02b07b3b.tar.gz |
* lib/webrick: Add Documentation
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@31499 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'lib/webrick/httpservlet')
-rw-r--r-- | lib/webrick/httpservlet/abstract.rb | 87 | ||||
-rw-r--r-- | lib/webrick/httpservlet/filehandler.rb | 31 |
2 files changed, 116 insertions, 2 deletions
diff --git a/lib/webrick/httpservlet/abstract.rb b/lib/webrick/httpservlet/abstract.rb index f8bf14a330..0d5c5ae48d 100644 --- a/lib/webrick/httpservlet/abstract.rb +++ b/lib/webrick/httpservlet/abstract.rb @@ -18,17 +18,88 @@ module WEBrick module HTTPServlet class HTTPServletError < StandardError; end + ## + # AbstractServlet allows HTTP server modules to be reused across multiple + # servers and allows encapsulation of functionality. + # + # By default a servlet will respond to GET, HEAD (through an alias to GET) + # and OPTIONS requests. + # + # By default a new servlet is initialized for every request. A servlet + # instance can be reused by overriding ::get_instance in the + # AbstractServlet subclass. + # + # == A Simple Servlet + # + # class Simple < WEBrick::HTTPServlet::AbstractServlet + # def do_GET request, response + # status, content_type, body = do_stuff_with request + # + # response.status = status + # response['Content-Type'] = content_type + # response.body = body + # end + # + # def do_stuff_with request + # return 200, 'text/plain', 'you got a page' + # end + # end + # + # This servlet can be mounted on a server at a given path: + # + # server.mount '/simple', Simple + # + # == Servlet Configuration + # + # Servlets can be configured via initialize. The first argument is the + # HTTP server the servlet is being initialized for. + # + # class Configureable < Simple + # def initialize server, color, size + # super server + # @color = color + # @size = size + # end + # + # def do_stuff_with request + # content = "<p " \ + # %q{style="color: #{@color}; font-size: #{@size}"} \ + # ">Hello, World!" + # + # return 200, "text/html", content + # end + # end + # + # This servlet must be provided two arguments at mount time: + # + # server.mount '/configurable', Configurable, 'red', '2em' + class AbstractServlet - def self.get_instance(config, *options) - self.new(config, *options) + + ## + # Factory for servlet instances that will handle a request from +server+ + # using +options+ from the mount point. By default a new servlet + # instance is created for every call. + + def self.get_instance(server, *options) + self.new(server, *options) end + ## + # Initializes a new servlet for +server+ using +options+ which are + # stored as-is in +@options+. +@logger+ is also provided. + def initialize(server, *options) @server = @config = server @logger = @server[:Logger] @options = options end + ## + # Dispatches to a +do_+ method based on +req+ if such a method is + # available. (+do_GET+ for a GET request). Raises a MethodNotAllowed + # exception if the method is not implemented. + def service(req, res) method_name = "do_" + req.request_method.gsub(/-/, "_") if respond_to?(method_name) @@ -39,14 +110,23 @@ module WEBrick end end + ## + # Raises a NotFound exception + def do_GET(req, res) raise HTTPStatus::NotFound, "not found." end + ## + # Dispatches to do_GET + def do_HEAD(req, res) do_GET(req, res) end + ## + # Returns the allowed HTTP request methods + def do_OPTIONS(req, res) m = self.methods.grep(/\Ado_([A-Z]+)\z/) {$1} m.sort! @@ -55,6 +135,9 @@ module WEBrick private + ## + # Redirects to a path ending in / + def redirect_to_directory_uri(req, res) if req.path[-1] != ?/ location = WEBrick::HTTPUtils.escape_path(req.path + "/") diff --git a/lib/webrick/httpservlet/filehandler.rb b/lib/webrick/httpservlet/filehandler.rb index daad8abd27..263c9fc80f 100644 --- a/lib/webrick/httpservlet/filehandler.rb +++ b/lib/webrick/httpservlet/filehandler.rb @@ -125,17 +125,48 @@ module WEBrick end end + ## + # Serves files from a directory + class FileHandler < AbstractServlet HandlerTable = Hash.new + ## + # Allow custom handling of requests for files with +suffix+ by class + # +handler+ + def self.add_handler(suffix, handler) HandlerTable[suffix] = handler end + ## + # Remove custom handling of requests for files with +suffix+ + def self.remove_handler(suffix) HandlerTable.delete(suffix) end + ## + # Creates a FileHandler servlet on +server+ that serves files starting + # at directory +root+ + # + # If +options+ is a Hash the following keys are allowed: + # + # :AcceptableLanguages:: Array of languages allowed for accept-language + # :DirectoryCallback:: Allows preprocessing of directory requests + # :FancyIndexing:: If true, show an index for directories + # :FileCallback:: Allows preprocessing of file requests + # :HandlerCallback:: Allows preprocessing of requests + # :HandlerTable:: Maps file suffixes to file handlers. + # DefaultFileHandler is used by default but any servlet + # can be used. + # :NondisclosureName:: Do not show files matching this array of globs + # :UserDir:: Directory inside ~user to serve content from for /~user + # requests. Only works if mounted on / + # + # If +options+ is true or false then +:FancyIndexing+ is enabled or + # disabled respectively. + def initialize(server, root, options={}, default=Config::FileHandler) @config = server.config @logger = @config[:Logger] |