NAME

Object::GlobalContainer - A global singleton object container

SYNOPSIS

 use Object::GlobalContainer;
 
 my $OC = Object::GlobalContainer->new();
 
 $OC->set('abc','123');
 $OC->set('first/second/third','456');
 
 print $OC->get('abc');
 print $OC->get('first/second/third');


 ## per default it works as singleton!
 use Object::GlobalContainer;

 my $OC1 = Object::GlobalContainer->new();
 my $OC2 = Object::GlobalContainer->new();
 
 $OC1->set('abc','123');
 print $OC2->get('abc'); ## returns also 123 !

 # to disable singleton behaviour, write:
 my $OC = Object::GlobalContainer->new( notglobal => 1 );

 # loading a class
 my $c = $OC->class('classes/database', 'Local::MyDatabaseHandler', foo => 123, bar => 456);

DESCRIPTION

The GlobalContainer is another object container and very similar to Object::Container and Object::Registrar, but it supports deep hash storages. It means you can save your data by using a path notation like 'foo/bar/more'. And that is not handled as a string, but a hash.

REQUIRES

Class::Inspector

Moose

METHODS

class

 my $classobject = class($path, $classname, %classparam);

Creates an instance of the given class and sets it to the given path. it also returns the new object. It is managed as a singleton, what means, if there is already an object in the given path, it won't instantiate the class again. It will call the constructor of the class with given parameters. If it is already loaded onto given path, it won't load it again. If you want to force a new load, please delete it first or replace it with set().

 my $c = $OC->class('classes/database', 'Local::MyDatabaseHandler', foo => 123, bar => 456);

I think the way Object::Container register classes, by it's own name, is against the idea of an object container. Because the getting part should not need to know what exactly has been set, to keep the application flexible. That is why I am setting it into the given path and not the classname.

If for example dealing with mod_perl and keeping the application in memory, it is very nice to re-run that code, but automatically skipping a new instantiation.

What means that that line:

 my $c = $OC->class('classes/database', 'Local::MyDatabaseHandler', foo => 123, bar => 456);

will be executed in a different way when running it the second time, if it still is in memory. Then it does not instantiate the class again, but just returns the existing instance.

Otherwise you would need to build your own complex if/else line.

delete

 delete($path);

deletes an entry by removing it from the hash

exists

 my $boolean = exists($path);

Validates if an entry (key) exists.

get

 my $scalar | reference = get($path);

returns a value by given key, which can be a path.

set

 set($key1, $value1, $key2, $value2);

Adds an object (any value or reference). Expects a key and a value. The key may be a path with slash delimiter. It will be stored as nested hash nodes.

hash storage

To be honest, I was not lucky with the plain store other classes provide. What means, to have only one string as identifier. Often you have already hash structures and you want to store them, but maybe read them with one simple command and not two.

The classical way, other object container usually work:

 my $data = {
      foo => {
               bar => {
                        more => '123',
                      }
             }
            };

 store->set('some/where',$data);

 print store->get('some/where')->{'foo'}->{'bar'}->{'more'};

Here you had to use the get() plus the hash syntax to access the content. With Object::GlobalContainer it is easier to access the content directly:

 print store->get('some/where/foo/bar/more');

Because the used string (path) is realy a path for a hash structure.

singleton

As shown in synopsis's example, the default behaviour is to work as singleton, because you usually want to share things globaly. Disable that by using the flag 'notglobal' in the constructor.

singleton, off (notglobal)

If you want to disable the singleton behaviour, you can use 'notglobal' to do so:

 my $OC1 = Object::GlobalContainer->new( notglobal => 1 );
 my $OC2 = Object::GlobalContainer->new( notglobal => 1 );
 
 $OC1->set('abc','123');
 $OC2->set('abc','456');

 print $OC1->get('abc'); ## returns 123 !
 print $OC2->get('abc'); ## returns 456 !

Both instances act as them self, as own separate object.

imported function

The most elegant way to deal with that global container, is to use a local funtion:

 use Object::GlobalContainer 'objcon';

 Object::GlobalContainer->new();

 objcon->set('abc','123');
 objcon->get('abc');

Here it installs the function 'objcon' locally to access the container. Combined with the default behaviour as singleton, it is quite usefull. Please note, the name of the method you can choose by yourself and may be different in every class.

Do not forget to call the constructor first!

delimiter

The default delimiter for a path is a slash like in 'a/b/c'. But you can change it, by setting 'delimiter' with the constructor:

 my $OC = Object::GlobalContainer->new( delimiter => '.' );
 $OC->get('a.b.c');

If using the imported function access method, you can change the delimter via a method call:

 use Object::GlobalContainer 'objcon';

 objcon->delimiter('.');
 objcon->set('a.b.c','123');
 objcon->get('a.b.c');

AUTHOR

Andreas Hernitscheck ahernit(AT)cpan.org

LICENSE

You can redistribute it and/or modify it under the conditions of LGPL.

cpanm Object::GlobalContainer

perl -MCPAN -e shell
install Object::GlobalContainer