Show Contents Previous Page Next Page
Chapter 3 - The Apache Module Architecture and API
Perl API Classes and Data Structures
In this section...
Introduction Show Contents Go to Top Previous Page Next Page
We'll look now at what a handler subroutine sees when it is called. All interaction between the handler and the Apache server is done through the request record. In the Perl API, the request record is encapsulated within a request object, which for historical reasons is blessed into the Apache:: namespace. The Apache request object contains most of the information about the current transaction. It also contains references to other objects that provide further information about the server and the current transaction. The request object's server() method returns an Apache::Server object, which contains server configuration information. The connection() method returns an Apache::Connection object, which contains low-level information about the TCP/IP connection between the browser and the client.
In the C API, information about the request is passed to the handler as a
pointer to a
request_rec. Included among its various fields are
pointers to a
server_rec and a
which correspond to the Perl API's Apache::Server and Apache::Connection
objects. We have much more to say about using the
Chapters 10 and 11 when we
discuss the C-language API in more detail.
The Apache Request Object Show Contents Go to Top Previous Page Next Page
The Apache request object (the
request_rec in C) is the primary conduit for the transfer of information between modules and the server. Handlers can use the request object to perform several types of operations:
- Get and set information about the requested document
The URI of the requested document, its translated file name, its MIME type,
and other useful information are available through a set of request object
methods. For example, a method named uri() returns the requested
document's URI, and content_type() retrieves the document's MIME
type. These methods can also be used to change the values, for example, to
set the MIME type of a document generated on the fly.
- Get incoming HTTP headers
All the request headers are available through a method called header_in().
From this information you can recover the make and model of the browser,
the list of MIME types that the browser can display, any HTTP cookies
the server has set, and information about any content the browser wishes
to send, such as the contents of a fill-out form.
- Get and set outgoing HTTP headers
The outgoing HTTP headers, which do such things as set HTTP cookies,
control browser caching, and provide information about the requested document,
can be examined or set via a method called header_out(). Certain
very common outgoing headers have dedicated methods for setting their
values. For example, the outgoing Content-Type header is usually
set using the content_type() method rather than header_out().
Once the outgoing header fields are fully set up, the handler can send
them to the client with send_ http_header().
- Read incoming document data
When the browser sends document information to the server, such as the
contents of POSTed forms or uploaded files, the handler can use the request
object's read() method to read in and manage the submitted information.
- Create outgoing document data
Handlers that are responsible for content generation will use the request
object's print() method to send document data to the browser.
There are also methods for sending whole files in a single step.
- Get common per-transaction information
Commonly needed information, such as the remote browser's hostname and
the port at which the server established the connection, is available from
the request object through methods with names like get_remote_host()
and get_server_port(). More esoteric information is available through
the Apache::Connection and Apache::Server objects returned
by the connection() and server() methods, respectively.
- Log warnings and errors
The request object provides methods for writing formatted error messages
and warnings to the server error log. The simplest and most widely used
method is log_error(). There is also a fully fledged Apache::Log
class which gives you access to Apache's more advanced logging API.
- Control transaction processing
By calling the request object's custom_response(), handler(),
or internal_redirect() methods, a handler can control how the
transaction is to be processed by setting what modules will handle the
content generation phase of the request in the case of success or failure.
A handler can also kick off a sub-request using the lookup_uri()
or lookup_filename() methods.
- Get module configuration information
The PerlSetVar configuration file directive allows you to pass
runtime configuration information to Perl API modules using a simple key/value
system. Perl API modules fetch this information with the dir_config()
method. This eliminates the need to pass runtime information to Perl API
modules by making source code modifications. In addition,
supports a more complex configuration API that allows modules to define
and use custom configuration directives.
The bulk of this book is devoted to all the many things you can do with the request object.
The Apache::Server Object Show Contents Go to Top Previous Page Next Page
The Apache::Server class (a
server_rec in the C API) contains information about the server's configuration. From this object, handlers can recover such things as the email address of the server administrator, the list of virtual hosts that this server supports, and the port number(s) that this server listens to.
The Apache::Server object is also where per-server module configuration
information is stored and is an integral part of the custom configuration directive
API described in Chapter 8.
The Apache::Connection Object Show Contents Go to Top Previous Page Next Page
Handlers can use this class to retrieve all sorts of low-level information about the current connection. Among the information stored here are the TCP/IP socket endpoints of the server/browser connection, the remote and local IP addresses, and a flag that indicates when a connection was broken prematurely.
In addition, the Apache::Connection object provides information about
user authentication. You can recover the type of authentication in use with
the auth_type() method, and the authenticated user's name with the
user() method. These features are described in more detail in Chapter 6.
Other Core Classes Show Contents Go to Top Previous Page Next Page
The Perl API also defines a number of core classes that provide interfaces to other areas of the Apache C API. We'll describe them at length in later chapters when we need to use them. For now, we'll just list them so that you know they're there.
Methods for generating and parsing URIs
Methods to generate nicely formatted log messages
Methods to send the contents of static files in an HTTP/1.1-compliant
Methods for manipulating HTTP dates and times, and for working with
- Apache::ModuleConfig and Apache::CmdParms
Utilities for generating and processing custom configuration directives
Noncore Classes Show Contents Go to Top Previous Page Next Page
mod_perl comes with a set of standalone modules that are useful
in their own right. The most important of these is Apache::Registry,
which the next chapter covers in great detail. We list them briefly here just
so that you know they exist. See Appendix A, Standard
Noncore Modules, for a full reference guide to Apache::Registry
and its kin.
A persistent CGI-like environment for legacy scripts and for writing
high-performance modules without using the Apache API.
An object-oriented API for running Perl scripts inside of the Apache
server. It uses this API within its own handler which provides another
CGI emulation environment for running legacy scripts that do not run properly
Speeds up Apache::Registry even further by preloading certain
Controls resource allocation to avoid poorly written scripts from hogging
Helper methods for configuring Apache dynamically using Perl embedded
in its configuration files.
Reloads changed modules from disk automatically when they change, rather
than the next time the server is restarted.
Simple wrappers around the subrequest API and a handler for running
within mod_ include.
A Perl runtime browser often helpful when tracking down problems or
The next chapter begins a tutorial that takes you through the API one step
at a time, beginning with the all-important response phase. For the definitive
reference style listing of classes, methods, functions, and data types, see
Chapter 9 for the Perl API and Chapters 10
and 11 for the C API. Show Contents Go to Top Previous Page Next Page
Copyright © 1999 by O'Reilly & Associates, Inc.