The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Apache-BabyConnect-0.93
River stage zero No dependents
++
/ Apache::BabyConnect

NAME

Apache::BabyConnect - uses DBI::BabyConnect to initiate persistent database connections

SYNOPSIS

 # Configuration in perl.conf and babystartup.pl:

 PerlSetEnv BABYCONNECT /opt/DBI-BabyConnect/configuration
 PerlRequire /opt/Apache-BabyConnect/startupscripts/babystartup.pl

DESCRIPTION

This module initiates persistent database connections using DBI::BabyConnect.

This module is best understood by going through the roadmap file and the sample programs provided with this distribution. The roadmap file is eg/README, and the sample programs are in eg/perl.

When loading the Apache::BabyConnect module, the module looks if the environment variable BABYCONNECT has been set to the URI location where it can read the configuration files, and if the the module DBI::BabyConnect has been loaded. The startup script instantiates DBI::BabyConnect objects with caching and persistence enabled. Each object is connected to a data source that is described by the database descriptor. See DBI::BabyConnect for a clarification of database descriptors.

If you create a DBI::BabyConnect object from a Perl script, then if the descriptor is found in the DBI::BabyConnect cache, you will be using the cached object. Otherwise, a new DBI::BabyConnect is created with that descriptor, and it is added to the cache.

Any Perl script can use DBI::BabyConnect to create as many DBI::BabyConnect objects; however, DBI::BabyConnect will only create a new object if not found in the cache. Programmers do not need to keep track of what is being cached, and they can write code as if the script is to be run from the command prompt.

It is recommended that you use a set of prefedined database descriptors that you load at the startup of Apache. See babystartup.pl script later in this document. However, you can always use a new database descriptor to create a DBI::BabyObject.

Unlike the Apache::DBI module, there is no request forwarding between the DBI module and the Apache::BabyConnect. All caching is handled by the DBI::BabyConnect. Do not load the Apache::DBI module whenever you are using Apache::BabyConnect, otherwise you will imply a penalty on the caching mechanism, and you will be limited to the caching mechanism of Apache::DBI.

The Apache::BabyConnect module does not have the same limitation as Apache::DBI. DBI::BabyConnect objects are persisted on per process basis, and a user can access several times a database from different http servers. The Apache::BabyConnect objects will never share the same handle. Each Apache::BabyConnect object contains its own handle, and DBI::db handle are never cached or shared. For this reason you should not load the Apache::DBI module.

Caching of the Apache::BabyConnect is maintained within the DBI::BabyConnect module itself, and each entry in the cache is uniquely identified by the concatenation of: the kernel process number of the http server + the database descriptor.

GETTING STARTED

The Apache::BabyConnect distribution comes with a startup script ("babystartup.pl"), a roadmap for installation and testing in eg/README file, and a set of sample programs to assist you in testing your installation.

 The directory startupscripts/ contains the file startupscripts/babystartup.pl
 The directory eg/ contains the roadmap file eg/README
 The directory eg/perl contains the sample scripts

Using mod_perl, modify your perl.conf as follow:

 PerlSetEnv BABYCONNECT /opt/DBI-BabyConnect/configuration
 PerlRequire /opt/Apache-BabyConnect-0.93/startupscripts/babystartup.pl

 Alias /perl /var/www/perl
 <Directory /var/www/perl>
     SetHandler perl-script
     PerlResponseHandler ModPerl::Registry
     PerlOptions +ParseHeaders
     Options +ExecCGI
 </Directory>

You will then copy the sample scripts from eg/perl to /var/www/perl. Restart the http server and test with the scripts. For more instruction refer to eg/README.

CONFIGURATION

Before loading the module, you need to setup the BABYCONNECT environment variable to point to the DBI::BabyConnect configuration directory. After, setting the environment variable BABYCONNECT, you should load the Apache::BabyConnect upon startup of the Apache daemon.

Add the following line to your perl.conf:

 PerlSetEnv BABYCONNECT /p9/BABYCONNECT/DBI-BabyConnect/configuration
 PerlRequire /p9/BABYCONNECT/Apache-BabyConnect/startupscripts/babystartup.pl

Write a startup script to be loaded via the PerlRequire directive. For an example, see the "babystartup.pl".

NOTE: You do not need to load the Apache::DBI module.

connect_on_init

To achieve a persistent connection upon http server startup, you will call the method connect_on_init:

 Apache::BabyConnect->connect_on_init(
    DESCRIPTOR => datasource_descriptor,
    ERROR_FILE => error_log,
    TRACE_FILE => trace_log,
    TRACE_LEVEL => trace_level,
 );

