NAME

  Class::ReluctantORM::Registry - Store CRO instances uniquely

SYNOPSIS

  # Setup a CRO class to use a Hash-based registry
  package MyCRO;
  use base 'Class::ReluctantORM';
  MyCRO->build_class(
                     ...
                     registry => 'Class::ReluctantORM::Registry::Hash',
                    );

  # Use the default registry class
  OtherCRO->build_class( ... );  # omit registry param

  # Change the default registry class
  Class::ReluctantORM::Registry->default_registry_class
     ('Class::ReluctantORM::Registry::Custom');

  # Disable registries
  Class::ReluctantORM::Registry->default_registry_class
     ('Class::ReluctantORM::Registry::None');

  # Work with a class's registry
  my $reg = MyCRO->registry();
  print "Have " . $reg->count() . " objects cached\n";

  $reg->walk(sub {
     my $obj = shift;
     ...
  });

  my $obj = $reg->fetch($id);
  $reg->store($obj);
  $reg->purge($id);
  $reg->purge_all();

DESCRIPTION

The Registry facility provides a way to ensure that objects loaded from the database are unique in memory. Upon initial fetch from the database, each CRO object is stored in its class's Registry. Subsequent fetches will result in the first object being returned.

This class provides a generalized interface for Registries. Specific subclasses provide specific implementations, each of which has strengths and weaknesses. A do-nothing Registry is provided as well, Registry::None .

Each CRO class may choose its registry implementation by naming a Registry subclass using the 'registry' parameter to build_class. If the parameter is not provided, the class named by Class::ReluctantORM::Registry->default_registry_class() will be used. You may change this default by passing a value.

NOTES ON IMPLEMENTING REGISTRIES

You may also write your own Registry classes. Simply subclass from this class, and implement the methods listed under METHODS FOR SUBCLASSES TO IMPLEMENT.

You are free to extend the Registry API (for example, with expirations or size or count limits).

You must use weak references to track objects. Otherwise this will leak memory badly. See Scalar::Util::weaken .

METHODS PROVIDED BY THIS SUPERCLASS

$reg = RegClass->new($target_class);

A basic constructor is provided. It sets the target class and blesses a hashref.

$reg_class = Class::ReluctantORM::Registry->default_registry_class();

Class::ReluctantORM::Registry->default_registry_class($new_default);

Reads or sets the defualt Registry class used when no 'registry' param is passed to build_class().

When setting, the class passed must be a subclass of Class::ReluctantORM::Registry.

$class = $registry->target_class();

Returns the CRO class for which this Registry is caching objects.

METHODS FOR SUBCLASSES TO IMPLEMENT

$obj = $registry->fetch($id);

Looks for an object previously stored with composite ID $id, and if found, returns it.

If not found, returns undef.

$registry->store($obj);

Stores an object in the registry, using its id() as the key. If the object already existed, it is replaced.

$registry->purge($id);

Removes an object from the registry. This doesn't invalidate any other references to the object, but subsequent fetch()s will return undef until an objecvt with the same ID is stored again.

$registry->purge_all();

Removes all objects from the registry.

$int = $registry->count();

Returns an integer count of the number of objects currently tracked by the registry.

$registry->walk($coderef);

Fetches each stored object and calls the provided coderef, sending the object as the only argument.

AUTHOR

 Clinton Wolfe clwolfe@cpan.org January 2010

cpanm Class::ReluctantORM

perl -MCPAN -e shell
install Class::ReluctantORM