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/user/porting compat.pod
Date Thu, 15 Jul 2004 20:51:09 GMT
stas        2004/07/15 13:51:09

  Modified:    src/docs/2.0/api Apache.pod
               src/docs/2.0/api/Apache RequestUtil.pod ServerUtil.pod
               src/docs/2.0/user/config config.pod
               src/docs/2.0/user/handlers http.pod server.pod
               src/docs/2.0/user/porting compat.pod
  Log:
  syncing docs with the recent API changes
  
  Revision  Changes    Path
  1.6       +1 -10     modperl-docs/src/docs/2.0/api/Apache.pod
  
  Index: Apache.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache.pod,v
  retrieving revision 1.5
  retrieving revision 1.6
  diff -u -u -r1.5 -r1.6
  --- Apache.pod	12 Jul 2004 23:13:22 -0000	1.5
  +++ Apache.pod	15 Jul 2004 20:51:08 -0000	1.6
  @@ -25,16 +25,7 @@
     use Apache::Server;
     my $server = Apache->server;
   
  -There are several modules that install constants into the C<Apache::>
  -namespace. For example
  -C<L<Apache::ServerUtil|docs::2.0::api::Apache::ServerUtil>> defines a
  -constant
  -C<L<Apache::server_root|docs::2.0::api::Apache::ServerUtil/C_Apache__server_root_>>:
  -
  -  use Apache::ServerUtil;
  -  my $server_root = Apache::server_root;
  -
  -To use this functions and methods you need to load the module that
  +To use these functions and methods you need to load the module that
   defines them. If you aren't sure which module contains the symbol you
   are after, use the helper module
   C<L<ModPerl::MethodLookup|docs::2.0::api::ModPerl::MethodLookup>>.
  
  
  
  1.24      +0 -50     modperl-docs/src/docs/2.0/api/Apache/RequestUtil.pod
  
  Index: RequestUtil.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/RequestUtil.pod,v
  retrieving revision 1.23
  retrieving revision 1.24
  diff -u -u -r1.23 -r1.24
  --- RequestUtil.pod	12 Jul 2004 23:13:22 -0000	1.23
  +++ RequestUtil.pod	15 Jul 2004 20:51:08 -0000	1.24
  @@ -55,9 +55,6 @@
     # merge a <Location> container in a request object
     $r->location_merge($location);
     
  -  # extend HTTP to support a new method
  -  Apache::RequestUtil::method_register($pool, $methname);
  -  
     # create a new Apache::RequestRec object
     $r = Apache::RequestRec->new($c);
     
  @@ -583,53 +580,6 @@
   C<Apache::RequestRec-E<gt>new()> method. See for example the L<Command
   Server protocol
   example|docs::2.0::user::handlers::protocols/Command_Server>.
  -
  -
  -
  -
  -
  -
  -
  -
  -
  -=head2 C<method_register>
  -
  -Register a new request method, and return the offset that will be
  -associated with that method.
  -
  -  $offset = Apache::RequestUtil::method_register($pool, $methname);
  -
  -=over 4
  -
  -=item arg1: C<$p> (C<L<APR::Pool|docs::2.0::api::APR::Pool>> )
  -
  -The pool to create registered method numbers from. Use a long lived
  -pool like:
  -
  -  $r->server->process->pconf;
  -
  -=item arg1: C<$methname> ( string )
  -
  -The name of the new method to register (in addition to the already
  -supported C<GET>, C<HEAD>, etc.)
  -
  -=item ret: C<$offset> ( integer )
  -
  -An int value representing an offset into a bitmask. You can probably
  -ignore it.
  -
  -=item since: 1.99_15
  -
  -=back
  -
  -This method allows you to extend the HTTP protocol to support new
  -methods, which fit the HTTP paradigm.  Of course you will need to
  -write a client that understands that protocol extension.  For a good
  -example, refer to the C<MyApache::SendEmail> example presented in
  -C<L<the PerlHeaderParserHandler
  -section|docs::2.0::user::handlers::http/PerlHeaderParserHandler>>,
  -which demonstrates how a new method C<EMAIL> is registered and used.
  -
   
   
   
  
  
  
  1.24      +210 -123  modperl-docs/src/docs/2.0/api/Apache/ServerUtil.pod
  
  Index: ServerUtil.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/api/Apache/ServerUtil.pod,v
  retrieving revision 1.23
  retrieving revision 1.24
  diff -u -u -r1.23 -r1.24
  --- ServerUtil.pod	12 Jul 2004 23:13:22 -0000	1.23
  +++ ServerUtil.pod	15 Jul 2004 20:51:08 -0000	1.24
  @@ -18,7 +18,9 @@
     # server level PerlOptions flags lookup
     $s->push_handlers(ChildExit => \&child_exit)
         if $s->is_perl_option_enabled('ChildExit');
  -
  +  
  +  # extend HTTP to support a new method
  +  $s->method_register('NEWGET');
   
   
   META: to be completed
  @@ -34,31 +36,29 @@
   
   
   
  +=head1 Methods API
   
  -=head1 Functions API
  +C<Apache::ServerUtil> provides the following functions and/or methods:
   
   
   
   
  -=head2 C<add_version_component>
   
  -META: Autogenerated - needs to be reviewed/completed
  +=head2 C<add_config>
   
  -Add a component to the version string
  +Dynamically add Apache configuration:
   
  -  add_version_component($pconf_pool, $component);
  +  $s->add_config($lines);
   
   =over 4
   
  -=item obj: C<$pconf>
  -( C<L<APR::Pool object|docs::2.0::api::APR::Pool>> )
  -
  -The pool to allocate the component from (should really be a
  -C<$pconf_pool>)
  +=item obj: C<$s>
  +( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )
   
  -=item arg1: C<$component> ( string )
  +=item arg1: C<$lines> ( ARRAY ref )
   
  -The string to add
  +An ARRAY reference containing configuration lines per element, without
  +the new line terminators.
   
   =item ret: no return value
   
  @@ -66,146 +66,91 @@
   
   =back
   
  -
  -
  -
  -
  -=head2 C<exists_config_define>
  -
  -Check for a definition from the server command line
  -
  -  $result = Apache::exists_config_define($name);
  -
  -=over 4
  -
  -=item obj: C<$name> ( string )
  -
  -The define to check for
  -
  -=item ret: C<$result> ( boolean )
  -
  -true if defined, false otherwise
  -
  -=item since: 1.99_10
  -
  -=back
  +See also:
  +C<L<$r-E<gt>add_config|docs::2.0::api::Apache::RequestUtil/C_add_config_>>
   
   For example:
   
  -  print "this is mp2" if Apache::exists_config_define('MODPERL2');
  -
  -
  -
  -
  -=head2 C<get_server_built>
  -
  -Get the date and time that the server was built
  -
  -  $when_built = Apache::ServerUtil::get_server_built();
  -
  -=over 4
  -
  -=item ret: C<$when_built> ( string )
  -
  -The server build time string
  +Add a configuration section at the server startup (e.g. from
  +I<startup.pl>):
   
  -=item since: 1.99_10
  +  use Apache::ServerUtil ();
  +  my $conf = <<'EOC';
  +  PerlModule Apache::MyExample
  +  <Location /perl>
  +    SetHandler perl-script
  +    PerlResponseHandler Apache::MyExample
  +  </Location>
  +  EOC
  +  Apache->server->add_config([split /\n/, $conf]);
   
  -=back
   
   
   
   
   
   
  -=head2 C<get_server_version>
  +=head2 C<add_version_component>
   
  -Get the server version string
  +Add a component to the version string
   
  -  $version = Apache::ServerUtil::get_server_version();
  +  $s->add_version_component($component);
   
   =over 4
   
  -=item ret: C<$version> ( string )
  -
  -The server version string
  -
  -=item since: 1.99_10
  -
  -=back
  -
  -
  -
  -
  -
  -
  -=head2 C<server_root>
  -
  -returns the value set by the top-level C<ServerRoot> directive.
  +=item obj: C<$s>
  +( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )
   
  -  $server_root = Apache::ServerUtil::server_root();
  +=item arg1: C<$component> ( string )
   
  -=over 4
  +The string componennt to add
   
  -=item ret: C<$server_root> ( string )
  +=item ret: no return value
   
  -=item since: 1.99_10
  +=item since: 1.99_15
   
   =back
   
  +This function is usually used by modules to advertise themselves to
  +the world. It's picked up by such statistics collectors, like
  +netcraft.com, which accomplish that by connecting to various servers
  +and grabbing the server version response header (C<Server>). Some
  +servers choose to fully or partially conceal that header.
   
  +This method should be invoked in the
  +C<L<PerlPostConfigHandler|docs::2.0::user::handlers::server/PerlPostConfigHandler>>
  +phase, which will ensure that the Apache core version number will
  +appear first.
   
  +For example let's add a component I<"Hikers, Inc/0.99999"> to the
  +server string at the server startup:
   
  +  use Apache::ServerUtil ();
  +  use Apache::Const -compile => 'OK';
  +  
  +  Apache->server->push_handlers(
  +      PerlPostConfigHandler => \&add_my_version);
  +  
  +  sub add_my_version {
  +      my($conf_pool, $log_pool, $temp_pool, $s) = @_;
  +      $s->add_version_component("Hikers, Inc/0.99999");
  +      return Apache::OK;
  +  }
  +
  +or of course you could register the
  +C<L<PerlPostConfigHandler|docs::2.0::user::handlers::server/PerlPostConfigHandler>>
  +handler directly in F<httpd.conf>
  +
  +Now when the server starts, you will something like:
  +
  +  [Thu Jul 15 12:15:28 2004] [notice] Apache/2.0.51-dev (Unix)
  +  mod_perl/1.99_15-dev Perl/v5.8.5 Hikers, Inc/0.99999
  +  configured -- resuming normal operations
   
   
   
   
   
  -=head1 Methods API
  -
  -C<Apache::ServerUtil> provides the following functions and/or methods:
  -
  -
  -
  -=head2 C<add_config>
  -
  -Dynamically add Apache configuration:
  -
  -  $s->add_config($lines);
  -
  -=over 4
  -
  -=item obj: C<$s>
  -( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )
  -
  -=item arg1: C<$lines> ( ARRAY ref )
  -
  -An ARRAY reference containing configuration lines per element, without
  -the new line terminators.
  -
  -=item ret: no return value
  -
  -=item since: 1.99_10
  -
  -=back
  -
  -See also:
  -C<L<$r-E<gt>add_config|docs::2.0::api::Apache::RequestUtil/C_add_config_>>
  -
  -For example:
  -
  -Add a configuration section at the server startup (e.g. from
  -I<startup.pl>):
  -
  -  use Apache::ServerUtil ();
  -  my $conf = <<'EOC';
  -  PerlModule Apache::MyExample
  -  <Location /perl>
  -    SetHandler perl-script
  -    PerlResponseHandler Apache::MyExample
  -  </Location>
  -  EOC
  -  Apache->server->add_config([split /\n/, $conf]);
   
   
   
  @@ -285,6 +230,8 @@
   
   
   
  +
  +
   =head2 C<error_log2stderr>
   
   Start sending STDERR to the error_log file
  @@ -312,6 +259,41 @@
   
   
   
  +
  +
  +=head2 C<exists_config_define>
  +
  +Check for a definition from the server startup command line
  +(e.g. C<-DMODPERL2>)
  +
  +  $result = Apache::ServerUtil::exists_config_define($name);
  +
  +=over 4
  +
  +=item arg1: C<$name> ( string )
  +
  +The define string to check for
  +
  +=item ret: C<$result> ( boolean )
  +
  +true if defined, false otherwise
  +
  +=item since: 1.99_15
  +
  +=back
  +
  +For example:
  +
  +  print "this is mp2"
  +      if Apache::ServerUtil::exists_config_define('MODPERL2');
  +
  +
  +
  +
  +
  +
  +
  +
   =head2 C<get_handlers>
   
   Returns a reference to a list of handlers enabled for
  @@ -351,6 +333,50 @@
   
   
   
  +=head2 C<get_server_built>
  +
  +Get the date and time that the server was built
  +
  +  $when_built = Apache::ServerUtil::get_server_built();
  +
  +=over 4
  +
  +=item ret: C<$when_built> ( string )
  +
  +The server build time string
  +
  +=item since: 1.99_10
  +
  +=back
  +
  +
  +
  +
  +
  +
  +
  +=head2 C<get_server_version>
  +
  +Get the server version string
  +
  +  $version = Apache::ServerUtil::get_server_version();
  +
  +=over 4
  +
  +=item ret: C<$version> ( string )
  +
  +The server version string
  +
  +=item since: 1.99_10
  +
  +=back
  +
  +
  +
  +
  +
  +
  +
   =head2 C<is_perl_option_enabled>
   
   check whether a server level C<PerlOptions> flag is enabled or not.
  @@ -388,6 +414,49 @@
   
   
   
  +
  +
  +=head2 C<method_register>
  +
  +Register a new request method, and return the offset that will be
  +associated with that method.
  +
  +  $offset = $s->method_register($methname);
  +
  +=over 4
  +
  +=item obj: C<$s>
  +( C<L<Apache::ServerRec object|docs::2.0::api::Apache::ServerRec>> )
  +
  +=item arg1: C<$methname> ( string )
  +
  +The name of the new method to register (in addition to the already
  +supported C<GET>, C<HEAD>, etc.)
  +
  +=item ret: C<$offset> ( integer )
  +
  +An int value representing an offset into a bitmask. You can probably
  +ignore it.
  +
  +=item since: 1.99_15
  +
  +=back
  +
  +This method allows you to extend the HTTP protocol to support new
  +methods, which fit the HTTP paradigm.  Of course you will need to
  +write a client that understands that protocol extension.  For a good
  +example, refer to the C<MyApache::SendEmail> example presented in
  +C<L<the PerlHeaderParserHandler
  +section|docs::2.0::user::handlers::http/PerlHeaderParserHandler>>,
  +which demonstrates how a new method C<EMAIL> is registered and used.
  +
  +
  +
  +
  +
  +
  +
  +
   =head2 C<psignature>
   
   META: Autogenerated - needs to be reviewed/completed
  @@ -494,6 +563,23 @@
   
   
   
  +=head2 C<server_root>
  +
  +returns the value set by the top-level C<ServerRoot> directive.
  +
  +  $server_root = Apache::ServerUtil::server_root();
  +
  +=over 4
  +
  +=item ret: C<$server_root> ( string )
  +
  +=item since: 1.99_10
  +
  +=back
  +
  +
  +
  +
   
   
   
  @@ -530,7 +616,8 @@
   with a trailing C</>. (it's the same as using C<''> as C<$fname>'s
   value).
   
  -Also see the C<L<Apache::server_root|/C_Apache__server_root_>>
  +Also see the
  +C<L<Apache::ServerUtil::server_root|/C_Apache__server_root_>>
   constant.
   
   
  
  
  
  1.65      +9 -6      modperl-docs/src/docs/2.0/user/config/config.pod
  
  Index: config.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/config/config.pod,v
  retrieving revision 1.64
  retrieving revision 1.65
  diff -u -u -r1.64 -r1.65
  --- config.pod	12 Jul 2004 23:13:22 -0000	1.64
  +++ config.pod	15 Jul 2004 20:51:08 -0000	1.65
  @@ -1209,11 +1209,12 @@
     </IfDefine>
   
   If you need to access any of the startup defines in the Perl code you
  -use C<Apache::exists_config_define>. For example in a startup file you
  -can say:
  +use
  +C<L<Apache::ServerUtil::exists_config_define()|docs::2.0::Apache::ServerUtil/C_exists_config_define_>>.
