A CL-HTTP Primer - Export Options

Export Options

This page describes the additional options available when exporting URLs in CL-HTTP.

Specifying the expiry time

You can supply an :expiration parameter to export-url. This allows browsers to serve up a cached version of the page, rather than needing to fetch a fresh copy from the server, which improves efficiency.

If you are dynamically generating a page with changing information you will want to specify that the page expires immediately, so that the browser always fetches an up to date version. If however the page is a static page of text which seldom changes, you can improve efficiency by specifying an expiration time of several minutes or even hours.

The following options are available:

Option	Description
:no-expiration-header	No EXPIRES header is issued.
:never	EXPIRES headers indicate one year from now.
:time	EXPIRES header indicates a universal time.
:interval	EXPIRES headers indicate now plus an interval.
:function	EXPIRES headers indicate a universal time computed by applying function to the URL. The function should return a universal time for use in the EXPIRES header or nil, in which case no EXPIRES header is issued.

The most usual options are:

:expiration '(:no-expiration-header)

for a dynamic page that should never be cached, or:

:expiration `(:interval ,(* 15. 60.))

to allow caching for 15 minutes for a fairly static page that changes infrequently.

Example

The following example illustrates the use of the :expiration parameter:

(defparameter *version* 0)
(defparameter *last-fetch* 0)

(defmethod display-test-page ((url http-url) stream)
  "Routine to test export options."
  (let ((title "Test Page")
        (now (get-universal-time)))
    (with-successful-response (stream :html :expires (expiration-universal-time url))
       (with-html-document (:declare-dtd-version-p :transitional :stream stream)
         (with-document-preamble (:stream stream)
           (declare-title title :stream stream))
         (with-document-body (:stream stream)
             (with-section-heading (title :stream stream)
               (with-paragraph (:stream stream) 
                 (format stream "Version: ~a. Time since last version: ~a secs" 
                         (incf *version*) (- now *last-fetch*))))
             (setq *last-fetch* now)
             (note-anchor "Update" :reference "/test.html" :stream stream))))))

we export the page with an :expiration parameter of 5 seconds:

(export-url #u("/test.html" :host "localhost" :port 8000)
            :computed
            :response-function 'display-test-page
            :expiration `(:interval 5))

Note that the call to with-successful-response needs to pick up the :expiration parameter and supply it to the :expires keyword using the function expiration-universal-time.

This displays the following page:

Clicking the Update link has no effect until the 5 second expiration time has elapsed, because the browser uses the cached version of the page.

Now change the :expiration parameter in export-url to:

:expiration '(:no-expiration-header)

Now the Update link updates the page whenever it is clicked.