DBIx::DataModel::Doc::Misc(3)

NAME
DBIx::DataModel::Doc::Misc - Other considerations

DOCUMENTATION CONTEXT
This chapter is part of the "DBIx::DataModel" manual.

•   SYNOPSIS AND DESCRIPTION

•   DESIGN

•   QUICKSTART

•   REFERENCE

•   MISC

•   INTERNALS

•   GLOSSARY

NAMESPACES, CLASSES, METHODS
"DBIx::DataModel" automatically generates Perl classes for Schemas, Tables, Views, Associations. Before doing so, it checks that no Perl package of the same name already exists in memory. A similar check is performed before adding role methods into classes.

The client code can insert additional methods into the generated classes : just switch to the package and define your code. However, because of the security checks just mentioned, "DBIx::DataModel" must create the package before you start adding methods to it, and therefore the declarations should be inside a BEGIN block :

  BEGIN { # make sure these declarations are immediately executed

    DBIx::DataModel->Schema('MySchema');
    MySchema->Table(Activity   => Activity   => qw/act_id/);
    ...
  }

  # now we can safely add new methods

  package MySchema::Activity;

  sub activePeriod {
    my $self = shift;
    $self->{d_end} ? "from $self->{d_begin} to $self->{d_end}"
                   : "since $self->{d_begin}";
  }

  package main;                 # switch back to the 'main' package

See perlmod for an explanation of BEGIN blocks.

INTERACTION WITH THE DBI LAYER

  Transactions and error handling
"DBIx::DataModel" follows the recommendations of "DBI" for transactions : it expects the database handle to be opened with "RaiseError => 1" and therefore does not check itself for "DBI" errors ; it is up to the client code to catch the exceptions and deal with errors.

As explained in "Transactions" in DBI, "AutoCommit" should be set off for databases that support transactions; then atomic operations are enclosed in an "eval", followed by either "$dbh->commit()" (in case of success) or "$dbh->rollback()" (in case of failure). The doTransaction() method does all this for you automatically.

Calling DBI directly

Maybe you will encounter situations where you need to generate SQL yourself (for example because of clauses specific to your RDBMS), or to interact directly with the DBI layer. This can be encapsulated in additional methods incorporated into the classes generated by "DBIx::DataModel". In those methods, you may want to call blessFromDB() so that the rows returned by DBI may be seen as objects from your client program. Here is an example :

  package MyTable; # switch to namespace 'MyTable'

  sub fancyMethod {

    # call the DBI API
    my $hash = $dbh->selectall_hashref($fancySQL, @keyFields);

    # bless results into objects of My::Table
    My::Table->blessFromDB($_) foreach values %$hash;

    return $hash;
  }

SELF-REFERENTIAL ASSOCIATIONS
Associations can be self-referential, i.e. describing tree structures :

  MySchema->Association([qw/OrganisationalUnit parent   1 ou_id/],
                        [qw/OrganisationalUnit children * parent_ou_id/],

However, when there are several self-referential associations, we might get into problems : consider

  MySchema->Association([qw/Person mother   1 pers_id/],
                        [qw/Person children * mother_id/]);
  MySchema->Association([qw/Person father   1 pers_id/],
                        [qw/Person children * father_id/]); # BUG: children

This does not work because there are two definitions of the "children" role name in the same class "Person". One solution is to distinguish these roles, and then write by hand a general "children" role :

  MySchema->Association([qw/Person mother         1 pers_id/],
                        [qw/Person motherChildren * mother_id/]);
  MySchema->Association([qw/Person father         1 pers_id/],
                        [qw/Person fatherChildren * father_id/]);

  package MySchema::Person;
  sub children {
    my $self = shift;
    my $id = $self->{pers_id};
    my $sql = "SELECT * FROM Person WHERE mother_id = $id OR father_id = $id";
    my $children = $self->dbh->selectall_arrayref($sql, {Slice => {}});
    MySchema::Person->blessFromDB($_) foreach @$children;
    return $children;
  }

Alternatively, since rolenames "motherChildren" and "fatherChildren" are most probably useless, we might just specify unidirectional associations :

  MySchema->Association([qw/Person mother  1 pers_id/],
                        [qw/Person ---     * mother_id/]);
  MySchema->Association([qw/Person father  1 pers_id/],
                        [qw/Person ---     * father_id/]);

And here is a more sophisticated way to define the "children" method, that will accept additional "where" criteria, like every regular method.

  package MySchema::Person;
  sub children {
    my $self      = shift; # remaining args in @_ will be passed to select()
    my $id        = $self->{pers_id};
    my $statement = Person->createStatement(-where => [mother_id => $id,
                                                       father_id => $id]);
    return $statement->select(@_);
  }

This definition forces the join on "mother_id" or "father_id", while leaving open the possibility for the caller to specify additional criteria. For example, all female children of a person (either father or mother) can now be retrieved through

  $person->children(-where => {gender => 'F'})

Observe that "mother_id" and "father_id" are inside an arrayref instead of a hashref, so that SQL::Abstract will generate an SQL 'OR'.