4 files changed, 384 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/Base.pm b/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/Base.pm
new file mode 100755
index 00000000000..1725b0316ad
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/Base.pm
@@ -0,0 +1,162 @@
+package DBD::Gofer::Policy::Base;
+
+#   $Id: Base.pm 10087 2007-10-16 12:42:37Z timbo $
+#
+#   Copyright (c) 2007, Tim Bunce, Ireland
+#
+#   You may distribute under the terms of either the GNU General Public
+#   License or the Artistic License, as specified in the Perl README file.
+
+use strict;
+use warnings;
+use Carp;
+
+our $VERSION = sprintf("0.%06d", q$Revision: 10087 $ =~ /(\d+)/o);
+our $AUTOLOAD;
+
+my %policy_defaults = (
+    # force connect method (unless overridden by go_connect_method=>'...' attribute)
+    # if false: call same method on client as on server
+    connect_method => 'connect',
+    # force prepare method (unless overridden by go_prepare_method=>'...' attribute)
+    # if false: call same method on client as on server
+    prepare_method => 'prepare',
+    skip_connect_check => 0,
+    skip_default_methods => 0,
+    skip_prepare_check => 0,
+    skip_ping => 0,
+    dbh_attribute_update => 'every',
+    dbh_attribute_list => ['*'],
+    locally_quote => 0,
+    locally_quote_identifier => 0,
+    cache_parse_trace_flags => 1,
+    cache_parse_trace_flag => 1,
+    cache_data_sources => 1,
+    cache_type_info_all => 1,
+    cache_tables => 0,
+    cache_table_info => 0,
+    cache_column_info => 0,
+    cache_primary_key_info => 0,
+    cache_foreign_key_info => 0,
+    cache_statistics_info => 0,
+    cache_get_info => 0,
+    cache_func => 0,
+);
+
+my $base_policy_file = $INC{"DBD/Gofer/Policy/Base.pm"};
+
+__PACKAGE__->create_policy_subs(\%policy_defaults);
+
+sub create_policy_subs {
+    my ($class, $policy_defaults) = @_;
+
+    while ( my ($policy_name, $policy_default) = each %$policy_defaults) { 
+        my $policy_attr_name = "go_$policy_name";
+        my $sub = sub {
+            # $policy->foo($attr, ...)
+            #carp "$policy_name($_[1],...)";
+            # return the policy default value unless an attribute overrides it
+            return (ref $_[1] && exists $_[1]->{$policy_attr_name})
+                ? $_[1]->{$policy_attr_name}
+                : $policy_default;
+        };
+        no strict 'refs';
+        *{$class . '::' . $policy_name} = $sub;
+    }
+}
+
+sub AUTOLOAD {
+    carp "Unknown policy name $AUTOLOAD used";
+    # only warn once
+    no strict 'refs';
+    *$AUTOLOAD = sub { undef };
+    return undef;
+}
+
+sub new {
+    my ($class, $args) = @_;
+    my $policy = {};
+    bless $policy, $class;
+}
+
+sub DESTROY { };
+
+1;
+
+=head1 NAME
+
+DBD::Gofer::Policy::Base - Base class for DBD::Gofer policies
+
+=head1 SYNOPSIS
+
+  $dbh = DBI->connect("dbi:Gofer:transport=...;policy=...", ...)
+
+=head1 DESCRIPTION
+
+DBD::Gofer can be configured via a 'policy' mechanism that allows you to
+fine-tune the number of round-trips to the Gofer server.  The policies are
+grouped into classes (which may be subclassed) and referenced by the name of
+the class.
+
+The L<DBD::Gofer::Policy::Base> class is the base class for all the policy
+classes and describes all the individual policy items.
+
+The Base policy is not used directly. You should use a policy class derived from it.
+
+=head1 POLICY CLASSES
+
+Three policy classes are supplied with DBD::Gofer:
+    
+L<DBD::Gofer::Policy::pedantic> is most 'transparent' but slowest because it
+makes more  round-trips to the Gofer server.
+
+L<DBD::Gofer::Policy::classic> is a reasonable compromise - it's the default policy.
+    
+L<DBD::Gofer::Policy::rush> is fastest, but may require code changes in your applications.
+
+Generally the default C<classic> policy is fine. When first testing an existing
+application with Gofer it is a good idea to start with the C<pedantic> policy
+first and then switch to C<classic> or a custom policy, for final testing.
+
+=head1 POLICY ITEMS
+
+These are temporary docs: See the source code for list of policies and their defaults.
+
+In a future version the policies and their defaults will be defined in the pod and parsed out at load-time.
+
+See the source code to this module for more details.
+
+=head1 POLICY CUSTOMIZATION
+
+XXX This area of DBD::Gofer is subject to change.
+
+There are three ways to customize policies:
+
+Policy classes are designed to influence the overall behaviour of DBD::Gofer
+with existing, unaltered programs, so they work in a reasonably optimal way
+without requiring code changes. You can implement new policy classes as
+subclasses of existing policies.
+
+In many cases individual policy items can be overridden on a case-by-case basis
+within your application code. You do this by passing a corresponding
+C<<go_<policy_name>>> attribute into DBI methods by your application code.
+This let's you fine-tune the behaviour for special cases.
+
+The policy items are implemented as methods. In many cases the methods are
+passed parameters relating to the DBD::Gofer code being executed. This means
+the policy can implement dynamic behaviour that varies depending on the
+particular circumstances, such as the particular statement being executed.
+
+=head1 AUTHOR
+
+Tim Bunce, L<http://www.tim.bunce.name>
+
+=head1 LICENCE AND COPYRIGHT
+
+Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.
+
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself. See L<perlartistic>.
+
+=cut
+
diff --git a/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/classic.pm b/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/classic.pm
new file mode 100755
index 00000000000..8f828f0ddba
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/classic.pm
@@ -0,0 +1,79 @@
+package DBD::Gofer::Policy::classic;
+
+#   $Id: classic.pm 10087 2007-10-16 12:42:37Z timbo $
+#
+#   Copyright (c) 2007, Tim Bunce, Ireland
+#
+#   You may distribute under the terms of either the GNU General Public
+#   License or the Artistic License, as specified in the Perl README file.
+
+use strict;
+use warnings;
+
+our $VERSION = sprintf("0.%06d", q$Revision: 10087 $ =~ /(\d+)/o);
+
+use base qw(DBD::Gofer::Policy::Base);
+
+__PACKAGE__->create_policy_subs({
+
+    # always use connect_cached on server
+    connect_method => 'connect_cached',
+
+    # use same methods on server as is called on client
+    prepare_method => '',
+
+    # don't skip the connect check since that also sets dbh attributes
+    # although this makes connect more expensive, that's partly offset
+    # by skip_ping=>1 below, which makes connect_cached very fast.
+    skip_connect_check => 0,
+
+    # most code doesn't rely on sth attributes being set after prepare
+    skip_prepare_check => 1,
+
+    # we're happy to use local method if that's the same as the remote
+    skip_default_methods => 1,
+
+    # ping is not important for DBD::Gofer and most transports
+    skip_ping => 1,
+
+    # only update dbh attributes on first contact with server
+    dbh_attribute_update => 'first',
+
+    # we'd like to set locally_* but can't because drivers differ
+
+    # get_info results usually don't change
+    cache_get_info => 1,
+});
+
+
+1;
+
+=head1 NAME
+
+DBD::Gofer::Policy::classic - The 'classic' policy for DBD::Gofer
+
+=head1 SYNOPSIS
+
+  $dbh = DBI->connect("dbi:Gofer:transport=...;policy=classic", ...)
+
+The C<classic> policy is the default DBD::Gofer policy, so need not be included in the DSN.
+
+=head1 DESCRIPTION
+
+Temporary docs: See the source code for list of policies and their defaults.
+
+In a future version the policies and their defaults will be defined in the pod and parsed out at load-time.
+
+=head1 AUTHOR
+
+Tim Bunce, L<http://www.tim.bunce.name>
+
+=head1 LICENCE AND COPYRIGHT
+
+Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.
+
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself. See L<perlartistic>.
+
+=cut
+
diff --git a/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/pedantic.pm b/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/pedantic.pm
new file mode 100755
index 00000000000..6829beafe3d
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/pedantic.pm
@@ -0,0 +1,53 @@
+package DBD::Gofer::Policy::pedantic;
+
+#   $Id: pedantic.pm 10087 2007-10-16 12:42:37Z timbo $
+#
+#   Copyright (c) 2007, Tim Bunce, Ireland
+#
+#   You may distribute under the terms of either the GNU General Public
+#   License or the Artistic License, as specified in the Perl README file.
+
+use strict;
+use warnings;
+
+our $VERSION = sprintf("0.%06d", q$Revision: 10087 $ =~ /(\d+)/o);
+
+use base qw(DBD::Gofer::Policy::Base);
+
+# the 'pedantic' policy is the same as the Base policy
+
+1;
+
+=head1 NAME
+
+DBD::Gofer::Policy::pedantic - The 'pedantic' policy for DBD::Gofer
+
+=head1 SYNOPSIS
+
+  $dbh = DBI->connect("dbi:Gofer:transport=...;policy=pedantic", ...)
+
+=head1 DESCRIPTION
+
+The C<pedantic> policy tries to be as transparent as possible. To do this it
+makes round-trips to the server for almost every DBI method call.
+
+This is the best policy to use when first testing existing code with Gofer.
+Once it's working well you should consider moving to the C<classic> policy or defining your own policy class.
+
+Temporary docs: See the source code for list of policies and their defaults.
+
+In a future version the policies and their defaults will be defined in the pod and parsed out at load-time.
+
+=head1 AUTHOR
+
+Tim Bunce, L<http://www.tim.bunce.name>
+
+=head1 LICENCE AND COPYRIGHT
+
+Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.
+
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself. See L<perlartistic>.
+
+=cut
+
diff --git a/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/rush.pm b/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/rush.pm
new file mode 100755
index 00000000000..9cfd5826829
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/DBD/Gofer/Policy/rush.pm
@@ -0,0 +1,90 @@
+package DBD::Gofer::Policy::rush;
+
+#   $Id: rush.pm 10087 2007-10-16 12:42:37Z timbo $
+#
+#   Copyright (c) 2007, Tim Bunce, Ireland
+#
+#   You may distribute under the terms of either the GNU General Public
+#   License or the Artistic License, as specified in the Perl README file.
+
+use strict;
+use warnings;
+
+our $VERSION = sprintf("0.%06d", q$Revision: 10087 $ =~ /(\d+)/o);
+
+use base qw(DBD::Gofer::Policy::Base);
+
+__PACKAGE__->create_policy_subs({
+
+    # always use connect_cached on server
+    connect_method => 'connect_cached',
+
+    # use same methods on server as is called on client
+    # (because code not using placeholders would bloat the sth cache)
+    prepare_method => '',
+
+    # Skipping the connect check is fast, but it also skips
+    # fetching the remote dbh attributes!
+    # Make sure that your application doesn't need access to dbh attributes.
+    skip_connect_check => 1,
+
+    # most code doesn't rely on sth attributes being set after prepare
+    skip_prepare_check => 1,
+
+    # we're happy to use local method if that's the same as the remote
+    skip_default_methods => 1,
+
+    # ping is almost meaningless for DBD::Gofer and most transports anyway
+    skip_ping => 1,
+
+    # don't update dbh attributes at all
+    # XXX actually we currently need dbh_attribute_update for skip_default_methods to work
+    # and skip_default_methods is more valuable to us than the cost of dbh_attribute_update
+    dbh_attribute_update => 'none', # actually means 'first' currently
+    #dbh_attribute_list => undef,
+
+    # we'd like to set locally_* but can't because drivers differ
+
+    # in a rush assume metadata doesn't change
+    cache_tables => 1,
+    cache_table_info => 1,
+    cache_column_info => 1,
+    cache_primary_key_info => 1,
+    cache_foreign_key_info => 1,
+    cache_statistics_info => 1,
+    cache_get_info => 1,
+});
+
+
+1;
+
+=head1 NAME
+
+DBD::Gofer::Policy::rush - The 'rush' policy for DBD::Gofer
+
+=head1 SYNOPSIS
+
+  $dbh = DBI->connect("dbi:Gofer:transport=...;policy=rush", ...)
+
+=head1 DESCRIPTION
+
+The C<rush> policy tries to make as few round-trips as possible.
+It's the opposite end of the policy spectrum to the C<pedantic> policy.
+
+Temporary docs: See the source code for list of policies and their defaults.
+
+In a future version the policies and their defaults will be defined in the pod and parsed out at load-time.
+
+=head1 AUTHOR
+
+Tim Bunce, L<http://www.tim.bunce.name>
+
+=head1 LICENCE AND COPYRIGHT
+
+Copyright (c) 2007, Tim Bunce, Ireland. All rights reserved.
+
+This module is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself. See L<perlartistic>.
+
+=cut
+