NAME

Elive::DAO - Abstract class for Elive Data Access Objects

DESCRIPTION

This is an abstract class for retrieving and managing objects mapped to a datastore.

METHODS

entity_name

    my $entity_name = MyApp::Entity::User->entity_name
    ok($entity_name eq 'user');

collection_name

    my $collection_name = MyApp::Entity::User->collection_name
    ok($collection_name eq 'users');

id

    my @primary_vals = $entity_obj->id

Return primary key values.

primary_key

Setter/getter for primary key field(s) for this entity class

    my @pkey = MyApp::Entity::User->primary_key

params

Setter/getter for parameter field(s) for this entity class

    Elive::Entity::User->params(loginName => 'Str');
    my %params = MyApp::Entity::User->params;

derivable

Setter/getter for derivable field(s) for this entity class

entities

    my $entities = Entity::Entity->entities

    print "user has entity class: $entities->{user}\n";
    print "meetingParticipant entity class has not been loaded\n"
        unless ($entities->{meetingParticipant});

Return has hash ref of all loaded entity names and classes

properties

   my @properties = MyApp::Entity::User->properties;

Return the property accessor names for an entity

property_types

   my $user_types = MyApp::Entity::User->property_types;
   my $type_info = Elive::Util::inspect_type($user_types->{role})

Return a hashref of attribute data types.

property_doco

    my $user_doc = MyApp::Entity::User->property_doc
    my $user_password_doco = $user_doc->{loginPassword}

Return a hashref of documentation for properties

stringify

Return a human readable string representation of an object. For database entities, this is the primary key:

    if ($user_obj->stringify eq "11223344") {
        ....
    }

Arrays of sub-items evaluated, in a string context, to a semi-colon separated string of the individual values sorted.

    my $group = Elive::Entity::Group->retrieve(98765);
    if ($group->members->stringify eq "11223344;2222222") {
         ....
    }

In particular meeting participants stringify to userId=role, e.g.

    my $participant_list = Elive::Entity::ParticipantList->retrieve(98765);
    if ($participant_list->participants->stringify eq "11223344=3;2222222=2") {
         ....
    }

connection

    my $default_connection = Elive::Entity::User->connection;
    my $connection = $entity_obj->connection;

Return a connection. Either the actual connection associated with a entity instance, or the default connection that will be used.

disconnect

Disconnects and disassociates an Elluminate connection from this class. It is recommended that you do this prior to exiting your program.

url

    my $url = $user->url

Abstract method to compute a restful url for an object instance. This will include both the url of the connection string and the entity class name. It is used internally to uniquely identify and cache objects across repositories.

construct

    my $user = Entity::User->construct(
            {userId = 123456,
             loginName => 'demo_user',
             role => {
                 roleId => 1
               }
             },
             overwrite => 1,        # overwrite any unsaved changes in cache
             connection => $conn,   # connection to use
             copy => 1,             # return a simple blessed uncached object.
           );

Abstract method to construct a data mapped entity. A copy is made of the data for use by the is_changed and revert methods.

is_changed

Abstract method. Returns a list of properties that have been changed since the entity was last retrieved or saved.

set

    $obj->set(prop1 => val1, prop2 => val2 [,...])

Abstract method to assign values to entity properties.

insert

    my $new_user = Elive::Entity::User->insert(
             {loginName => 'demo_user',
              email => 'demo.user@test.org'}
             },
             connection => $con,   # connection to use,
             command => $cmd,      # soap command to use
             );

    print "inserted user with id: ".$new_user->userId."\n";

Abstract method to insert new entities. The primary key is generally not required. It is generated for you and returned with the newly created object.

live_entity

    my $user_ref
      = Elive::Entity->live_entity('http://test.org/User/1234567890');

Returns a reference to an object in the Elive::Entity cache.

live_entities

    my $live_entities = Elive::Entity->live_entities;

    my $user_ref = $live_entities->{'http://test.org/User/1234567890'};

Returns a reference to the Elive::Entity cache.

update

Abstract method to update entities. The following commits outstanding changes to the object.

    $obj->{foo} = 'Foo';  # change foo attribute directly
    $foo->update;         # save

    $obj->bar('Bar');     # change bar via its accessor
    $obj->update;         # save

Updates may also be passed as parameters:

    # change and save foo and bar. All in one go.
    $obj->update({foo => 'Foo', bar => 'Bar'});

This method can be called from the class level. You will need to supply the primary key and all mandatory fields.

list

    my $users = Elive::Entity::User->list(
                    filter => 'surname = smith',  # filter results (server side)
                    command => $cmd,              # soap command to use
                    connection => $connection,    # connection to use
                    raw => 1,                     # return unblessed data
                );

Abstract method to list entity objects.

retrieve

    my $user = Elive::Entity::User->retrieve(
                        $user_id,
                        reuse => 1,  # use cached data if present.
                        );
    

Abstract method to retrieve a single entity object by primary key.

delete

    $user_obj->delete;

    Elive::Entity::Session->delete(sessionId = 123456);

Abstract method to delete an entity.

revert

    $user->revert                        # revert entire entity
    $user->revert(qw/loginName email/);  # revert selected properties

Abstract method to revert an entity to its last constructed value.

ADVANCED

Object Management

Elive::DAO keeps a reference table to all current database objects. This is primarily used to detect errors, such as destroying or overwriting objects with unsaved changes.

You can also reuse objects from this cache by passing reuse => 1 to the fetch method.

    my $user = Elive::Entity::User->retrieve(11223344);
    #
    # returns the same reference, but refetches from the database
    #
    my $user_copy = Elive::Entity::User->retrieve(11223344);
    #
    # same as above, however don't refetch if we already have a copy
    #
    my $user_copy2 = Elive::Entity::User->retrieve(11223344, reuse => 1);

You can access the in-memory cache using the live_entity and live_entities methods.

Entity Manipulation

All objects are simply blessed structures that contain data and nothing else. You may choose to use the accessors, or work directly with the object data.

The following are all equivalent, and are all ok:

    my $p_list = Elive::Entity::ParticipantList->retrieve(98765);
    my $user = Elive::Entity::User->retrieve(11223344);

    $p_list->participants->add($user);
    push (@{ $p_list->participants        }, $user);
    push (@{ $p_list->{participants}      }, $user);
    push (@{ $p_list->get('participants') }, $user);

SEE ALSO

Mouse (base class) - Middle-weight Moose like class system

cpanm Elive

perl -MCPAN -e shell
install Elive