summaryrefslogtreecommitdiff
path: root/lib/webrick/httpservlet
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-05-10 00:13:58 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-05-10 00:13:58 +0000
commit071a678a156dde974d8e470b659c89cb02b07b3b (patch)
treea0c846f48a5107c97261a117e7624edabe6feddd /lib/webrick/httpservlet
parent7e3ec1db0da950bf77bc3aa8d9b24b161cb60654 (diff)
* 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.rb87
-rw-r--r--lib/webrick/httpservlet/filehandler.rb31
2 files changed, 116 insertions, 2 deletions
diff --git a/lib/webrick/httpservlet/abstract.rb b/lib/webrick/httpservlet/abstract.rb
index f8bf14a3300..0d5c5ae48dd 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 daad8abd27f..263c9fc80f9 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]