\label{Guts_Apache}

The standard mode in which the Apache web server is used is that a
URL corresponds to some static file on the file system, which then
more or less gets sent out as-is. Slight deviations from that simple
principle are however already the directory listing function, virtual
servers, and the cgi-bin directory. In the latter case, Apache executes
the file in a new process and provides both the input to the process
in the environment, and routes the output to the client. Other deviations
are the error messages.

In a more general view, URLs to Apache are URIs (Uniform Resource
Identifiers), which may are may not correspond to a physical file,
which in turn may or may not be sent out as-is.

As a request for a URI gets sent to the Apache server, it goes through
several phases. At each phase ({}``stage'') along the process, handler
modules can be defined to deal with the request. Details about these
phases are given in {}``Writing Apache Modules with Perl and C''
from O'Reilly (the {}``Eagle book'') in Chapter 3 (page 60).

These handler modules are not like cgi-scripts executed in a separate
process, but are dynamically linked into the Apache child processes
themselves - they run inside of Apache. The mod\_perl mechanism in
addition links the Perl interpreter into the Apache child process.
Modules are pre-interpreted ({}``compiled'') by the Perl interpreter
when they are first loaded, and the pre-interpreted code stays permanently
in the memory allocated to that Apache child process. The result is
a significant speed-up, and through the flexible mechanism of module
registration and different stages of the process, a high degree of
customizability.

LON-CAPA does \emph{not} use Apache::Registry, and so in addition
avoids the unnecessary overhead of emulating a cgi-environment within
the handlers. Instead, it makes direct use of the Apache Perl API
(Chapter 9, Eagle book).

If you intend to add new capabilities to LON-CAPA that require new
handlers, as opposed to tweaking current ones, we recommend buying
a copy of {}``Writing Apache Modules with Perl and C''; it is not
strictly necessary but it is the clearest description of what is going
on in the Apache server, and without it you will be challenged to
understand everything that is occurring in the server.