You are viewing a plain text version of this content. The canonical link for it is here.
Posted to apreq-cvs@httpd.apache.org by jo...@apache.org on 2003/11/01 01:03:11 UTC
cvs commit: httpd-apreq-2/glue/perl/xsbuilder/Apache/Request Request_pod
joes 2003/10/31 16:03:11
Modified: glue/perl/xsbuilder/Apache/Request Request_pod
Log:
Minor Request_pod cleanups
Revision Changes Path
1.4 +72 -194 httpd-apreq-2/glue/perl/xsbuilder/Apache/Request/Request_pod
Index: Request_pod
===================================================================
RCS file: /home/cvs/httpd-apreq-2/glue/perl/xsbuilder/Apache/Request/Request_pod,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Request_pod 29 Oct 2003 02:20:24 -0000 1.3
+++ Request_pod 1 Nov 2003 00:03:11 -0000 1.4
@@ -9,10 +9,9 @@
=head1 DESCRIPTION
-I<Apache::Request> is a subclass of the I<Apache> class, which adds methods
-for parsing B<GET> requests and B<POST> requests where I<Content-type>
-is one of I<application/x-www-form-urlencoded> or
-I<multipart/form-data>. See the libapreq(3) manpage for more details.
+I<Apache::Request> adds methods for parsing B<GET> requests and B<POST>
+requests where I<Content-type> is one of I<application/x-www-form-urlencoded> or
+I<multipart/form-data>.
=head1 Apache::Request METHODS
@@ -21,27 +20,23 @@
=over 4
-=item * C<Apache::Request::new> takes an Apache object as (second) argument.
-
+=item * C<Apache::Request::new> takes an environment-specific
+object as (second) argument.
=item * The query parameters are stored as Apache::Table objects,
and are therefore parsed using case-insensitive keys.
-
-=item * C<-attr =E<gt> $val> -type arguments are not supported. [WRONG- this works now]
-
-
=item * The query string is always parsed, even for POST requests.
=back
-=head2 new [NEEDS REWRITE: No longer require Apache* objects]
+=head2 new Create a new I<Apache::Request> object with an
+environment object $r:
-Create a new I<Apache::Request> object with an I<Apache::RequestRec> object $r:
+ my $req = Apache::Request->new($r);
- my $apr = Apache::Request->new($r);
-
-All methods from the I<Apache::RequestRec> class are inherited.
+With mod_perl2, the environment object must be an I<Apache::RequestRec>
+object. All methods from the environment class are inherited.
The following attributes are optional:
@@ -49,31 +44,11 @@
=item POST_MAX
-Limit the size of POST data (in bytes). I<Apache::Request::parse> will
-return an error code if the size is exceeded:
-
- my $apr = Apache::Request->new($r, POST_MAX => 1024);
- my $status = $apr->parse;
-
- if ($status) {
- my $errmsg = $apr->notes("error-notes");
- ...
- return $status;
- }
+Limit the size of POST data (in bytes).
=item DISABLE_UPLOADS
-Disable file uploads. I<Apache::Request::parse> will return an
-error code if a file upload is attempted:
-
- my $apr = Apache::Request->new($r, DISABLE_UPLOADS => 1);
- my $status = $apr->parse;
-
- if ($status) {
- my $errmsg = $apr->notes("error-notes");
- ...
- return $status;
- }
+Disable file uploads.
=item TEMP_DIR
@@ -81,8 +56,8 @@
that supports link(2), the TEMP_DIR should be located on the same
file system as the final destination file:
- my $apr = Apache::Request->new($r, TEMP_DIR => "/home/httpd/tmp");
- my $upload = $apr->upload('file');
+ my $req = Apache::Request->new($r, TEMP_DIR => "/home/httpd/tmp");
+ my $upload = $req->upload('file');
$upload->link("/home/user/myfile") || warn "link failed: $!";
=item HOOK_DATA [TODO]
@@ -106,158 +81,83 @@
HOOK_DATA => "Note",
UPLOAD_HOOK => $transparent_hook,
);
- $apr->parse;
=back
-=head2 instance [DEPRECATED, same as C<new>]
+=head2 param
-The instance() class method allows Apache::Request to be a singleton.
-This means that whenever you call Apache::Request->instance() within a
-single request you always get the same Apache::Request object back.
-This solves the problem with creating the Apache::Request object twice
-within the same request - the symptoms being that the second
-Apache::Request object will not contain the form parameters because
-they have already been read and parsed.
-
- my $apr = Apache::Request->instance($r, DISABLE_UPLOADS => 1);
-
-Note that C<instance()> call will take the same parameters as the above
-call to C<new()>, however the parameters will only have an effect the
-first time C<instance()> is called within a single request. Extra
-parameters will be ignored on subsequent calls to C<instance()> within
-the same request.
-
-Subrequests receive a new Apache::Request object when they call
-instance() - the parent request's Apache::Request object is not copied
-into the subrequest.
-
-Also note that it is unwise to use the C<parse()> method when using
-C<instance()> because you may end up trying to call it twice, and
-detecting errors where there are none.
-
-=head2 parse [TODO]
-
-The I<parse> method does the actual work of parsing the request.
-It is called for you by the accessor methods, so it is not required but
-can be useful to provide a more user-friendly message should an error
-occur:
-
- my $r = shift;
- my $apr = Apache::Request->new($r);
-
- my $status = $apr->parse;
- unless ($status == OK) {
- $apr->custom_response($status, $apr->notes("error-notes"));
- return $status;
- }
-
-=head2 param [TODO scalar PREFETCH]
-
-Get or set request parameters (using case-insensitive keys) by
-mimicing the OO interface of C<CGI::param>. Unlike the CGI.pm version,
-Apache::Request's param method is I<very> fast- it's now quicker than even
-mod_perl's native Apache->args method. However, CGI.pm's
-C<-attr =E<gt> $val> type arguments are not supported.
+Get or set (TODO) the request parameters (using case-insensitive keys) by
+mimicing the OO interface of C<CGI::param>.
# similar to CGI.pm
- my $value = $apr->param('foo');
- my @values = $apr->param('foo');
- my @params = $apr->param;
+ my $value = $req->param('foo');
+ my @values = $req->param('foo');
+ my @params = $req->param;
# the following differ slightly from CGI.pm
# assigns multiple values to 'foo'
- $apr->param('foo' => [qw(one two three)]);
+ $req->param('foo' => [qw(one two three)]); # TODO
# returns ref to underlying apache table object
- my $table = $apr->param; # identical to $apr->parms - see below
+ my $table = $req->param; # identical to $apr->parms - see below
-=head2 parms [DEPRECATED]
+=head2 parms, params
-Get or set the underlying apache parameter table of the I<Apache::Request>
-object. When invoked without arguments, C<parms> returns a reference
-to an I<Apache::Table> object that is tied to the Apache::Request
-object's parameter table. If called with an Apache::Table reference
-as as argument, the Apache::Request object's parameter table is
-replaced by the argument's table.
-
- # $apache_table references an Apache::Table object
- $apr->parms($apache_table); # sets $apr's parameter table
-
- # returns ref to Apache::Table object provided by $apache_table
- my $table = $apr->parms;
-
-=head2 upload [WRONG: $req->upload similar to $req->param now]
-
-Returns a single I<Apache::Upload> object in a scalar context or
-all I<Apache::Upload> objects in a list context:
-
- my $upload = $apr->upload;
- my $fh = $upload->fh;
- my $lines = 0;
- while(<$fh>) {
- ++$lines;
- ...
- }
+Get the full parameter table of the I<Apache::Request> object.
-An optional name parameter can be passed to return the I<Apache::Upload>
-object associated with the given name:
+ # returns ref to Apache::Request::Table object provided by $apache_table
+ my $table = $req->parms;
- my $upload = $apr->upload($name);
+An optional name parameter can be passed to return the parameter
+associated with the given name:
-=head1 SUBCLASSING Apache::Request [WRONG- This is unnecessary now]
+ my $param = $req->parms($name);
-The Apache::Request class cannot be subclassed directly because its constructor
-method does not bless new objects into the invocant class. Instead, it always
-blesses them into the Apache::Request class itself.
+=head2 args
-However, there are two main ways around this.
+Returns an I<Apache::Request::Table> object containing the query-string
+parameters of the I<Apache::Request> object.
-One way is to have a constructor method in your subclass that invokes the
-superclass constructor method and then re-blesses the new object into itself
-before returning it:
+ my $args = $req->args;
- package MySubClass;
- use Apache::Request;
- our @ISA = qw(Apache::Request);
- sub new {
- my($class, @args) = @_;
- return bless $class->SUPER::new(@args), $class;
- }
+An optional name parameter can be passed to return the query string
+parameter associated with the given name:
-The other way is to aggregate and delegate: store an Apache::Request object in
-each instance of your subclass, and delegate any Apache::Request methods that
-you are not overriding to it:
+ my $arg = $req->args($name);
- package MySubClass;
- use Apache::Request;
- sub new {
- my($class, @args) = @_;
- return bless { r => Apache::Request->new(@args) }, $class;
- }
- sub AUTOLOAD {
- my $proto = shift;
- return unless ref $proto;
- our $AUTOLOAD;
- my $name = $AUTOLOAD;
- $name =~ s/^.*:://;
- return $proto->{r}->$name(@_);
- }
+=head2 body
-A fancier AUTOLOAD() subroutine could be written to handle class methods too if
-required, but we leave that as an exercise for the reader because in fact the
-Apache::Request class provides some magic that makes the aggregate/delegate
-solution much easier.
+Returns an I<Apache::Request::Table> object containing the POST data
+parameters of the I<Apache::Request> object.
+
+ my $body = $req->body;
+
+An optional name parameter can be passed to return the POST data
+parameter associated with the given name:
+
+ my $param = $req->body($name);
+
+
+=head2 upload
+
+With no arguments, this returns an I<Apache::Upload::Table> object in
+scalar context, or the names of all I<Apache::Upload> objects in
+list context.
+
+An optional name parameter can be passed to return the I<Apache::Upload>
+object associated with the given name:
+
+ my $upload = $apr->upload($name);
+
+=head1 SUBCLASSING Apache::Request
If the instances of your subclass are hash references then you can actually
inherit from Apache::Request as long as the Apache::Request object is stored in
an attribute called "r" or "_r". (The Apache::Request class effectively does the
delegation for you automagically, as long as it knows where to find the
-Apache::Request object to delegate to.)
-
-Thus, the second example above can be simplified as:
+Apache::Request object to delegate to.) For example:
package MySubClass;
use Apache::Request;
@@ -281,22 +181,17 @@
my $filename = $upload->filename;
-=head2 fh [DEPRECATED: should use brigade API instead]
+=head2 bb [replaces fh]
-The filehandle pointing to the uploaded file:
+The APR::Brigade containing the contents of the uploaded file.
- my $fh = $upload->fh;
- while (<$fh>) {
- ...
- }
-
-=head2 size [TODO]
+=head2 size
The size of the file in bytes:
my $size = $upload->size;
-=head2 info [TODO]
+=head2 info
The additional header information for the uploaded file.
Returns a hash reference tied to the I<Apache::Table> class.
@@ -318,22 +213,6 @@
#same as
my $type = $upload->info("Content-Type");
-=head2 next [WRONG : uploads are table entries now, not linked lists]
-
-Upload objects are implemented as a linked list by libapreq; the
-I<next> method provides an alternative to using the I<Apache::Request>
-I<upload> method in a list context:
-
- for (my $upload = $apr->upload; $upload; $upload = $upload->next) {
- ...
- }
-
- #functionally the same as:
-
- for my $upload ($apr->upload) {
- ...
- }
-
=head2 tempname [XXX- Does this mesh with brigade API?]
Provides the name of the spool file. This method is reserved for
@@ -342,30 +221,29 @@
=head2 link
-To avoid recopying the spool file on a *nix-like system,
-I<link> will create a hard link to it:
+To avoid recopying the upload's internal tempfile brigade on a
+*nix-like system, I<link> will create a hard link to it:
my $upload = $apr->upload('file');
$upload->link("/path/to/newfile") or
die sprintf "link from '%s' failed: $!", $upload->tempname;
Typically the new name must lie on the same file system as the
-spool file. Check your system's link(2) manpage for details.
+brigade's tempfile. Check your system's link(2) manpage for details.
=head1 SEE ALSO
-libapreq(3), APR::Table(3)
+APR::Table(3)
=head1 CREDITS
This interface is based on the original pure Perl version by Lincoln Stein.
-=head1 AUTHOR
+=head1 AUTHORS
-Doug MacEachern, updated for v1.0 by Joe Schaefer
+Doug MacEachern, Joe Schaefer, Steve Hay.
=head1 MISSING DOCS
-$req->args, $req->body, $req->config, Apache::Request::Table,
-Apache::Upload::Table, $upload->bb.
+$req->config, Apache::Request::Table, Apache::Upload::Table.