Oak::DBIEntity - Class for DBI based entity classes

NAME

Oak::DBIEntity - Class for DBI based entity classes

HIERARCHY

Oak::Object

Oak::Persistent

Oak::DBIEntity

DESCRIPTION

Base class for DBI based entity classes. This class can be used to automate the development of business applications, it implements automatic load and save of data with get and set methods, functions for listing the objects of a class, functions to handle the relationships and the constructor with a default interface to create new objects of a class.

This class is based on methods that will be overriden to specify the behavior of a class.

P.S.: Methods that are written with UpperCaseLetters are class methods and methods written with lower_case_letters are object methods.

ABSTRACT METHODS

GetDefaultDBIIo: Returns the Oak::IO::DBI object to be used if there is not a custom object defined by the SetDBIIo method. Defaults to $::TL::dataModule->dbi. Where dataModule is a Oak::DataModule and dbi is the name of the Oak::IO::DBI component. Overrides it if your object is in another place.

GetFields

Returns a hashref where the key is the name of the table and the value is an arrayref of arrayrefs describing the table, each row represents a column. The column representation is another arrayref with two elements. The first element represents the name of the field and the second represents the SQL syntax to describe the field (without the field name).

Ex.:

  {
   User =>
   [
    ["login","VARCHAR(40) NOT NULL DEFAULT ''"],
    ...
   ]
   ...
  }

GetPrimaryKey

Returns an array reference with the fields that are the primary key of this object.

When implementing table-distributed classes (subclasses), remember that the primary keys of the tables MUST have the same name and value.

GetAutoIncrementFields

Returns a hash reference with the fields that we should auto increment.

The value has no meaning and it is a hash to simplify lookup.

GetRelationships

Return a hashref describing the relationships of this class. The hash structure follows:

  name_of_the_relationship =>
  {
   type => Relationship type, one of: 1-1, 1-N, N-1, N-N.
   class => The class of the objects at the other side.
   foreign_key => The field that maintain the relationship in this table.
   other_foreign_key => The field that maintain the relationship in the other table
   relation_table => Used in type N-N to specify the relationship table
   on_delete => The name of a method in the current class that will be called
                 when trying to delete this object:
            on_delete_cascade: Delete the objects at the other side (composition)
            on_delete_restrict: Do not delete anything if there are objects at the other side
            on_delete_set_null: Defines the foreign_key with a null value
            default: Delete this entity and do nothing with the other objects
  }

GetDefaultValues: Array of hashes with records to be inserted when setting up the entity class.

METHODS

GetDBIIo: Returns the Oak::IO::DBI object to be used with this class. Use the GetDefaultDBIIo or the object defined with the SetDBIIo method.

SetDBIIo(obj)

Defines which Oak::DBI::IO object to be used in this class from now on.

Remember that a class variable will be set in this module, so, always you set an obj, remember to set undef after using it, else your dbi object will never be destroyed.

Setup: Creates the table and insert the data specified in the GetDefaultValues method. XXTODOXX

List($query): List the objects of this class using $query as complement to the SQL. Returns an array with the objects.

Count($query): Count the objects in this class using $query as complement to the SQL.

constructor(create => {field => value})

Create this object into the system. Insert into the table.

Throws Oak::DBIEntity::Error::InvalidObject if the object already exists.

constructor(primary_key => value)

Instanciate the object using the primary key

Throws Oak::DBIEntity::Error::InvalidObject if the object does not exist.

Throws Oak::Error::ParamsMissing if neighter create of primary key passed.

List the objects in the relationship $relationshipname using $query as a complement to the SQL Returns an array with the objects.

In this method, the $query must not include the WHERE word.

Throws Oak::DBIEntity::Error::InexistentRelationship if an inexistent relationship is passed.

remove_relationship($relationshipname,$object)

Remove the reletionship between $object and this object.

Throws Oak::DBIEntity::Error::InexistentRelationship if an inexistent relationship is passed.

Throws Oak::DBIEntity::Error::InvalidObject if the passed object is not associated with this object

add_relationship($relationshipname,$object)

Add $object to $relationshipname.

Throws Oak::DBIEntity::Error::InexistentRelationship if an inexistent relationship is passed.

purge

Purge this object itself. Suicides...

This method will transverse the relationships, dispatching the on_delete methods. after this, it will delete itself.

ON_DELETE METHODS

The methods in this section can be specified in the on_delete attribute of a relationship.

on_delete_cascade($relationshipname): Delete all the objects in this relationship.

on_delete_restrict($relationshipname): Throws Oak::DBIEntity::Error::Restricted if there are objects in this relationship

on_delete_set_null($relationshipname): Defines the foreign_key of the objects in the relationship as NULL.

EXCEPTIONS

Oak::DBIEntity::Error::Restricted: Throwed by on_delete_restrict

Oak::DBIEntity::Error::InexistentRelationship: Throwed by list_related, add_relationship, remove_relationship when the passed relationship was not declared.

Oak::DBIEntity::Error::InvalidObject: Throwed by remove_relationship when the received object is not associated with this object.

COPYRIGHT

Copyright (c) 2001 Daniel Ruoso <daniel@ruoso.com> Carlos Eduardo de Andrade Brasileiro <eduardo@oktiva.com.br> All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Oak::DBIEntity - Class for DBI based entity classes