For
  +example in a startup file you can say:
   
     use Apache::ServerUtil ();
  -  if (Apache::exists_config_define("PERLDB")) {
  +  if (Apache::ServerUtil::exists_config_define("PERLDB")) {
         require Apache::DB;
         Apache::DB->init;
     }
  @@ -1221,7 +1222,7 @@
   For example to check whether the server has been started in a single
   mode use:
   
  -  if (Apache::exists_config_define("ONE_PROCESS")) {
  +  if (Apache::ServerUtil::exists_config_define("ONE_PROCESS")) {
         print "Running in a single mode";
     }
   
  @@ -1241,9 +1242,11 @@
     </IfDefine>
   
   From within Perl code this can be tested with
  -C<Apache::exists_config_define()>, for example:
  +C<L<Apache::ServerUtil::exists_config_define()|docs::2.0::Apache::ServerUtil/C_exists_config_define_>>,
  +for example:
   
  -  if (Apache::exists_config_define("MODPERL2")) {
  +  use Apache::ServerUtil ();
  +  if (Apache::ServerUtil::exists_config_define("MODPERL2")) {
         # some 2.0 specific code
     }
   
  
  
  
  1.41      +2 -2      modperl-docs/src/docs/2.0/user/handlers/http.pod
  
  Index: http.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/http.pod,v
  retrieving revision 1.40
  retrieving revision 1.41
  diff -u -u -r1.40 -r1.41
  --- http.pod	12 Jul 2004 23:13:22 -0000	1.40
  +++ http.pod	15 Jul 2004 20:51:08 -0000	1.41
  @@ -444,6 +444,7 @@
     use Apache::RequestRec ();
     use Apache::RequestIO ();
     use Apache::RequestUtil ();
  +  use Apache::ServerUtil ();
     use Apache::ServerRec ();
     use Apache::Process ();
     use APR::Table ();
  @@ -458,8 +459,7 @@
     
         return Apache::DECLINED unless $r->method eq METHOD;
     
  -      Apache::RequestUtil::method_register($r->server->process->pconf,
  -                                           METHOD);
  +      $r->server->method_register(METHOD);
         $r->handler("perl-script");
         $r->push_handlers(PerlResponseHandler => \&send_email_handler);
     
  
  
  
  1.17      +4 -0      modperl-docs/src/docs/2.0/user/handlers/server.pod
  
  Index: server.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/server.pod,v
  retrieving revision 1.16
  retrieving revision 1.17
  diff -u -u -r1.16 -r1.17
  --- server.pod	12 Jul 2004 23:13:22 -0000	1.16
  +++ server.pod	15 Jul 2004 20:51:08 -0000	1.17
  @@ -347,6 +347,10 @@
   C<L<PerlOpenLogsHandler|/PerlOpenLogsHandler>> identically applies to
   this handler.
   
  +The
  +C<L<add_version_component()|docs::2.0::api::Apache::ServerUtil/C_add_version_component_>>
  +includes another useful example.
  +
   
   
   
  
  
  
  1.57      +6 -6      modperl-docs/src/docs/2.0/user/porting/compat.pod
  
  Index: compat.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/porting/compat.pod,v
  retrieving revision 1.56
  retrieving revision 1.57
  diff -u -u -r1.56 -r1.57
  --- compat.pod	13 Jul 2004 03:59:46 -0000	1.56
  +++ compat.pod	15 Jul 2004 20:51:09 -0000	1.57
  @@ -417,7 +417,9 @@
   
   C<Apache::Constants::SERVER_VERSION()> has been replaced with:
   
  -  Apache::get_server_version();
  +  Apache::ServerUtil::get_server_version();
  +
  +
   
   =head2 C<export()>
   
  @@ -577,12 +579,10 @@
   =head2 C<Apache-E<gt>define>
   
   C<Apache-E<gt>define> has been replaced with
  -C<Apache::exists_config_define()> residing inside
  -C<Apache::ServerUtil>.
  +C<L<Apache::ServerUtil::exists_config_define()|docs::2.0::Apache::ServerUtil/C_exists_config_define_>>.
  +
  +
   
  -See the
  -C<L<Apache::ServerUtil|docs::2.0::api::Apache::ServerUtil>>
  -manpage.
   
   =head2 C<Apache-E<gt>can_stack_handlers>
   
  
  
  

---------------------------------------------------------------------
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