This document is a brief introduction to the OpenACS 5.7.0 +Request Processor; more details can be found in the OpenACS 4 +Request Processor Design. Here we cover the high level concepts +behind the system, and implications and usage for the application +developer.
+The 5.7.0 Request Processor is a global filter and set of Tcl
+procs that respond to every incoming URL reaching the server. The
+following diagram summarizes the stages of the request processor
+assuming a URL request like http://someserver.com/notes/somepage.adp.
-
+
- Stage 1: Search Site Map
-
+
The first thing the RP does is to map the given URL to the +appropriate physical directory in the filesystem, from which to +serve content. We do this by searching the site map data model +(touched on in the Packages, and further discussed in Writing OpenACS Application +Pages). This data model maps URLs to objects representing +content, and these objects are typically package instances.
After looking up the appropriate object, the RP stores the URL, +the ID of the object it found, and the package and package instance +the object belongs to into the environment of the connection. This +environment can be queried using the
+ad_connprocedure, which is described in +detail in OpenACS 4 Request Processor Design. +The page development tutorial +shows you how to use this interface to make your pages aware of +which instance was requested. - Stage 2: Authentication
Next, the Request Processor examines the request for session +information. Session information is generally sent from the client +(the user's browser) to the server via cookies. The security/session +handler is described in detail in its own document. It examines +the client request and either extracts or sets up new session +tokens for the user.
- Stage 3: Authorization
Next, the Request Processor checks if the user has appropriate +access privileges to the requested part of the site. In OpenACS +5.7.0, access control is dictated by the permissions system. In this case, +the RP checks if the user has "read" priviledges on the object in +the site map specified by the URL. This object is typically a +package instance, but it could easily be something more granular, +such as whehter the user can view a particular piece of content +within a package instance. This automatic check makes it easy to +set up sites with areas that are only accessible to specific groups +of users.
- Stage 4: URL Processing, File +Search
-
+
Finally, the Request Processor finds the file we intend to +serve, searching the filesystem to locate the actual file that +corresponds to an abstract URL. It searches for files with +predefined "magic" extensions, i.e. files that end with: +
.html,.tcland.adp.If the RP can't find any matching files with the expected +extensions, it will look for virtual-url-handler files, or +
.vuhfiles. A.vuhfile will be executed as if it were a +Tcl file, but with the tail end of the URL removed. This allows the +code in the.vuhfile to act +like a registered procedure for an entire subtree of the URL +namespace. Thus a.vuhfile can +be thought of as a replacement for filters and registered procs, +except that they integrate cleanly and correctly with the RP's URL +mapping mechanisms. The details of how to use these files are +described in OpenACS 4 Request Processor +Design.Once the appropriate file is found, it is either served directly +if it's static content, or sent to the template system or the +standard Tcl interpreter if it's a dynamic page.
+
+
Once the flow of control reaches a dynamic page, the Request
+Processor has populated the environment of the request with several
+pieces of useful information. The RP's environment is accessible
+through the ad_conn interface,
+and the following calls should be useful to you when developing
+dynamic pages:
-
+
[ad_conn +user_id]The ID of the user associated with this request. By convention +this is zero if there is no user.
[ad_conn +session_id]The ID of the session associated with this request.
[ad_conn +url]The URL associated with the request.
[ad_conn +urlv]The URL associated with the request, represented as a list +instead of a single string.
[ad_conn +file]The actual local filesystem path of the file that is being +served.
[ad_conn +object_url]If the URL refers to a site map object, this is the URL to the +root of the tree where the object is mounted.
[ad_conn +package_url]If the URL refers to a package instance, this is the URL to the +root of the tree where the package is mounted.
[ad_conn +extra_url]If we found the URL in the site map, this is the tail of the URL +following the part that matched a site map entry.
[ad_conn +object_id]If the URL refers to a site map object, this is the ID of that +object.
[ad_conn +package_id]If the URL refers to a package instance, this is the ID of that +package instance.
[ad_conn +package_key]If the URL refers to a package instance, this is the unique key +name of the package.
[ad_conn +path_info]In a .vuh file, path_info is the trailing part of the URL not +matched by the .vuh file.
+