Table of Contents
By Pete Su
This document is a brief introduction to the ACS 4 Request Processor; more details can be found in the ACS 4 Request Processor Design. Here we cover the high level concepts behind the system, and implications and usage for the application developer.
In older versions of the ACS, the mapping between URLs and pages was simple. AOLserver (the usual webserver for the ACS) would find the appropriate file by appending the server's page-root to the path in the URL and returning that file to the user. For example, a user's request for a URL like "http://foo-service.com/bar.html" would cause the server to look in the filesystem for /web/foo-service/www/bar.html, and return that file. This was simple enough, but ACS did not provide a clean centralized mechanism for the following requirements of larger web services:
To achieve this functionality above in ACS 3.x, developers used an ad hoc combination of AOLserver filters, the ns_perm call, special purpose code in pages, and other procedures. In ACS 4, the Request Processor, along with the ACS Package Manager, centralizes and unifies this functionality, making it more transparent and readily available to developers.The 4.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.
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 Section 8.). 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_conn procedure, which is described in detail in ACS 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.
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.
Next, the Request Processor checks if the user has appropriate access privileges to the requested part of the site. In ACS 4, 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.
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, .tcl and .adp.
If the RP can't find any matching files with the expected extensions, it will look for virtual-url-handler files, or .vuh files. A .vuh file 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 .vuh file to act like a registered procedure for an entire subtree of the URL namespace. Thus a .vuh file 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 ACS 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:
The ID of the user associated with this request. By convention this is zero if there is no user.
The ID of the session associated with this request.
The URL associated with the request.
The URL associated with the request, represented as a list instead of a single string.
The actual local filesystem path of the file that is being served.
If the URL refers to a site map object, this is the URL to the root of the tree where the object is mounted.
If the URL refers to a package instance, this is the URL to the root of the tree where the package is mounted.
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.
If the URL refers to a site map object, this is the ID of that object.
If the URL refers to a package instance, this is the ID of that package instance.
If the URL refers to a package instance, this is the unique key name of the package.