[Summary view] [Print] [Text view]

   1  package DBD::Gofer::Policy::Base;
   2  
   3  #   $Id: Base.pm 10087 2007-10-16 12:42:37Z timbo $
   4  #
   5  #   Copyright (c) 2007, Tim Bunce, Ireland
   6  #
   7  #   You may distribute under the terms of either the GNU General Public
   8  #   License or the Artistic License, as specified in the Perl README file.
   9  
  10  use strict;
  11  use warnings;
  12  use Carp;
  13  
  14  our $VERSION = sprintf("0.%06d", q$Revision: 10087 $ =~ /(\d+)/o);
  15  our $AUTOLOAD;
  16  
  17  my %policy_defaults = (
  18      # force connect method (unless overridden by go_connect_method=>'...' attribute)
  19      # if false: call same method on client as on server
  20      connect_method => 'connect',
  21      # force prepare method (unless overridden by go_prepare_method=>'...' attribute)
  22      # if false: call same method on client as on server
  23      prepare_method => 'prepare',
  24      skip_connect_check => 0,
  25      skip_default_methods => 0,
  26      skip_prepare_check => 0,
  27      skip_ping => 0,
  28      dbh_attribute_update => 'every',
  29      dbh_attribute_list => ['*'],
  30      locally_quote => 0,
  31      locally_quote_identifier => 0,
  32      cache_parse_trace_flags => 1,
  33      cache_parse_trace_flag => 1,
  34      cache_data_sources => 1,
  35      cache_type_info_all => 1,
  36      cache_tables => 0,
  37      cache_table_info => 0,
  38      cache_column_info => 0,
  39      cache_primary_key_info => 0,
  40      cache_foreign_key_info => 0,
  41      cache_statistics_info => 0,
  42      cache_get_info => 0,
  43      cache_func => 0,
  44  );
  45  
  46  my $base_policy_file = $INC{"DBD/Gofer/Policy/Base.pm"};
  47  
  48  __PACKAGE__->create_policy_subs(\%policy_defaults);
  49  
  50  sub create_policy_subs {
  51      my ($class, $policy_defaults) = @_;
  52  
  53      while ( my ($policy_name, $policy_default) = each %$policy_defaults) { 
  54          my $policy_attr_name = "go_$policy_name";
  55          my $sub = sub {
  56              # $policy->foo($attr, ...)
  57              #carp "$policy_name($_[1],...)";
  58              # return the policy default value unless an attribute overrides it
  59              return (ref $_[1] && exists $_[1]->{$policy_attr_name})
  60                  ? $_[1]->{$policy_attr_name}
  61                  : $policy_default;
  62          };
  63          no strict 'refs';
  64          *{$class . '::' . $policy_name} = $sub;
  65      }
  66  }
  67  
  68  sub AUTOLOAD {
  69      carp "Unknown policy name $AUTOLOAD used";
  70      # only warn once
  71      no strict 'refs';
  72      *$AUTOLOAD = sub { undef };
  73      return undef;
  74  }
  75  
  76  sub new {
  77      my ($class, $args) = @_;
  78      my $policy = {};
  79      bless $policy, $class;
  80  }
  81  
  82  sub DESTROY { };
  83  
  84  1;
  85  
  86  =head1 NAME
  87  
  88  DBD::Gofer::Policy::Base - Base class for DBD::Gofer policies
  89  
  90  =head1 SYNOPSIS
  91  
  92    $dbh = DBI->connect("dbi:Gofer:transport=...;policy=...", ...)
  93  
  94  =head1 DESCRIPTION
  95  
  96  DBD::Gofer can be configured via a 'policy' mechanism that allows you to
  97  fine-tune the number of round-trips to the Gofer server.  The policies are
  98  grouped into classes (which may be subclassed) and referenced by the name of
  99  the class.
 100  
 101  The L<DBD::Gofer::Policy::Base> class is the base class for all the policy
 102  classes and describes all the individual policy items.
 103  
 104  The Base policy is not used directly. You should use a policy class derived from it.
 105  
 106  =head1 POLICY CLASSES
 107  
 108  Three policy classes are supplied with DBD::Gofer:
 109      
 110  L<DBD::Gofer::Policy::pedantic> is most 'transparent' but slowest because it
 111  makes more  round-trips to the Gofer server.
 112  
 113  L<DBD::Gofer::Policy::classic> is a reasonable compromise - it's the default policy.
 114      
 115  L<DBD::Gofer::Policy::rush> is fastest, but may require code changes in your applications.
 116  
 117  Generally the default C<classic> policy is fine. When first testing an existing
 118  application with Gofer it is a good idea to start with the C<pedantic> policy
 119  first and then switch to C<classic> or a custom policy, for final testing.
 120  
 121  =head1 POLICY ITEMS
 122  
 123  These are temporary docs: See the source code for list of policies and their defaults.
 124  
 125  In a future version the policies and their defaults will be defined in the pod and parsed out at load-time.
 126  
 127  See the source code to this module for more details.
 128  
 129  =head1 POLICY CUSTOMIZATION
 130  
 131  XXX This area of DBD::Gofer is subject to change.
 132  
 133  There are three ways to customize policies:
 134  
 135  Policy classes are designed to influence the overall behaviour of DBD::Gofer
 136  with existing, unaltered programs, so they work in a reasonably optimal way
 137  without requiring code changes. You can implement new policy classes as
 138  subclasses of existing policies.
 139  
 140  In many cases individual policy items can be overridden on a case-by-case basis
 141  within your application code. You do this by passing a corresponding
 142  C<<go_<policy_name>>> attribute into DBI methods by your application code.
 143  This let's you fine-tune the behaviour for special cases.
 144  
 145  The policy items are implemented as methods. In many cases the methods are
 146  passed parameters relating to the DBD::Gofer code being executed. This means
 147  the policy can implement dynamic behaviour that varies depending on the
 148  particular circumstances, such as the particular statement being executed.
 149  
 150  =head1 AUTHOR
 151  
 152  Tim Bunce, L<http://www.tim.bunce.name>
 153  
 154  =head1 LICENCE AND COPYRIGHT
 155  
 156  Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.
 157  
 158  This module is free software; you can redistribute it and/or
 159  modify it under the same terms as Perl itself. See L<perlartistic>.
 160  
 161  =cut
 162