GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
IOC::Proxy(3) User Contributed Perl Documentation IOC::Proxy(3)

IOC::Proxy - Proxy for the IOC Framework

  use IOC::Proxy;
  
  my $proxy_server = IOC::Proxy->new({
                        on_method_call => sub {
                        my ($proxy_server, $method_name, $method_full_name, $current_method_args) = @_;
                        warn ("Method '$method_name' called with args (" . 
                              (join ", " => @{$current_method_args}) .
                              "), now passing call to '$method_full_name'");
                        }
                    });
  
  $proxy_server->wrap($object);
  # this now wraps the $object in a special proxy package
  # which will intercept all it's calls, while still
  # behaving exactly as if it was not proxied
  
  $object->method();
  # this will warn:
  #    Method 'method' called with args (Class::_::Proxy=HASH(0x859978)), now passing call to 'Class::method'

This module is a base class for all your IOC::Proxy needs. It can be used on it's own or it can be subclassed.

The basic idea of the IOC::Proxy is that since we are using the IOC framework to create our object instances, we can do certain things to those instances which we would not easily be able to do otherwise. In this specific case we can wrap the service instance with an IOC::Proxy object and be able to capture calls to the service instance through our proxy. The simplest use for this is some kind of logging.

The IOC::Proxy object does everything within it's power to make sure that the proxy object can be used as a drop in replacement to the service instance. This means we do not impose our OO-style on you class nor do we mess with your class's symbol table, and we are as transparent as possible.

All this is accomplished by the creation of a proxy package, which is just you package name followed by "::_::Proxy", which inherits from your object's class. We then gather up all the methods of your class by performaing a depth-first search of the inheritance tree (just as perl would do) and we then install these methods into our proxy package. We also check to see if your class has overloaded the stringification operator ("") and if not, we install our own which will remove all trace of the "::_::Proxy" package from the output, so when you stringify your object it will not show the proxy (unless you use "overload::StrVal").

Once our proxied package is all set up, we re-bless your object into the proxy package. One of the benefits of this is that we do not need to worry about the underlying reference type your class is implemented with, and all data storage in your instance is preserved without issue.

All this means that your proxied object will respond as expected to calls to "isa" and "can" (including "UNIVERSAL::isa" and "UNIVERSAL::can"), and since we use "goto" all evidence of IOC::Proxy is removed from the output of "caller" as well. It also respects "AUTOLOAD", "DESTROY" and overloaded operations. And when your object is automatically stringified, it will not show the proxy either. There is only one place where IOC::Proxy will reveal itself, and that is with "ref". Short of overloading "CORE::GLOBAL::ref" this could not be done.

new ($config)
This will construct a IOC::Proxy object, but do nothing with it. The $config option is an HASH ref, which can be used to store data with your proxied object since it will not actually be an instance of IOC::Proxy. The $config hash can have anything in it you want, but IOC::Proxy will look for two specific keys; on_method_call and on_wrap which should contain subroutine references and which will get called within "onMethodCall" and "onWrap" respectively.
wrap ($object)
This will wrap the $object given to it in a proxy package as described in the "IOC::Proxy guts" section above. The return value of this method is the proxied object. Theoretically since we actually will re-bless $object you don't actually need to capture that return value since the changes should affect $object as well.
onWrap ($unwrapped_object, $proxy_package)
This method is here mostly for subclasses of IOC::Proxy. It will be called when IOC::Proxy wraps an instance. Currently it will look for the value on_wrap in the $config passed to the constructor (see above for more details).

The first argument, $unwrapped_object is the object to be proxied, the second argument $proxy_package is the name of the package it will be proxied with. It is up to you what to do with them.

onMethodCall ($method, $original_method, $args)
This method is here mostly for subclasses of IOC::Proxy. It will be called when IOC::Proxy recieves a method call. Currently it will look for the value on_method_call in the $config passed to the constructor (see above for more details).

The first argument, $method is the short (local) name of the method which has been called. The second argument $original_method is the fully qualified name of the method which includes the package where it actually comes from (which in inheritance situations may not be the class of the original proxied object). The third argument $args is a reference to the @_ array the method was called with.

Work on the documentation

None that I am aware of. Of course, if you find a bug, let me know, and I will be sure to fix it.

I use Devel::Cover to test the code coverage of my tests, see the CODE COVERAGE section of IOC for more information.

Class::Proxy
Class::Proxy::Lite
Class::Wrap

stevan little, <stevan@iinteractive.com>

Copyright 2004-2007 by Infinity Interactive, Inc.

<http://www.iinteractive.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

2007-04-22 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.