rp.xml
Delivered as text/xml
[ hide source ] | [ make this the default ]
File Contents
<?xml version='1.0' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="request-processor" xreflabel="Request Processor">
<title>The Request Processor</title>
<authorblurb>
<para>By Pete Su</para>
</authorblurb>
<sect2 id="rp-overview"><title>Overview</title>
<para>
This document is a brief introduction to the OpenACS &version; Request Processor;
more details can be found in the <xref linkend="rp-design"/>. Here we cover the high-level concepts behind the
system, and implications and usage for the application developer.
</para>
</sect2>
<sect2 id="rp-thenewway"><title>Request Processor</title>
<para>
The &version; 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 <computeroutput>http://someserver.com/notes/somepage.adp</computeroutput>.
<mediaobject>
<imageobject>
<imagedata fileref="images/rp-flow.gif" format="GIF" align="center"/>
</imageobject>
</mediaobject>
</para>
<variablelist>
<varlistentry><term>Stage 1: Search Site Map</term>
<listitem><para>
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 <xref linkend="packages"/>, and further
discussed in <xref linkend="subsites"/>). This data model maps URLs to objects representing
content, and these objects are typically package instances.
</para>
<para>
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 <computeroutput>ad_conn</computeroutput> procedure,
which is described in detail in <xref linkend="rp-design"/>. The <link linkend="subsites">page
development</link> tutorial shows you how to use this interface to make
your pages aware of which instance was requested.
</para></listitem>
</varlistentry>
<varlistentry><term>Stage 2: Authentication</term>
<listitem><para>
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 <link linkend="security-notes">security/session handler</link> 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.
</para></listitem>
</varlistentry>
<varlistentry><term>Stage 3: Authorization</term>
<listitem><para>
Next, the Request Processor checks if the user has appropriate access
privileges to the requested part of the site. In OpenACS &version;, access control
is dictated by the <ulink url="permissions">permissions system</ulink>. In
this case, the RP checks if the user has "read" privileges 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 whether 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.
</para></listitem>
</varlistentry>
<varlistentry><term>Stage 4: URL Processing, File Search</term>
<listitem><para>
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: <computeroutput>.html</computeroutput>,
<computeroutput>.tcl</computeroutput> and <computeroutput>.adp</computeroutput>.
</para>
<para>
If the RP can't find any matching files with the expected extensions,
it will look for virtual-url-handler files, or <computeroutput>.vuh</computeroutput>
files. A <computeroutput>.vuh</computeroutput> 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 <computeroutput>.vuh</computeroutput> file to act like a registered procedure for
an entire subtree of the URL namespace. Thus a <computeroutput>.vuh</computeroutput> 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 <xref linkend="rp-design"/>.
</para>
<para>
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.
</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="rp-basicapi"><title>Basic API</title>
<para>
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
<computeroutput>ad_conn</computeroutput> interface, and the following calls should be
useful to you when developing dynamic pages:
</para>
<variablelist>
<varlistentry><term><computeroutput>[ad_conn user_id]</computeroutput>
</term><listitem><para>
The ID of the user associated with this request. By convention this is
zero if there is no user.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn session_id]</computeroutput>
</term><listitem><para>
The ID of the session associated with this request.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn url]</computeroutput>
</term><listitem><para>
The URL associated with the request.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn urlv]</computeroutput>
</term><listitem><para>
The URL associated with the request, represented as a list instead of
a single string.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn file]</computeroutput>
</term><listitem><para>
The actual local filesystem path of the file that is being served.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn object_url]</computeroutput>
</term><listitem><para>
If the URL refers to a site map object, this is the URL to the root
of the tree where the object is mounted.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn package_url]</computeroutput>
</term><listitem><para>
If the URL refers to a package instance, this is the URL to the root
of the tree where the package is mounted.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn extra_url]</computeroutput>
</term><listitem><para>
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.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn object_id]</computeroutput>
</term><listitem><para>
If the URL refers to a site map object, this is the ID of that object.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn package_id]</computeroutput>
</term><listitem><para>
If the URL refers to a package instance, this is the ID of that
package instance.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn package_key]</computeroutput>
</term><listitem><para>
If the URL refers to a package instance, this is the unique key name
of the package.
</para></listitem></varlistentry>
<varlistentry><term><computeroutput>[ad_conn path_info]</computeroutput>
</term><listitem><para>
In a .vuh file, path_info is the trailing part of the URL not matched
by the .vuh file.
</para></listitem></varlistentry>
</variablelist>
<para><phrase role="cvstag">($Id: rp.xml,v 1.13.2.2 2019/08/09 20:04:23 gustafn Exp $)</phrase></para>
</sect2>
</sect1>
