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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
