|
Show Contents Previous Page Next Page
Chapter 3 - The Apache Module Architecture and API
Perl API Classes and Data Structures
In this section...
|
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 conn_rec structure,
which correspond to the Perl API's Apache::Server and Apache::Connection
objects. We have much more to say about using the request_rec in
Chapters 10 and 11 when we
discuss the C-language API in more detail.
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
- 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,
mod_perlsupports a more complex configuration API that allows modules to define and use custom configuration directives.
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.
The bulk of this book is devoted to all the many things you can do with the request 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.
Show Contents Go to Top Previous Page Next PageHandlers 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.
Show Contents Go to Top Previous Page Next PageThe 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.
- Apache::URI
Methods for generating and parsing URIs
- Apache::Log
Methods to generate nicely formatted log messages
- Apache::File
Methods to send the contents of static files in an HTTP/1.1-compliant fashion
- Apache::Util
Methods for manipulating HTTP dates and times, and for working with HTML documents
- Apache::ModuleConfig and Apache::CmdParms
Utilities for generating and processing custom configuration directives
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.
- Apache::Registry
A persistent CGI-like environment for legacy scripts and for writing high-performance modules without using the Apache API.
- Apache::PerlRun
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 under Apache::Registry.
- Apache::RegistryLoader
Speeds up Apache::Registry even further by preloading certain CGI scripts.
- Apache::Resource
Controls resource allocation to avoid poorly written scripts from hogging the server.
- Apache::PerlSections
Helper methods for configuring Apache dynamically using Perl embedded in its configuration files.
- Apache::StatINC
Reloads changed modules from disk automatically when they change, rather than the next time the server is restarted.
- Apache::Include
Simple wrappers around the subrequest API and a handler for running within mod_ include.
- Apache::Status
A Perl runtime browser often helpful when tracking down problems or satisfying curiosities.
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 PageCopyright © 1999 by O'Reilly & Associates, Inc.
