NAME

IOC::Container - An IOC Container object

SYNOPSIS

  use IOC::Container;
  
  my $container = IOC::Container->new();
  $container->register(IOC::Service::Literal->new('log_file' => "logfile.log"));
  $container->register(IOC::Service->new('logger' => sub { 
      my $c = shift; 
      return FileLogger->new($c->get('log_file'));
  }));
  $container->register(IOC::Service->new('application' => sub {
      my $c = shift; 
      my $app = Application->new();
      $app->logger($c->get('logger'));
      return $app;
  }));

  $container->get('application')->run();    
  
  
  # or a more complex example
  # utilizing a tree-like structure
  # of services

  my $logging = IOC::Container->new('logging');
  $logging->register(IOC::Service->new('logger' => sub {
      my $c = shift;
      return My::FileLogger->new($c->find('/filesystem/filemanager')->openFile($c->get('log_file')));
  }));
  $logging->register(IOC::Service::Literal->new('log_file' => '/var/my_app.log')); 
  
  my $database = IOC::Container->new('database');
  $database->register(IOC::Service->new('connection' => sub {
      my $c = shift;
      return My::DB->connect($c->get('dsn'), $c->get('username'), $c->get('password'));
  }));
  $database->register(IOC::Service::Literal->new('dsn'      => 'dbi:mysql:my_app'));
  $database->register(IOC::Service::Literal->new('username' => 'test'));
  $database->register(IOC::Service::Literal->new('password' => 'secret_test'));          
  
  my $file_system = IOC::Container->new('filesystem');
  $file_system->register(IOC::Service->new('filemanager' => sub { return My::FileManager->new() })); 
          
  my $container = IOC::Container->new(); 
  $container->addSubContainers($file_system, $database, $logging);
  $container->register(IOC::Service->new('application' => sub {
      my $c = shift; 
      my $app = My::Application->new();
      $app->logger($c->find('/logging/logger'));
      $app->db_connection($c->find('/database/connection'));
      return $app;
  })); 
  
  $container->get('application')->run();

DESCRIPTION

In this IOC framework, the IOC::Container object holds instances of IOC::Service objects keyed by strings. It can also have sub-containers, which are instances of IOC::Container objects also keyed by string.

                    +------------------+
                    |  IOC::Container  |
                    +---------+--------+
                              |
           +------------------+-----------------+
           |                  |                 |
   (*sub-containers)     (*proxies)        (*services)
           |                  |                 |
           V                  V                 V
 +------------------+  +--------------+  +--------------+
 |  IOC::Container  |  |  IOC::Proxy  |  | IOC::Service |
 +------------------+  +--------------+  +--------------+
                                                |
                                            (instance)
                                                |
                                                V
                                    +-------------------------+                                                
                                    | <Your Component/Object> |
                                    +-------------------------+

METHODS

new ($container_name): A container can be named with the optional $container_name argument, otherwise the container will have the name 'default'.
name: This will return the name of the container.

Service Methods

register ($service)

Given a $service, this will register the $service as part of this container. The value returned by the "name" method of the $service object is as the key where this service is stored. This also will call "setContainer" on the $service and pass in it's own instance.

If $service is not an instance of IOC::Service, or a subclass of it, an IOC::InsufficientArguments exception will be thrown.

If the name of $service already exists, then a IOC::ServiceAlreadyExists exception is thrown.

unregister ($name)

Given a $name this will remove the service from the container. If there is no service by that $name, then a IOC::ServiceNotFound exception is thrown.

registerWithProxy ($service, $proxy)

Same as "register" but also registers a $proxy object to wrap the $service object with.

addProxy ($name, $proxy)

Adds a $proxy object to wrap the service at $name.

get ($name)

Given a $name this will return the service instance that name corresponds to, if $name is not defined, an exception is thrown.

If there is no service by that $name, then a IOC::ServiceNotFound exception is thrown.

NOTE: If the requested service is currently locked (meaning it is being created), then a deferred service stub is returned. This will allow for cyclical dependencies to work.

find ($path)

Given a $path to a service, this method will attempt to locate that service. It utilizes the IOC::Visitor::ServiceLocator to do this.

hasService ($name)

getServiceList

Returns a list of all the named services available.

Parent Container Methods

getParentContainer: Get the parent container associated with this instance. If there is no container, undef is returned.
setParentContainer ($container): Given a $container, this will associate it as the invocant's parent. If the $container is not an instance of IOC::Container (or a subclass of it), an IOC::InsufficientArguments exception will be thrown.
isRootContainer: If the invocant does not have a parent, then it is considered a root container and this method will return true (1), otherwise it will return false (0).
findRootContainer: This will climb back up the container hierarchy and find the root of the container tree.

Sub-Container Methods

addSubContainer ($container): Adds a $container to it's keyed list of sub-containers. This has the effect of making the invocant the parent of $container. If $container is not a IOC::Container object (or a subclass of it), then an IOC::InsufficientArguments exception is thrown. If the name of $container is a duplicate of one already stored, then a IOC::ContainerAlreadyExists exception is thrown.
addSubContainers (@container): This just loops calling "addSubContainer" on each of the items in @containers.
hasSubContainer ($name)
hasSubContainers: This will return true (1) if the invocant has sub-containers, and false (0) otherwise.
getSubContainerList: This will return a list of strings which the sub-containers are keyed by.
getSubContainer ($name): This will return the sub-container associated with $name. If $name is undefined an IOC::InsufficientArguments exception will be thrown. If no sub-container exists by that $name, then an IOC::ContainerNotFound exception will be thrown.
getAllSubContainers: This will return a list of the actual sub-containers stored. This will be in the same order as the list returned by "getSubContainerList".
accept ($visitor): This method is part of the IOC::Visitable interface. It accepts only $visitor objects which implement the IOC::Visitor interface.

TO DO

Work on the documentation

BUGS

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

CODE COVERAGE

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

AUTHOR

stevan little, <stevan@iinteractive.com>

COPYRIGHT AND LICENSE

<http://www.iinteractive.com>

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