/ 
Oak-1.5
/ Oak::DBIEntity

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

GetDBIIO

Returns the Oak::IO::DBI object to be used with this class, 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 a 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.

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

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_related($relationshipname,$query)

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.