NAME

Myco::Entity - common base class for all Myco entity classes.

SYNOPSIS

 ### Entity class definition

 package Myco::Foo;
 use base qw(Myco::Entity);

 # Start building metadata
 my $metadata = Myco::Entity::Meta->new
  ( name => __PACKAGE__,
    tangram => { table => 'Foo' }
  );

 $metadata->add_attribute(name => 'attr1', type => 'string');
 $metadata->add_attribute(name => 'attr2', type => 'string');

 #    class-specific methods defined ...
 #

 # Fill in $schema with all added_attributes and discover other metadata
 $metadata->activate_class;



 ### Entity class usage

 use Myco::Foo;

 # Constructor
 $obj = Myco::Foo->new;
 $obj = Myco::Foo->new(attr1 => value, attr2 => value);

 # Access class metadata (see Myco::Entity::Meta)
 $meta = Myco::Foo->introspect;
 $meta = $obj->introspect;

 # Accessors
 $obj->get_attr1;              # get attribute value
 $obj->set_attr1('value');     # set attribute value

 # Instance methods
 $id = $obj->save;             # update object's state in persistent
                               # storage, create new record if needed;
                               # returns object's Tangram id
 $obj->destroy;
 $obj->modify(attr1 => val, attr2 => val);
 $object_id = $obj->id;
 $obj->is_transient;           # returns true if object is in Tangram
                               # transient storage

 ## object retrieval (see class Myco documentation
 #    for full detail)

 $obj = Myco->load($object_id);

 # fetch all objects of given type
 @objects = Myco->select(ref $obj);

DESCRIPTION

Provides, via inheritence, common interface in support of basic lifecycle needs for myco entity objects.

This is accomplished through the encapsulation of the CPAN module Class::Tangram which provides a basis for "in-memory" object behavior. Consult its documentation for details on schema definition syntax, getter/setter behavior, check functions, etc.

The common interface for object persistence behavior (referred within myco as "transaction" behavior) is provided through defintion of a handful of related instance methods. This is done with reliance on the services of the class Myco, which encapsulates the functionality of Tangram::Storage and provides system-wide connection handling.

CLASS SETUP

Class meta data and object schema definition is managed via Myco::Entity::Meta. Typical class setup begins like this:

 package Foo;
 use base qw(Myco::Entity);
 my $metadata = Myco::Entity::Meta->new
  ( name => __PACKAGE__,
    tangram => { table => 'foo' }
  );

The 'tangram' parameter passes in an anonymous hash containing a Class::Tangram-style schema definition [but --without-- a 'fields' key!]. The creation of the $metadata object is normally followed by one or more calls to $metadata->add_attribute() each of which adds an attribute to the schema, along with establishing associated metadata.

At the very end of the class file comes the following, which triggers a final phase of metadata discovery and makes the object schema active.

 $metadata->activate_class;

Class setup in Class::Tangram $schema style

Alternately the schema may be specified as a fully laid-out $schema data structure, with no $metadata->add_attribute() calls. In this case the activate_class() method will parse $schema and fill out the $metadata object with what it finds. This may be of use when converting an existing class or when the Class::Tangram style is simply preferred.

import_schema [deprecated]

 Myco::Entity::import_schema('Myco::Foo');

Informs Class::Tangram about class's schema so it can take care of in-memory behavior. ***If Myco::Entity::Meta is in use then direct use of this method should be avoided.

CONSTRUCTOR

new

 $obj = Myco::Foo->new;
 $obj = Myco::Foo->new(attr1 => value, attr2 => value);

Object constructor. See Class::Tangram documentation. Will throw an exception if a required attribute is missing from parameter list.

CLASS / INSTANCE METHODS

See Class::Tangram for other available methods.

new

  $obj->set(attribute => $value, ...);

Constructs the new object. Overrides Class::Tangram::set() in order to initiate the Event Cache.

set

  $obj->set(attribute => $value, ...);

Sets the value of an attribute. Overrides Class::Tangram::set() in order to enforce access control.

get

  my $value = $obj->get($attribute);

Returns the value of an attribute. Overrides Class::Tangram::get() in order to enforce access control.

save

 $id = $obj->save;

Updates database state to be consistent with object's current in-memory representation. If object is not already persistent, it is inserted into the database. The Tangram object ID is returned.

destroy

 $obj->destroy;

Removes object from persistent storage and does its best to remove it from memory as well. This memory cleanup process includes:

• Clearing all attributes that hold references to other objects (via a call to $obj->clear_refs. See Class::Tangram).

• Clearing the Tangram transient storage reference to object.

• Setting to undef the caller object reference. If no other references to the object exist Perl will do its usual garbage collection.

This method is just an encapsulation of the call 'Myco->destroy($obj)'.

modify

 $obj->modify(attr1 => value, attr2 => value);

Modifies one or more object attributes and updates object's persistence storage state as well.

id

 $id = $obj->id;

Returns the Tangram persistence object identifier (typcially for use with later calls to Myco->load() ).

is_transient

 if ($obj->is_transient) { ... };

Returns true if object is currently in Tangram transient storage.

introspect

 $meta = Myco::Foo->introspect;
 $meta = $obj->introspect;

Returns the Myco::Entity::Meta metadata object that describes the referent, or undef if none exists.

SEARCHING AND LOADING

Retrieval of objects from persistent storage is accomplished via related class methods of the class Myco. See Myco.

LICENSE AND COPYRIGHT

Copyright (c) 2006 the myco project. All rights reserved. This software is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

AUTHOR

Charles Owens <czbsd@cpan.org>

SEE ALSO

Myco::Entity::Meta, Class::Tangram, Tangram, Myco::Test::EntityTest, Myco, myco-mkentity

cpanm Myco

perl -MCPAN -e shell
install Myco