Changeset 2516

Show
Ignore:
Timestamp:
02/16/08 21:00:17 (11 months ago)
Author:
hhubner
Message:

Docstrings

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • branches/trunk-reorg/bknr/web/src/web/handlers.lisp

    r2510 r2516  
    6767    :template-base-directory nil 
    6868    :template-command-packages nil 
    69     :rss-feed-url nil)) 
     69    :rss-feed-url nil) 
     70  (:documentation "Class to hold all information on a web server that 
     71is served within BKNR.  Currently, this is a singleton object, and 
     72*WEBSITE* will point to the only instance.  Eventually, multiple 
     73WEBSITE instances for virtual hosts may be supported.")) 
    7074 
    7175(defmethod initialize-instance :after ((website website) &key &allow-other-keys) 
    …… 
    8791  (format nil "~A~A" (website-base-href website) (relative path))) 
    8892 
    89 (defgeneric publish-handler (website handler)) 
    90 (defgeneric handler-matches (handler)) 
    91 (defgeneric publish-site (website)) 
     93(defgeneric publish-handler (website handler) 
     94  (:documentation "Publish HANDLER on WEBSITE, thereby adding it to 
     95the chain of handlers that is searched to handle an incoming 
     96request.")) 
     97 
     98(defgeneric handler-matches-p (handler) 
     99  (:documentation "Determine whether HANDLER is willing to handle the 
     100current request.  Returns non-NIL if the HANDLER wants to handle the request 
     101NIL otherwise.")) 
     102 
     103(defgeneric publish-site (website) 
     104  (:documentation "Publish all handlers defined in WEBSITE. 
     105 
     106XXX When is this called?")) 
    92107 
    93108(defun handler-definition-name (handler-definition) 
    …… 
    192207    (format stream "~A" (page-handler-prefix handler)))) 
    193208 
    194 (defgeneric handle (page-handler)) 
    195 (defgeneric authorized-p (page-handler)) 
    196 (defgeneric page-handler-url (page-handler)) 
     209(defgeneric handle (page-handler) 
     210  (:documentation "Handle an incoming HTTP request, returning either a 
     211string or an (array (unsigned-byte 8) (*)) with the response 
     212contents.  Alternatively, the handler may call (SEND-HEADERS) to 
     213get access to the response stream and output the data to it.")) 
     214 
     215(defgeneric authorized-p (page-handler) 
     216  (:documentation "Return non-nil if the request is authorized to be 
     217executed on PAGE-HANDLER 
     218 
     219XXX wouldn't it be better if handler-matches-p checked 
     220authorization?")) 
     221 
     222(defgeneric page-handler-url (page-handler) 
     223  (:documentation "Return the full base URL for PAGE-HANDLER.")) 
    197224 
    198225(defmethod handler-path ((handler page-handler)) 
    …… 
    267294(defun bknr-dispatch (request) 
    268295  (declare (ignore request)) 
    269   (let ((handler (find-if #'handler-matches (website-handlers *website*)))) 
     296  (let ((handler (find-if #'handler-matches-p (website-handlers *website*)))) 
    270297    (cond 
    271298      (handler 
    …… 
    280307  (setf *handlers* (append *handlers* (list handler)))) 
    281308 
    282 (defmethod handler-matches ((handler page-handler)) 
     309(defmethod handler-matches-p ((handler page-handler)) 
    283310  (string-equal (page-handler-prefix handler) 
    284311                (script-name))) 
    …… 
    297324 
    298325(defclass form-handler (page-handler) 
    299   ()) 
     326  () 
     327  (:documentation "A FORM-HANDLER is a handler that processes form 
     328submissions.  The handler generic function for FORM-HANDLER subclasses 
     329is called HANDLE-FORM.")) 
    300330 
    301331(define-condition form-condition (condition) 
    …… 
    316346             :field ',field-name)))) 
    317347 
    318 (defgeneric handle-form (page-handler action)) 
     348(defgeneric handle-form (page-handler action) 
     349  (:documentation "Handle form submission for PAGE-HANDLER.  The 
     350form variable \"action\" will be parsed into a keyword and passwd to 
     351the invocation of this generic function as ACTION.  Methods are meant 
     352to specialize on individual keywords to handle different actions that 
     353the form supports.")) 
    319354 
    320355(defmethod handle ((page-handler form-handler)) 
    …… 
    324359 
    325360(defclass prefix-handler (page-handler) 
    326   ()) 
     361  () 
     362  (:documentation "A PREFIX-HANDLER is a handler that is invoked for 
     363URLs with a certain prefix, as determined by the :PREFIX 
     364initialization argument.  It is used as a mixin class and only 
     365provides for a HANDLER-MATCHES-P method.")) 
    327366 
    328367#+(or) 
    …… 
    332371    (warn "prefix handler ~A does not have prefix ending with / - may match unexpectedly" handler))) 
    333372 
    334 (defmethod handler-matches ((handler prefix-handler)) 
     373(defmethod handler-matches-p ((handler prefix-handler)) 
    335374  (and (>= (length (script-name)) 
    336375           (length (page-handler-prefix handler))) 
    …… 
    341380(defclass directory-handler (prefix-handler) 
    342381  ((destination :initarg :destination 
    343                 :reader page-handler-destination))) 
    344  
    345 (defmethod request-pathname ((handler directory-handler)) 
    346   (or (aux-request-value 'request-pathname) 
    347       (setf (aux-request-value 'request-pathname) 
    348             (subseq (script-name) (1+ (length (page-handler-prefix handler))))))) 
    349  
    350 (defmethod handler-matches ((handler directory-handler)) 
     382                :reader page-handler-destination)) 
     383  (:documentation 
     384   "Handler for a directory in the file system.  Publishes all files 
     385in the directory DESTINATION under their relative path name.")) 
     386 
     387(defgeneric request-relative-pathname (directory-handler) 
     388  (:documentation "Return the relative pathname for the current 
     389request as determined by DIRECTORY-HANDLER.") 
     390  (:method ((handler directory-handler)) 
     391    (or (aux-request-value 'request-relative-pathname) 
     392        (setf (aux-request-value 'request-relative-pathname) 
     393              (pathname (subseq (script-name) (1+ (length (page-handler-prefix handler))))))))) 
     394 
     395(defmethod handler-matches-p ((handler directory-handler)) 
    351396  (and (call-next-method) 
    352        (probe-file (merge-pathnames (request-pathname handler) 
     397       (probe-file (merge-pathnames (request-relative-pathname handler) 
    353398                                    (page-handler-destination handler))))) 
    354399 
    355400(defmethod handle ((handler directory-handler)) 
    356   (handle-static-file (merge-pathnames (request-pathname handler) 
     401  (handle-static-file (merge-pathnames (request-relative-pathname handler) 
    357402                                       (page-handler-destination handler)))) 
    358403 
    …… 
    362407   (content-type :initarg :content-type 
    363408                 :reader page-handler-content-type)) 
    364   (:default-initargs :content-type "text/plain")) 
     409  (:default-initargs :content-type "text/plain") 
     410  (:documentation "A FILE-HANDLER is used to publish a single file 
     411under an URL.  :DESTINATION is the pathname of the file to publish, 
     412:CONTENT-TYPE is the content type to use.")) 
    365413 
    366414(defmethod handle ((handler file-handler)) 
    367   (handle-static-file (page-handler-destination handler))) 
     415  (handle-static-file (page-handler-destination handler) (page-handler-content-type handler))) 
    368416 
    369417(defclass object-handler (prefix-handler) 
    370418  ((query-function :initarg :query-function :reader object-handler-query-function) 
    371419   (object-class :initarg :object-class :reader object-handler-object-class)) 
    372   (:default-initargs :object-class t :query-function nil)) 
    373  
    374 (defgeneric object-handler-get-object (object-handler)) 
    375 (defgeneric handle-object (object-handler object)) 
    376  
    377 (defmethod object-handler-get-object ((handler object-handler)) 
    378   (let ((id (parse-url))) 
    379     (when id 
    380       (find-store-object id 
    381                          :class (object-handler-object-class handler) 
    382                          :query-function (object-handler-query-function handler))))) 
     420  (:default-initargs :object-class t :query-function nil) 
     421  (:documentation "An OBJECT-HANDLER handles requests for a persistent 
     422object in the BKNR datastore.  The first component of the relative 
     423path of the request is used as the key to locate the object.  The 
     424object is looked up using the OBJECT-HANDLER-GET-OBJECT generic 
     425function, which will, by default, call FIND-STORE-OBJECT with the key 
     426as argument. 
     427 
     428The :QUERY-FUNCTION initarg may be supplied to set up a query function 
     429that maps from the key to an object.  It is typically used to 
     430implement lookup by name. 
     431 
     432The :OBJECT-CLASS initarg may be supplied to restrict the handler to 
     433operate on objects of that class or its subclass.  If the key 
     434specifies the ID of an object that has a different class or if the 
     435QUERY-FUNCTION returns an object of a different class, a run-time 
     436error is signaled.")) 
     437 
     438(defgeneric object-handler-get-object (object-handler) 
     439  (:documentation "Implement object lookup.  Methods return the object 
     440that the current request should operate upon.  The default method for 
     441the OBJECT handler class performs a lookup using FIND-STORE-OBJECT.") 
     442  (:method ((handler object-handler)) 
     443    (let ((id (parse-url))) 
     444      (when id 
     445        (find-store-object id 
     446                           :class (object-handler-object-class handler) 
     447                           :query-function (object-handler-query-function handler)))))) 
     448 
     449(defgeneric handle-object (object-handler object) 
     450  (:documentation "Handle the current to the OBJECT-HANDLER.  OBJECT 
     451is the object as looked up by OBJECT-HANDLER-GET-OBJECT.")) 
    383452 
    384453(defmethod handle ((handler object-handler)) 
    …… 
    387456 
    388457(defclass edit-object-handler (form-handler object-handler) 
    389   ()) 
    390  
    391 (defgeneric handle-object-form (handler action object)) 
     458  () 
     459  (:documentation "Combined FORM-HANDLER and OBJECT-HANDLER class that 
     460is used as a base class for handlers that edit an object using a HTML 
     461form.")) 
     462 
     463(defgeneric handle-object-form (handler action object) 
     464  (:documentation "Perform ACTION, a keyword that has been determined by 
     465parsing the \"action\" input element of the current HTML form, on 
     466OBJECT, which is parsed using the mechanism of an OBJECT-HANDLER.")) 
    392467 
    393468(defmethod handle-form ((handler edit-object-handler) action)