ACS Documentation : ACS Core Architecture Guide : ACS Request Processor
/web/arsdigita/wwwto the URL, serving up the file named by that path.
This is no longer the case: the process of responding to a request involves many more steps than simply resolving a path and delivering a file. Serving an ACS page involves (at the very least) reading security information from HTTP cookies, extracting subcommunity information from the URL, calling filters and registered procedures, invoking the abstract URL system to determine which file to serve, and then actually serving the file.
The traditional way to realize this process was to register a plethora of filters and procedures, but there were several problems with this approach:
/wwwdirectory), as in the case of pages associated with packages.
ns_register_procs for each possible URL prefix (
/download/files/wouldn't work for requests under
ns_register_procs), allowing us a great deal of control over exactly what happens when we deliver a response to an HTTP request. We also introduced new APIs,
ad_register_proc, analogous to existing AOLserver APIs (
ns_register_proc) but tightly integrated into the request processor.
preauthfilter. In fact, it is the only filter ever registered with AOLserver. We've killed off
ns_register_proc- see the API below. It contains the following steps:
ad_connglobal variable, which contains information about the connection (see
*-procs.tclfiles, source them. Also examine any files registered to be watched (via the package manager); if any have been changed, source them as well.
Hostheader to make sure it's what we expect it to be. If the
Hostheader is present but differs from the canonical server name (as reported by
ns_info location), issue an HTTP redirect using the the correct, canonical server name.
For instance, if someone accesses the URL
http://arsdigita.com/pages/customers, we redirect them to
http://www.arsdigita.com/pages/customers since the canonical
host name for the server is
ad_session_id. If either is is invalid or not present at all, issue a cookie and note information about the new browser or session in the database.
/groups/Boston/address-book/belongs to the Boston subcommunity), strip the subcommunity information from the URL and save it in the environment to be later accessed by
This is not implemented in ACS 3.3.
ad_register_filter. Use the URL with subcommunity stripped as the string to be matched against patterns passed to
ad_register_filter, e.g. if a filter is registered on
/download/files/, it will be applied on URLs like
/groups/Boston/download/files/*since we stripped
/groups/Bostonfrom the URL in the step above.
ad_register_proc, invoke it. As in the previous step, match using the URL minus subcommunity information. If such a procedure is found, the process terminates here.
First resolve the path:
rp_register_directory_map, map to the associated directory in the filesystem. For example, if we've called
then all requests under therp_register_directory_map "apm" "acs-core" "apm-docs"
/apmURL stub are mapped to the
apm-docs/www, and all requests under
/admin/apmare mapped to the
admin-wwwdirectory in that package. For example, if there's a package named
address-book, then requests under
/address-bookare mapped to the
/packages/address-book/wwwdirectory, and requests under
/admin/address-bookare mapped to
/web/arsdigita/www) to the URL, just like AOLserver always used to do.
Now check to see if the path refers to a directory without a trailing
slash, e.g. a request to
If this is the case, issue a redirect to the directory with the trailing
http://www.arsdigita.com/address-book/. This is
necessary so the browser will properly resolve relative HREFs.
Next determine which particular file to serve. If our file name is
filename, check to see if any files exist which are named
filename.*, i.e. we try automatically adding an extension to the
file name. If the URL ends in a trailing slash, then no file name is provided
so we look for an
index.* file instead.
Give precedence to particular extensions in the order specified
ExtensionPrecedence parameter, e.g. in general
prefer to serve
.tcl files rather than
.tcl) file, source it; if it's an ADP (
.adp) file, parse it. In either case, if the script or ADP built a document using the documents API, invoke the document handler to route the document to the appropriate master template.
ad_serve_htmlto serve it, including a comment link as appropriate.
rp_register_extension_handler, use that handler to serve the file. For example, if I call
then if the file is a JSP (rp_register_extension_handler jsp jsp_handler
.jsp) file, the
jsp_handlerroutine will be called and expected to return a page.
filter_return, i.e. it is always solely responsible for returning a page. Essentially it commandeers the entire AOLserver page delivery process.
The exception is that you can specifically instruct the request
processor to leave certain URLs alone and return
filter_ok instead, by adding parameters of the form
LeaveAloneUrl=/cgi-bin/* to the
of your server
.ini file. Add more
LeaveAloneUrl= lines for more url patterns. The patterns
use glob matching (Tcl syntax is
string match $pattern $actual_url).
ns_register_procare dead - trying to use them causes an error. Instead of these two procedures, you'll need to use
ad_register_proc, drop-in replacements which provide the same functionality but are integrated into the request processor.
ad_register_filter when method URLpattern script [ args ... ]
ad_register_proc [ -noinherit f ] method URL procname [ args ... ]
ns_register_proc. See the AOLserver documentation for syntax.
ns_conn). Allowed values for which are:
url: same as
ns_conn url. (In future versions of ACS with subcommunity support, this will return the portion of the URL after any subcommunity information. For instance, for a URL request to
/groups/Boston/address-book/, it would return
canonical_url: returns a URL, minus extension, which is consistent no matter what URL is used to access a resource. For instance, if any of the following URLs are used to access the address book: Boston office:
then the canonical URL for each might be/address-book/ /address-book/index /address-book/index.tcl
This URL is useful whenever a consistent, unique identifier for a resource is necessary, e.g. storing URLs for general comments./address-book/index
full_url: similar to
ad_conn canonical_url, except that the extension of the file is included. For instance, in the case of the example above,
ad_conn full_urlwould return
file: returns the absolute path in the filesystem of the file which is being delivered. If the request does not correspond to a file (e.g. is a registered filter or procedure), returns an empty string.
extension: returns the extension of the file which is being delivered (equivalent to
[file extension [ad_conn file]]). If the request does not correspond to a file (e.g. is a registered filter or procedure), returns an empty string.
browser_id: returns the client's browser ID (see the document security and session-tracking).
session_id: returns the client's session ID (see the document security and session-tracking).
[ns/server/yourservername/request-processor] ; Log lots of timestamped debugging messages? DebugP=0 ; URL sections exempt from Host header checks and security/session handling. ; (can specify an arbitrary number). SystemURLSection=SYSTEM ; URLs that the request-processor should simply pass on to AOLserver to handle ; good candidates for these are URLs handled by nscgi.so or nsphp.so ;LeaveAloneUrl=/cgi-bin/* ;LeaveAloneUrl=/php/*
Integration with subcommunities.