| 1 | package Class::Proxy::Lite; | ||||||||||||||||||||||||||||
| 2 | |||||||||||||||||||||||||||||
| 3 | 3 | ▶ | use strict; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 4 | 3 | ▶ | use vars qw($VERSION); | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 5 | |||||||||||||||||||||||||||||
| 6 | 3 | $VERSION = '1.01'; | |||||||||||||||||||||||||||
| 7 | |||||||||||||||||||||||||||||
| 8 | 3 | ▶ | use constant TOKEN => 0; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 9 | 3 | ▶ | use constant RESOLVER => 1; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 10 | 3 | ▶ | use constant CACHED => 2; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 11 | |||||||||||||||||||||||||||||
| 12 | 8 | ▶ | sub AUTOLOAD { | ||||||||||||||||||||||||||
|
Subroutine
AUTOLOAD: called CC=15 SCAR=31.9
| |||||||||||||||||||||||||||||
| 13 | 8 | my $self_or_class = shift(); | |||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||
| 15 | 8 | (my $method = $Class::Proxy::Lite::AUTOLOAD) =~ s/(.*):://; | |||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||
| 17 | 8 | my $is_class_method = ref($self_or_class) eq ''; | |||||||||||||||||||||||||||
| 18 | |||||||||||||||||||||||||||||
| 19 | # --- Check for special cases and non-references | ||||||||||||||||||||||||||||
| 20 | 8 | ▶ | return undef if $method eq 'DESTROY'; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 21 | 6 | ▶ | return undef if $method eq 'import' and $is_class_method; | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$method eq "import" and $is_class_method
MC/DC0%0/2
$method eq "import" and $is_class_method
$method eq "import"
$is_class_method
Truth table33%1/3
A and B
A= $method eq "import"B= $is_class_method
| |||||||||||||||||||||||||||||
| 22 | |||||||||||||||||||||||||||||
| 23 | # --- XXX Try to deal with can and isa? | ||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||
| 25 | # --- Emulate class method new() | ||||||||||||||||||||||||||||
| 26 | 6 | ▶ | if ($is_class_method) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 27 | 2 | ▶ | die "Can't call a class method on Class::Proxy::Lite or a subclass" | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$method eq "new" and UNIVERSAL::isa($self_or_class, __PACKAGE__)
MC/DC0%0/2
$method eq "new" and UNIVERSAL::isa($self_or_class, __PACKAGE__)
$method eq "new"
UNIVERSAL::isa($self_or_class, __PACKAGE__)
Truth table33%1/3
A and B
A= $method eq "new"B= UNIVERSAL::isa($self_or_class, __PACKAGE__)
| |||||||||||||||||||||||||||||
| 28 | unless $method eq 'new' | ||||||||||||||||||||||||||||
| 29 | and UNIVERSAL::isa($self_or_class, __PACKAGE__); | ||||||||||||||||||||||||||||
| 30 | # --- Create a proxy | ||||||||||||||||||||||||||||
| 31 | 2 | my ($token, $resolver, $cached) = @_; | |||||||||||||||||||||||||||
| 32 | 2 | my @self; | |||||||||||||||||||||||||||
| 33 | 2 | $self[TOKEN] = $token; | |||||||||||||||||||||||||||
| 34 | 2 | $self[RESOLVER] = $resolver; | |||||||||||||||||||||||||||
| 35 | 2 | ▶ | $self[CACHED] = $cached if defined $cached; | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 36 | 2 | return bless \@self, $self_or_class; | |||||||||||||||||||||||||||
| 37 | } | ||||||||||||||||||||||||||||
| 38 | |||||||||||||||||||||||||||||
| 39 | # --- Reject attempts to call functions in Class::Proxy::Lite | ||||||||||||||||||||||||||||
| 40 | 4 | ▶ | die "No such function: $Class::Proxy::Lite::AUTOLOAD" | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
$is_class_method and $self_or_class ne "Class::Proxy::Lite"
MC/DC0%0/2
$is_class_method and $self_or_class ne "Class::Proxy::Lite"
$is_class_method
$self_or_class ne "Class::Proxy::Lite"
Truth table33%1/3
A and B
A= $is_class_methodB= $self_or_class ne "Class::Proxy::Lite"
| |||||||||||||||||||||||||||||
| 41 | if $is_class_method | ||||||||||||||||||||||||||||
| 42 | and $self_or_class ne 'Class::Proxy::Lite'; | ||||||||||||||||||||||||||||
| 43 | |||||||||||||||||||||||||||||
| 44 | # --- Resolve the token | ||||||||||||||||||||||||||||
| 45 | 4 | my ($token, $resolver, $cached) = @$self_or_class[TOKEN, RESOLVER, CACHED]; | |||||||||||||||||||||||||||
| 46 | 4 | my $target; | |||||||||||||||||||||||||||
| 47 | 4 | ▶ | if ($cached) { | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 48 | 0 | ▶ | $target = $$cached ||= $resolver->($token); | ||||||||||||||||||||||||||
|
Condition0%0/3
$$cached ||= &$resolver($token)
MC/DC0%0/2
$$cached ||= &$resolver($token)
$$cached
&$resolver($token)
Truth table0%0/3
A ||= B
A= $$cachedB= &$resolver($token)
| |||||||||||||||||||||||||||||
| 49 | } | ||||||||||||||||||||||||||||
| 50 | else { | ||||||||||||||||||||||||||||
| 51 | 4 | $target = $resolver->($token); | |||||||||||||||||||||||||||
| 52 | } | ||||||||||||||||||||||||||||
| 53 | 4 | ▶ | die "Couldn't resolve proxy target" | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition33%1/3
defined $target and ref $target
MC/DC0%0/2
defined $target and ref $target
defined $target
ref $target
Truth table33%1/3
A and B
A= defined $targetB= ref $target
| |||||||||||||||||||||||||||||
| 54 | unless defined $target and ref $target; | ||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||
| 56 | # --- These don't work -- see under `Default UNIVERSAL methods' | ||||||||||||||||||||||||||||
| 57 | # in perlobj for an explanation | ||||||||||||||||||||||||||||
| 58 | # return ref($target)->isa(shift) if $method eq 'isa'; | ||||||||||||||||||||||||||||
| 59 | # return ref($target)->can(shift) if $method eq 'can'; | ||||||||||||||||||||||||||||
| 60 | |||||||||||||||||||||||||||||
| 61 | # --- Invoke the method of the same name on the target object | ||||||||||||||||||||||||||||
| 62 | # goto &{UNIVERSAL::can($target, $method)} won't work, | ||||||||||||||||||||||||||||
| 63 | # because $target might rely upon its own AUTOLOAD!! | ||||||||||||||||||||||||||||
| 64 | 3 | ▶ | no strict 'refs'; | ||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||
| 65 | return wantarray | ||||||||||||||||||||||||||||
| 66 | 0 | ▶ | ? @{ [ $target->${method}(@_) ] } | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 67 | : $target->${method}(@_) | ||||||||||||||||||||||||||||
| 68 | ; | ||||||||||||||||||||||||||||
| 69 | } | ||||||||||||||||||||||||||||
| 70 | |||||||||||||||||||||||||||||
| 71 | |||||||||||||||||||||||||||||
| 72 | 3 | 1; | |||||||||||||||||||||||||||
| 73 | |||||||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||||||
| 75 | =head1 NAME | ||||||||||||||||||||||||||||
| 76 | |||||||||||||||||||||||||||||
| 77 | Class::Proxy::Lite - Simple, lightweight object proxies | ||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||
| 79 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||
| 80 | |||||||||||||||||||||||||||||
| 81 | # Make a proxy to a particular object | ||||||||||||||||||||||||||||
| 82 | $proxy = Class::Proxy::Lite->new($token, \&resolver); | ||||||||||||||||||||||||||||
| 83 | |||||||||||||||||||||||||||||
| 84 | # Make a caching proxy | ||||||||||||||||||||||||||||
| 85 | $proxy = Class::Proxy::Lite->new($token, \&resolver, \$cache); | ||||||||||||||||||||||||||||
| 86 | |||||||||||||||||||||||||||||
| 87 | # Methods invoked on the proxy are passed to the target object | ||||||||||||||||||||||||||||
| 88 | $proxy->foo(...); | ||||||||||||||||||||||||||||
| 89 | $proxy->bar(...); | ||||||||||||||||||||||||||||
| 90 | $proxy->etc(...); | ||||||||||||||||||||||||||||
| 91 | |||||||||||||||||||||||||||||
| 92 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||
| 93 | |||||||||||||||||||||||||||||
| 94 | Each instance of this class serves as a proxy to a target object. The proxy | ||||||||||||||||||||||||||||
| 95 | is constructed from a I<token> and a I<resolver>. The resolver is a code | ||||||||||||||||||||||||||||
| 96 | reference called with the token as its only argument; its job is to resolve | ||||||||||||||||||||||||||||
| 97 | the token into a reference to the desired target object. | ||||||||||||||||||||||||||||
| 98 | |||||||||||||||||||||||||||||
| 99 | The proxy doesn't hold a reference to its target; instead, the token must be | ||||||||||||||||||||||||||||
| 100 | resolved each time a method call is made on the proxy. | ||||||||||||||||||||||||||||
| 101 | |||||||||||||||||||||||||||||
| 102 | =head1 METHODS | ||||||||||||||||||||||||||||
| 103 | |||||||||||||||||||||||||||||
| 104 | =head2 new | ||||||||||||||||||||||||||||
| 105 | |||||||||||||||||||||||||||||
| 106 | $proxy = Class::Proxy::Lite->new($token, \&resolver); | ||||||||||||||||||||||||||||
| 107 | $proxy = Class::Proxy::Lite->new($token, \&resolver, \$cache); | ||||||||||||||||||||||||||||
| 108 | |||||||||||||||||||||||||||||
| 109 | Construct a proxy. The resolver is expected to return an object exactly | ||||||||||||||||||||||||||||
| 110 | equivalent (if not identical) to the desired target object. This constraint | ||||||||||||||||||||||||||||
| 111 | can't be formally enforced by this module, so your resolver must be written | ||||||||||||||||||||||||||||
| 112 | in such a way as to meet the constraint itself. | ||||||||||||||||||||||||||||
| 113 | |||||||||||||||||||||||||||||
| 114 | If you want one-time resolution, you may pass a reference to an undefined scalar | ||||||||||||||||||||||||||||
| 115 | variable as a third argument to the C<new> method; this will be used to cache | ||||||||||||||||||||||||||||
| 116 | the target object the first time it's resolved, and as a result the target | ||||||||||||||||||||||||||||
| 117 | object won't need to be resolved again. Or you might pass a reference to a tied | ||||||||||||||||||||||||||||
| 118 | variable that implements caching with some sort of expiry. | ||||||||||||||||||||||||||||
| 119 | |||||||||||||||||||||||||||||
| 120 | (There's a lot of room for clever hacks here. For instance, you could use a | ||||||||||||||||||||||||||||
| 121 | resolver that returns a different object each time it's called. Also, | ||||||||||||||||||||||||||||
| 122 | consider passing a closure as the resolver rather than a plain old reference | ||||||||||||||||||||||||||||
| 123 | to a function.) | ||||||||||||||||||||||||||||
| 124 | |||||||||||||||||||||||||||||
| 125 | B<NOTE:> Strictly speaking, the method C<new> doesn't exist as such: it isn't | ||||||||||||||||||||||||||||
| 126 | actually defined. Instead, it's emulated using C<AUTOLOAD> (see below) -- | ||||||||||||||||||||||||||||
| 127 | B<< but only when called as a class method! >> This way, your target | ||||||||||||||||||||||||||||
| 128 | objects' class(es) can safely implement a method C<new> that can be called | ||||||||||||||||||||||||||||
| 129 | as either a class method or an object method: | ||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||
| 131 | $obj1 = MyClass->new(...); | ||||||||||||||||||||||||||||
| 132 | $obj2 = $obj1->new(...); | ||||||||||||||||||||||||||||
| 133 | |||||||||||||||||||||||||||||
| 134 | See L<perltoot|perltoot> for information on how to implement this style of | ||||||||||||||||||||||||||||
| 135 | constructor. | ||||||||||||||||||||||||||||
| 136 | |||||||||||||||||||||||||||||
| 137 | When C<new> is called as a class method on your own class, | ||||||||||||||||||||||||||||
| 138 | L<Class::Proxy::Lite|Class::Proxy::Lite> isn't involved (unless you set up | ||||||||||||||||||||||||||||
| 139 | your objects' classes to inherit from it, which is a very bad idea). When | ||||||||||||||||||||||||||||
| 140 | C<new> is called as an object method, the call is passed on to the target | ||||||||||||||||||||||||||||
| 141 | object just as would happen for any other object method call. | ||||||||||||||||||||||||||||
| 142 | |||||||||||||||||||||||||||||
| 143 | =head2 AUTOLOAD | ||||||||||||||||||||||||||||
| 144 | |||||||||||||||||||||||||||||
| 145 | This is where the action takes place. It simply calls the resolver to get a | ||||||||||||||||||||||||||||
| 146 | reference to the target object, then passes the method call on to it. | ||||||||||||||||||||||||||||
| 147 | |||||||||||||||||||||||||||||
| 148 | The methods C<DESTROY> and C<import> are special-cased; the former is | ||||||||||||||||||||||||||||
| 149 | ignored, while the latter is ignored if and only if it was invoked on an | ||||||||||||||||||||||||||||
| 150 | object (i.e., not called implicitly as the result of a C<use> statement). | ||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||
| 152 | Except for C<import> and C<new>, all methods invoked on this class or a | ||||||||||||||||||||||||||||
| 153 | subclass of it (as opposed to methods invoked on an actual object) result in | ||||||||||||||||||||||||||||
| 154 | an exception being thrown. An exception is also thrown if the resolver | ||||||||||||||||||||||||||||
| 155 | returns C<undef> or a non-reference -- in other words, if it can't resolve | ||||||||||||||||||||||||||||
| 156 | the token into an actual object. | ||||||||||||||||||||||||||||
| 157 | |||||||||||||||||||||||||||||
| 158 | B<WARNING:> Never call AUTOLOAD directly! | ||||||||||||||||||||||||||||
| 159 | |||||||||||||||||||||||||||||
| 160 | =head1 SUBCLASSING | ||||||||||||||||||||||||||||
| 161 | |||||||||||||||||||||||||||||
| 162 | Depending on your needs, it may not be necessary to subclass | ||||||||||||||||||||||||||||
| 163 | L<Class::Proxy::Lite|Class::Proxy::Lite>. If you do, however, your subclass | ||||||||||||||||||||||||||||
| 164 | will probably look something like this: | ||||||||||||||||||||||||||||
| 165 | |||||||||||||||||||||||||||||
| 166 | package MyObject::Proxy; | ||||||||||||||||||||||||||||
| 167 | @ISA = qw(Class::Proxy::Lite); | ||||||||||||||||||||||||||||
| 168 | sub new { | ||||||||||||||||||||||||||||
| 169 | my ($cls, $target) = @_; | ||||||||||||||||||||||||||||
| 170 | my $token = obj2token($target); | ||||||||||||||||||||||||||||
| 171 | my $resolver = \&token2obj; | ||||||||||||||||||||||||||||
| 172 | return $self->SUPER::new($token, $resolver); | ||||||||||||||||||||||||||||
| 173 | } | ||||||||||||||||||||||||||||
| 174 | sub obj2token { ... } | ||||||||||||||||||||||||||||
| 175 | sub token2obj { ... } | ||||||||||||||||||||||||||||
| 176 | |||||||||||||||||||||||||||||
| 177 | See F<t/proxy.t> for a slightly different example. | ||||||||||||||||||||||||||||
| 178 | |||||||||||||||||||||||||||||
| 179 | C<Class::Proxy::Lite> was designed to avoid method name clashes; the only | ||||||||||||||||||||||||||||
| 180 | method defined for it is C<AUTOLOAD>. If your subclass must inherit from | ||||||||||||||||||||||||||||
| 181 | another class that uses AUTOLOAD, this is probably not the right solution | ||||||||||||||||||||||||||||
| 182 | for you. | ||||||||||||||||||||||||||||
| 183 | |||||||||||||||||||||||||||||
| 184 | =head1 BACKGROUND | ||||||||||||||||||||||||||||
| 185 | |||||||||||||||||||||||||||||
| 186 | L<Class::Proxy|Class::Proxy> didn't fit my needs. I was implementing an | ||||||||||||||||||||||||||||
| 187 | object model in which objects are loaded dynamically and references to | ||||||||||||||||||||||||||||
| 188 | loaded objects are stored in a master table. I wanted a solution that | ||||||||||||||||||||||||||||
| 189 | served both as a proxy and a reference (generally speaking) to an object. | ||||||||||||||||||||||||||||
| 190 | This module is what resulted. | ||||||||||||||||||||||||||||
| 191 | |||||||||||||||||||||||||||||
| 192 | =head1 LIMITATIONS | ||||||||||||||||||||||||||||
| 193 | |||||||||||||||||||||||||||||
| 194 | Apparently, it's not possible to catch calls to the C<can()> and C<isa()> | ||||||||||||||||||||||||||||
| 195 | methods on B<instances> of C<Class::Proxy::Lite>. This makes it impossible | ||||||||||||||||||||||||||||
| 196 | to implement a true proxy without defining C<UNIVERSAL::isa> and | ||||||||||||||||||||||||||||
| 197 | C<UNIVERSAL::can>, which I'm reluctant to do. | ||||||||||||||||||||||||||||
| 198 | |||||||||||||||||||||||||||||
| 199 | The following note in L<perlobj|perlobj> (under `Default UNIVERSAL methods') | ||||||||||||||||||||||||||||
| 200 | appears to explain the problem: | ||||||||||||||||||||||||||||
| 201 | |||||||||||||||||||||||||||||
| 202 | NOTE: `can' directly uses Perl's internal code for method | ||||||||||||||||||||||||||||
| 203 | lookup, and `isa' uses a very similar method and cache-ing | ||||||||||||||||||||||||||||
| 204 | strategy. This may cause strange effects if the Perl code | ||||||||||||||||||||||||||||
| 205 | dynamically changes @ISA in any package. | ||||||||||||||||||||||||||||
| 206 | |||||||||||||||||||||||||||||
| 207 | I might be wrong about all this, though; any insights on this problem are | ||||||||||||||||||||||||||||
| 208 | welcome. | ||||||||||||||||||||||||||||
| 209 | |||||||||||||||||||||||||||||
| 210 | =head1 SEE ALSO | ||||||||||||||||||||||||||||
| 211 | |||||||||||||||||||||||||||||
| 212 | L<Class::Proxy|Class::Proxy> is a better alternative for more sophisticated | ||||||||||||||||||||||||||||
| 213 | proxy capabilities. | ||||||||||||||||||||||||||||
| 214 | |||||||||||||||||||||||||||||
| 215 | =head1 VERSION | ||||||||||||||||||||||||||||
| 216 | |||||||||||||||||||||||||||||
| 217 | 1.01 | ||||||||||||||||||||||||||||
| 218 | |||||||||||||||||||||||||||||
| 219 | =head1 AUTHOR | ||||||||||||||||||||||||||||
| 220 | |||||||||||||||||||||||||||||
| 221 | Paul Hoffman <nkuitse AT cpan DOT org>. | ||||||||||||||||||||||||||||
| 222 | |||||||||||||||||||||||||||||
| 223 | =head1 CREDITS | ||||||||||||||||||||||||||||
| 224 | |||||||||||||||||||||||||||||
| 225 | Thanks to Kurt Starsinic (KSTAR) for L<Class::Delegate|Class::Delegate>, | ||||||||||||||||||||||||||||
| 226 | which got me thinking, and to Murat Uenalan (MUENALAN) for | ||||||||||||||||||||||||||||
| 227 | L<Class::Proxy|Class::Proxy>, which set a good example. | ||||||||||||||||||||||||||||
| 228 | |||||||||||||||||||||||||||||
| 229 | =head1 COPYRIGHT | ||||||||||||||||||||||||||||
| 230 | |||||||||||||||||||||||||||||
| 231 | Copyright 2003 Paul M. Hoffman. All rights reserved. | ||||||||||||||||||||||||||||
| 232 | |||||||||||||||||||||||||||||
| 233 | This program is free software; you can redistribute it and modify it under | ||||||||||||||||||||||||||||
| 234 | the same terms as Perl itself. | ||||||||||||||||||||||||||||
| 235 | |||||||||||||||||||||||||||||
| 236 | =cut | ||||||||||||||||||||||||||||
| 237 | |||||||||||||||||||||||||||||