Here is an example:

 Apache::BabyConnect->connect_on_init(
    DESCRIPTOR =>'BABYDB_001',
    ERROR_FILE => '/var/www/htdocs/logs/error_BABYDB_001.log',
    TRACE_FILE => '/var/www/htdocs/logs/db_BABYDB_001.log',
    TRACE_LEVEL => 2
 );

connect_on_init() takes a hash with a DESCRIPTOR attribute that is mandatory, followed by three optional attributes ERROR_FILE, TRACE_FILE, and TRACE_LEVEL, that are optional.

The DESCRIPTOR specifies the database descriptor to be persisted by the http server. Apache::BabyConnect will instantiate an DBI::BabyConnect object with connection persistence and caching for such an object.

The ERROR_FILE attribute is optional and it is the file name where STDERR will be redirected. See the note "IMPORTANT REMARK" about the effect of redirecting STDERR during startup.

The TRACE_FILE attribute is optional and it is the file name where all tracing will be written.

The TRACE_LEVEL attribute is optional and it is the DBI trace level to be written to the trace file specified in the previous argument.

babystartup.pl

  use strict;
  
  $ENV{MOD_PERL} or die "not running under mod_perl!";
  
  # Set up the ENV for BABYCONNECT in the perl.conf just before requiring the babystartup.pl as follow:
  #   PerlSetEnv BABYCONNECT /opt/DBI-BabyConnect/configuration
  #   PerlRequire /opt/Apache-BabyConnect/startupscripts/babystartup.pl
  #
  # alternatively you can uncomment the line below:
  #BEGIN { $ENV{BABYCONNECT} = '/opt/DBI-BabyConnect/configuration'; }
  
  use ModPerl::Registry ();
  use LWP::UserAgent ();
  
  use Apache::BabyConnect ();
  
  use Carp ();
  $SIG{__WARN__} = \&Carp::cluck;
  
  $Apache::BabyConnect::DEBUG = 2;
  
  #ATTENTION: this is only a sample example to test with Apache::BabyConnect,
  #  in production environment, do not enable logging and tracing. To do so
  #  just call connect_on_init() with the database descriptor only. For example:
  #Apache::BabyConnect->connect_on_init(DESCRIPTOR=>'BABYDB_001');
  
  Apache::BabyConnect->connect_on_init(
      DESCRIPTOR =>'BABYDB_001',
      ERROR_FILE => '/var/www/htdocs/logs/error_BABYDB_001.log',
      TRACE_FILE => '/var/www/htdocs/logs/db_BABYDB_001.log',
      TRACE_LEVEL => 2
  );

  Apache::BabyConnect->connect_on_init(
      DESCRIPTOR =>'BABYDB_002',
      ERROR_FILE => '/var/www/htdocs/logs/error_BABYDB_002.log',
      TRACE_FILE => '/var/www/htdocs/logs/db_BABYDB_002.log',
      TRACE_LEVEL => 2
  );

  Apache::BabyConnect->connect_on_init(
      DESCRIPTOR => 'BABYDB_003',
      ERROR_FILE => '/var/www/htdocs/logs/error_BABYDB_003.log',
      TRACE_FILE => '/var/www/htdocs/logs/db_BABYDB_003.log',
      TRACE_LEVEL => 2
  );

  Apache::BabyConnect->connect_on_init(
      DESCRIPTOR => 'BABYDB_004',
      ERROR_FILE => '/var/www/htdocs/logs/error_BABYDB_004.log',
      TRACE_FILE => '/var/www/htdocs/logs/db_BABYDB_004.log',
      TRACE_LEVEL => 2
  );
  
  1;

IMPORTANT REMARK

The redirection of STDERR during the startup of Apache may result in confusing messages printed to Apache error_log. If you specify the attribute ERROR_FILE during startup, and you enable debugging $Apache::BabyConnect::DEBUG = 2;, as shown in the script above, the messages printed to Apache error_log, and to the error log for each of the descriptor will be intermixed and out of order. This may result in confusion when the administrator is configuring Apache::BabyConnect.

If you want to view the startup properly, in the startup script "babystartup.pl" comment out all the lines where ERROR_FILE attribute is specified. Restart the server and view the error_log.

PREREQUISITES

MOD_PERL 2.0

Apache::DBI version 0.96 and higher should work under mod_perl 2.0 RC5 and later with httpd 2.0.49 and later.

MOD_PERL 1.0

Note that this module needs mod_perl-1.08 or higher, apache_1.3.0.

SEE ALSO

DBI::BabyConnect

AUTHORS

Bassem W. Jamaleddine is the author of Apache::BabyConnect.

COPYRIGHT

The Apache::BabyConnect module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.