NAME

Object::Registrar - A global registry of objects that can be resolved by names

SYNOPSIS

  use Object::Registrar;

  my $or = new Object::Registrar();

  $nm->bind('Test/Foo', new Foo());      ## or use register()
  $nm->bind('Test/Bar', new Bar());

  my $foo = $nm->resolve('Test/Foo');
  $nm->rebind('Test/Bar', $bar);         ## or use reregister()

  my %objhash = $or->list();
  my %objhash = $or->list('Test/*');

  my $bool = $or->exists('Test/Foo');

  $or->unbind('Test/Bar');               ## or use unregister()

  ## ----------------------------------- ##
  ## Typical usage with error handling   ##
  ## ----------------------------------- ##

  use Object::Registrar;
  use Error qw(:try);

  my $or = new Object::Registrar();
  try {
    $or->resolve('Null');
  }
  catch Object::NotFoundException with {
    my ($ex) = shift;
    print "Caught NotFoundException: $ex\n";
  };

DESCRIPTION

The Object::Registrar implements is a global registry of objects. This module makes use of the Singleton Pattern to achieve the desired functionality.

Using this module an application can register its Object instances in the Registrar with a unique name. Later on in the application these object instances can be retrieved / resolved by providing the unique name.

The names provided for identifying the Objects can be anything that would be acceptable as a valid hash key in Perl.

For a detailed description of the Singleton Pattern, refer "Design Patterns", Gamma et al, Addison-Wesley, 1995, ISBN 0-201-63361-2.

METHODS

$nm->bind (NAME, OBJ)

Binds the object specified OBJ in the Registry with the name NAME. The object can then be retrieved from the Registry by invoking the resolve() method, passing the NAME as a parameter.

This method raises the Object::AlreadyBound exception if the specified NAME already exists in the Registry.

$nm->rebind (NAME, OBJ)

Unlike bind() this method does not raise the Object::AlreadyBound expection but otherwise performs the same functions as bind(). Using this method allows you to associate an object OBJ with a NAME that is already bound in the Registry.

$nm->unbind (NAME)

This method disassociates the mapping between the given name NAME and its object from the Registry.

$nm->resolve (NAME)

This method retruns the object referred by the given name NAME.

This method raises the Object::NotFoundException exception if the specified NAME does not exist in the Registry or if the object referenced by the NAME is not defined.

$nm->exists (NAME)

Returns a boolean value indicating existence of the given name NAME in the Registry.

$nm->list ([PATTERN])

This method returns a Perl hash containing all the names in the Registry as keys in the hash. The objects referred by the names are stored as values to the corresponding key in the hash.

This method accepts any valid perl regular expression i.e PATTERN to filter the keys that would be returned. If the PATTERN is left undefined then all the names in the Registry are returned.

$nm->register (NAME, OBJ)

Alias for bind(). Works exactly the same as bind();

$nm->reregister (NAME, OBJ)

Alias for rebind(). Works exactly the same as rebind();

$nm->unregister (NAME)

Alias for unbind(). Works exactly the same as unbind();

$nm->Debug ([VAL])

This method turn ON verbosity if the VAL is TRUE and truns OFF verbosity if VAL is FALSE. If called without any parameters it returns the current value for the verbosity flag.

STATIC INVOCATION

All the above methods can also be statically invoked. As illustrated here:

  Object::Registrar->bind('Test/Foo', new Foo());
  my $foo = Object::Registrar->resolve('Test/Foo');

  my %objhash = Object::Registrar->list('Widget/Labels*');

     ....
     ....

  Object::Registrar->unbind('Test/Bar'); 

EXCEPTIONS

Object::NotFoundException

This exception is raised when a call to resolve() is not able to locate an object with the given name in the Registry.

Object::AlreadyBound

This exception is raised when bind() or register() is called with a name that is already available in the Registry.

PREREQUISITES

Error.pm - Error/exception handling in an OO-ish way

KNOWN BUGS

None. Well if they are KNOWN, they will be fixed :-)

COPYRIGHT

Copyright (c) 2001 Arun Kumar U <u_arunkumar@yahoo.com>. All rights reserved.

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

AUTHOR

Arun Kumar U <u_arunkumar@yahoo.com>

SEE ALSO

perl(1)