perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/api/Apache SubRequest.pod
Date Sat, 14 Aug 2004 05:10:32 GMT
stas        2004/08/13 22:10:32

  Modified:    src/docs/2.0/api/Apache SubRequest.pod
  Log:
  finish the manpage
  
  Revision  Changes    Path
  1.5       +255 -91   modperl-docs/src/docs/2.0/api/Apache/SubRequest.pod
  
  Index: SubRequest.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/SubRequest.pod,v
  retrieving revision 1.4
  retrieving revision 1.5
  diff -u -u -r1.4 -r1.5
  --- SubRequest.pod	22 May 2004 02:03:27 -0000	1.4
  +++ SubRequest.pod	14 Aug 2004 05:10:31 -0000	1.5
  @@ -8,15 +8,35 @@
   =head1 Synopsis
   
     use Apache::SubRequest ();
  -
  -META: to be completed
  +  
  +  # run internal redirects at once
  +  $r->internal_redirect($new_uri);
  +  $r->internal_redirect_handler($new_uri);
  +  
  +  # create internal redirect objects
  +  $subr = $r->lookup_uri("/foo");
  +  $subr = $r->lookup_method_uri("GET", "/tmp/bar")
  +  $subr = $r->lookup_file("/tmp/bar");
  +  # optionally manipulate the output through main request filters
  +  $subr = $r->lookup_uri("/foo", $r->output_filters);
  +  # now run them
  +  my $rc = $subr->run;
  +  # optional
  +  $subr->DESTROY;
   
   
   
   
   =head1 Description
   
  -META: to be completed
  +C<Apache::SubRequest> contains API for creating and running of Apache
  +sub-requests.
  +
  +C<Apache::SubRequest> is a sub-class of C<L<Apache::RequestRec
  +object|docs::2.0::api::Apache::RequestRec>>.
  +
  +
  +
   
   
   
  @@ -28,255 +48,399 @@
   
   
   
  -=head2 C<DESTROY>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=head2 C<DESTROY>
   
   Free the memory associated with a sub request
   
  -  $r->DESTROY();
  +  $subr->DESTROY();
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$subr> ( C<L<Apache::SubRequest
  +object|docs::2.0::api::Apache::SubRequest/Description>> )
   
   The sub request to finish
   
   =item ret: no return value
   
  +=item since: 1.99_12
  +
   =back
   
  +This method will be called automatically when C<$subr> goes out of
  +scope, so there is no need to call it explicitly, unless you want to
  +free the memory earlier than that (for example if you run several
  +subrequests).
  +
  +
  +
  +
   
   
   
   
  -=head2 C<internal_fast_redirect>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Redirect the current request to a sub_req, merging the pools
   
  -  $r->internal_fast_redirect($sub_req);
  +
  +=head2 C<internal_redirect>
  +
  +Redirect the current request to some other uri internally
  +
  +  $r->internal_redirect($new_uri);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item arg1: C<$sub_req> (string)
  +=item arg1: C<$new_uri> ( string )
   
  -A subrequest created from this request
  +The URI to replace the current request with
   
   =item ret: no return value
   
  +=item since: 1.99_12
  +
   =back
   
  +In case that you want some other request to be served as the top-level
  +request instead of what the client requested directly, call this
  +method from a handler, and then immediately return C<Apache::OK>. The
  +client will be unaware the a different request was served to her
  +behind the scenes.
   
   
   
   
  -=head2 C<internal_redirect>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Then there's the case that you want some other request to be served as
  -the top-level request INSTEAD of what the client requested directly.
  -If so, call this from a handler, and then immediately return OK.
   
  -Redirect the current request to some other uri
   
  -  $r->internal_redirect($new_uri);
  +=head2 C<internal_redirect_handler>
  +
  +Identical to C<internal_redirect|/C_internal_redirect_>, plus
  +automatically sets
  +C<L<$r-E<gt>content_type|docs::2.0::api::Apache::RequestRec/C_content_type_>>
  +is of the sub-request to be the same as of the main request, if
  +C<L<$r-E<gt>handler|docs::2.0::api::Apache::RequestRec/C_handler_>> is
  +true.
  +
  +  $r->internal_redirect_handler($new_uri);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item arg1: C<$new_uri> (string)
  +=item arg1: C<$new_uri> ( string )
   
  -The URI to replace the current request with
  +The URI to replace the current request with.
   
   =item ret: no return value
   
  +=item since: 1.99_12
  +
   =back
   
  +This function is designed for things like actions or CGI scripts, when
  +using C<AddHandler>, and you want to preserve the content type across
  +an internal redirect.
   
   
   
   
  -=head2 C<internal_redirect_handler>
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -This function is designed for things like actions or CGI scripts, when
  -using AddHandler, and you want to preserve the content type across an
  -internal redirect.
   
  -  $r->internal_redirect_handler($new_uri);
  +
  +
  +
  +=head2 C<lookup_file>
  +
  +Create a subrequest for the given file.  This sub request can be
  +inspected to find information about the requested file
  +
  +  $ret = $r->lookup_file($new_file);
  +  $ret = $r->lookup_file($new_file, $next_filter);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item arg1: C<$new_uri> (string)
  +=item arg1: C<$new_file> ( string )
   
  -The URI to replace the current request with.
  +The file to lookup
   
  -=item ret: no return value
  +=item opt arg2: C<$next_filter>
  +( C<L<Apache::Filter|docs::2.0::api::Apache::Filter>> )
   
  -=back
  +See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for details.
   
  +=item ret: C<$ret> ( C<L<Apache::SubRequest
  +object|docs::2.0::api::Apache::SubRequest/Description>> )
   
  +The sub request record.
   
  +=item since: 1.99_15
   
  +=back
   
  -=head2 C<lookup_dirent>
  +See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for further discussion.
   
  -META: Autogenerated - needs to be reviewed/completed
   
  -Create a sub request for the given apr_dir_read result.  This sub request
  -can be inspected to find information about the requested file
   
  -  $lr = $r->lookup_dirent($finfo, $subtype, $next_filter);
  +
  +=head2 C<lookup_method_uri>
  +
  +Create a sub request for the given URI using a specific method.  This
  +sub request can be inspected to find information about the requested
  +URI
  +
  +  $ret = $r->lookup_method_uri($method, $new_uri);
  +  $ret = $r->lookup_method_uri($method, $new_uri, $next_filter);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item arg1: C<$finfo> (C<L<APR::Finfo|docs::2.0::api::APR::Finfo>>)
  +=item arg1: C<$method> ( string )
   
  -The apr_dir_read result to lookup
  +The method to use in the new sub request (e.g. C<"GET">)
   
  -=item arg2: C<$subtype> (integer)
  +=item arg2: C<$new_uri> ( string )
   
  -What type of subrequest to perform, one of;
  +The URI to lookup
   
  -  Apache::SUBREQ_NO_ARGS     ignore r->args and r->path_info
  -  Apache::SUBREQ_MERGE_ARGS  merge  r->args and r->path_info
  +=item opt arg3: C<$next_filter>
  +( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
   
  -=item arg3: C<$next_filter> (integer)
  +See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for details.
   
  -The first filter the sub_request should use.  If this is
  -NULL, it defaults to the first filter for the main request
  +=item ret: C<$ret> ( C<L<Apache::SubRequest
  +object|docs::2.0::api::Apache::SubRequest/Description>> )
   
  -=item ret: C<$lr> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +The sub request record.
   
  -The new request record
  +=item since: 1.99_15
   
   =back
   
  +See C<L<$r-E<gt>lookup_uri|/C_lookup_uri_>> for further discussion.
   
   
   
   
  -=head2 C<lookup_file>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=head2 C<lookup_uri>
   
  -Create a sub request for the given file.  This sub request can be
  -inspected to find information about the requested file
  +Create a sub request from the given URI.  This sub request can be
  +inspected to find information about the requested URI.
   
  -  $ret = $r->lookup_file($new_file, $next_filter);
  +  $ret = $r->lookup_uri($new_uri);
  +  $ret = $r->lookup_uri($new_uri, $next_filter);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item arg1: C<$new_file> (string)
  +=item arg1: C<$new_uri> ( string )
   
   The URI to lookup
   
  -=item arg2: C<$next_filter> (C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)
  +=item opt arg2: C<$next_filter>
  +( C<L<Apache::Filter object|docs::2.0::api::Apache::Filter>> )
   
  -The first filter the sub_request should use.  If this is NULL, it
  -defaults to the first filter for the main request
  +The first filter the subrequest should pass the data through.  If not
  +specified it defaults to the first connection output filter for the
  +main request
  +C<L<$r-E<gt>proto_output_filters|docs::2.0::api::Apache::RequestRec/C_proto_output_filters_>>.
So
  +if the subrequest sends any output it will be filtered only once. If
  +for example you desire to apply the main request's output filters to
  +the sub-request output as well pass
  +C<L<$r-E<gt>output_filters|docs::2.0::api::Apache::RequestRec/C_output_filters_>>
  +as an argument.
   
  -=item ret: C<$ret> (C<L<Apache::SubRequest|docs::2.0::api::Apache::SubRequest>>)
  +=item ret: C<$ret> ( C<L<Apache::SubRequest
  +object|docs::2.0::api::Apache::SubRequest/Description>> )
   
  -The new request record
  +The sub request record
  +
  +=item since: 1.99_15
   
   =back
   
  +Here is an example of a simple subrequest which serves uri
  +I</new_uri>:
   
  +  sub handler {
  +      my $r = shift;
  +  
  +      my $subr = $r->lookup_uri("/new_uri");
  +      $sub->run;
  +  
  +      return Apache::OK;
  +  }
   
  +If let's say you have three request output filters registered to run
  +for the main request:
  +
  +  PerlOutputFilterHandler MyApache::SubReqExample::filterA
  +  PerlOutputFilterHandler MyApache::SubReqExample::filterB
  +  PerlOutputFilterHandler MyApache::SubReqExample::filterC
  +
  +and you wish to run them all, the code needs to become:
  +
  +      my $subr = $r->lookup_uri("/new_uri", $r->output_filters);
  +
  +and if you wish to run them all, but the first one (C<filterA>), the
  +code needs to be adjusted to be:
  +
  +      my $subr = $r->lookup_uri("/new_uri", $r->output_filters->next);
  +
  +
  +
  +
  +
  +=head2 C<run>
  +
  +Run a sub-request
  +
  +  $rc = $subr->run();
  +
  +=over 4
  +
  +=item obj: C<$subr>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
  +
  +The sub-request (e.g. returned by C<L<lookup_uri|/C_lookup_uri_>>)
  +
  +=item ret: C<$rc> ( integer )
  +
  +The return code of the handler (C<Apache::OK>, C<Apache::DECLINED>,
  +etc.)
  +
  +=item since: 1.99_12
  +
  +=back
  +
  +
  +
  +
  +
  +
  +=head1 Unsupported API
  +
  +C<Apache::SubRequest> also provides auto-generated Perl interface for
  +a few other methods which aren't tested at the moment and therefore
  +their API is a subject to change. These methods will be finalized
  +later as a need arises. If you want to rely on any of the following
  +methods please contact the L<the mod_perl development mailing
  +list|maillist::dev> so we can help each other take the steps necessary
  +to shift the method to an officially supported API.
   
   
  -=head2 C<lookup_uri>
  +
  +
  +
  +
  +=head2 C<internal_fast_redirect>
   
   META: Autogenerated - needs to be reviewed/completed
   
  -Create a sub request from the given URI.  This sub request can be
  -inspected to find information about the requested URI.
  +Redirect the current request to a sub_req, merging the pools
   
  -  $ret = $r->lookup_uri($new_file, $next_filter);
  +  $r->internal_fast_redirect($sub_req);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item arg1: C<$new_file> (string)
  +=item arg1: C<$sub_req> ( string )
   
  -The URI to lookup
  +A subrequest created from this request
   
  -=item arg2: C<$next_filter> (C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)
  +=item ret: no return value
   
  -The first filter the sub_request should use.  If this is NULL, it
  -defaults to the first filter for the main request
  +=item since: 1.99_12
   
  -=item ret: C<$ret> (C<L<Apache::SubRequest|docs::2.0::api::Apache::SubRequest>>)
  +=back
   
  -The new request record
   
  -=back
  +META: httpd-2.0/modules/http/http_request.c declares this function as:
   
  +  /* XXX: Is this function is so bogus and fragile that we deep-6 it? */
  +
  +do we really want to expose it to mod_perl users?
   
   
   
   
  -=head2 C<lookup_method_uri>
  +
  +
  +=head2 C<lookup_dirent>
   
   META: Autogenerated - needs to be reviewed/completed
   
  -Create a sub request for the given URI using a specific method.  This
  -sub request can be inspected to find information about the requested
  -URI
  +Create a sub request for the given apr_dir_read result.  This sub request
  +can be inspected to find information about the requested file
   
  -  $ret = $r->lookup_method_uri($method, $new_file, $next_filter);
  +  $lr = $r->lookup_dirent($finfo);
  +  $lr = $r->lookup_dirent($finfo, $subtype);
  +  $lr = $r->lookup_dirent($finfo, $subtype, $next_filter);
   
   =over 4
   
  -=item obj: C<$r> (C<L<Apache::RequestRec|docs::2.0::api::Apache::RequestRec>>)
  +=item obj: C<$r>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The current request
   
  -=item arg1: C<$method> (string)
  +=item arg1: C<$finfo>
  +( C<L<APR::Finfo object|docs::2.0::api::APR::Finfo>> )
   
  -The method to use in the new sub request
  +The apr_dir_read result to lookup
   
  -=item arg2: C<$new_file> (string)
  +=item arg2: C<$subtype> ( integer )
   
  -The URI to lookup
  +What type of subrequest to perform, one of;
   
  -=item arg3: C<$next_filter> (C<L<Apache::Filter|docs::2.0::api::Apache::Filter>>)
  +  Apache::SUBREQ_NO_ARGS     ignore r->args and r->path_info
  +  Apache::SUBREQ_MERGE_ARGS  merge  r->args and r->path_info
   
  -The first filter the sub_request should use.  If this is NULL, it
  -defaults to the first filter for the main request
  +=item arg3: C<$next_filter> ( integer )
   
  -=item ret: C<$ret> (C<L<Apache::SubRequest|docs::2.0::api::Apache::SubRequest>>)
  +The first filter the sub_request should use.  If this is
  +NULL, it defaults to the first filter for the main request
  +
  +=item ret: C<$lr>
  +( C<L<Apache::RequestRec object|docs::2.0::api::Apache::RequestRec>> )
   
   The new request record
   
  +=item since: 1.99_12
  +
   =back
  +
  +META: where do we take the apr_dir_read result from?
  +
   
   
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message