Dave Rolsky > Fey-ORM-0.45 > Fey::Object::Iterator::FromSelect

Download:
Fey-ORM-0.45.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
Stalled  1
View/Report Bugs
Module Version: 0.45   Source   Latest Release: Fey-ORM-0.46

NAME ^

Fey::Object::Iterator::FromSelect - Wraps a DBI statement handle to construct objects from the results

VERSION ^

version 0.45

SYNOPSIS ^

  use Fey::Object::Iterator::FromSelect;

  my $iter = Fey::Object::Iterator::FromSelect->new(
      classes     => 'MyApp::User',
      select      => $select,
      dbh         => $dbh,
      bind_params => \@bind,
  );

  print $iter->index();    # 0

  while ( my $user = $iter->next() ) {
      print $iter->index();    # 1, 2, 3, ...
      print $user->username();
  }

  $iter->reset();

DESCRIPTION ^

This class implements an iterator on top of a DBI statement handle. Each call to next() returns one or more objects based on the data returned by the statement handle.

METHODS ^

This class provides the following methods:

Fey::Object::Iterator::FromSelect->new(...)

This method constructs a new iterator. It accepts the following parameters:

$iterator->index()

This returns the current index value of the iterator. When the object is first constructed, this index is 0, and it is incremented once for each row fetched by calling $iterator->next().

$iterator->next()

This returns the next set of objects, based on data retrieved by the query. In list context this returns all the objects. In scalar context it returns the first object.

It is possible that one or more of the objects it returns will be undefined, though this should really only happen with an outer join. The statement handle will be executed the first time this method is called.

If the statement handle is exhausted, this method returns false.

$iterator->remaining()

This returns all of the remaining sets of objects. If the iterator is for a single class, it returns a list of objects of that class. If it is for multiple objects, it returns a list of array references.

$iterator->all()

This returns all of the sets of objects. If necessary, it will call $iterator->reset() first. If the iterator is for a single class, it returns a list of objects of that class. If it is for multiple objects, it returns a list of array references.

$iterator->next_as_hash()

Returns the next set of objects as a hash. The keys are the names of the object's associated table.

If the statement handle is exhausted, this method returns false.

This method will throw an exception unless all of the iterator's classes have a Table() method.

$iterator->remaining_as_hashes()

This returns all of the remaining sets of objects as a list of hash references. Each hash ref is keyed on the table name of the associated object's class.

This method will throw an exception unless all of the iterator's classes have a Table() method.

$iterator->all_as_hashes()

This returns all of the sets of objects as a list of hash references. If necessary, it will call $iterator->reset() first. Each hash ref is keyed on the table name of the associated object's class.

This method will throw an exception unless all of the iterator's classes have a Table() method.

$iterator->reset()

Resets the iterator so that the next call to $iterator->next() returns the first objects. Internally this means that the statement handle will be executed again. It's possible that data will have changed in the DBMS since then, meaning that the iterator will return different objects after a reset.

$iterator->raw_row()

Returns an array reference containing the raw data returned by the query on the most recent call to $iterator->next(). Once the iterator is exhausted, this method returns undef.

$iterator->DEMOLISH()

This method will call $sth->finish() on its DBI statement handle if necessary.

ATTRIBUTE MAPPING ^

This class tries to automatically map each element of the SELECT clause to a class's attribute. You can also provide your own explicit mappings as needed.

In the absence of an explicit mapping, it checks to see if the element has a table() method. If it does, it calls Fey::Meta::Class::Table->ClassForTable in order to get a class name for the table. Then it uses the value of name() (for column objects) or alias_name() (for column alias objects) as the name of the attribute to be passed to the class's constructor.

If the class is not listed in the iterator's "classes" attribute, then it will simply be ignored.

If the element does not have a table() method or an explicit mapping, it is ignored.

This default works for most queries, where you're just selecting some or all of the columns from one or more tables.

In more exotic cases, you can specify an explicit mapping. The mapping maps a SELECT clause element to a specify class's attribute. The map would look something like this:

  Fey::Object::Iterator::FromSelect->new
      ( classes       => [ 'User', 'Message' ],
        dbh           => $dbh,
        select        => $select,
        attribute_map => { 0 => { class     => 'User',
                                  attribute => 'user_id',
                                },
                           1 => { class     => 'User',
                                  attribute => 'username',
                                },
                           3 => { class     => 'Message',
                                  attribute => 'message_id',
                                },
                         },
      );

The keys in the mapping are positions in the list of SELECT clause elements. The numbers start from zero (0) just like a Perl array. The values are themselves a hash reference specifying a "class" and "attribute" of that class.

This explicit mapping is useful for more "exotic" queries. For example:

  SELECT   Message.user_id, COUNT(message_id) AS message_count
    FROM   Message
  ORDER BY message_count DESC
  GROUP BY user_id
     LIMIT 10

This query selects to the top 10 most frequent message posters from a Message table. Assuming our User class has a message_count attribute, we'd like to create a list of User objects from this query.

  Fey::Object::Iterator::FromSelect->new
      ( classes       => [ 'User', 'Message' ],
        dbh           => $dbh,
        select        => $select,
        attribute_map => { 0 => { class     => 'User',
                                  attribute => 'user_id',
                                },
                           1 => { class     => 'User',
                                  attribute => 'message_count',
                                },
      );

Explicit mappings to classes not listed in the "classes" attribute cause an error at object construction time.

ROLES ^

This class does the Fey::ORM::Role::Iterator role.

AUTHOR ^

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE ^

This software is copyright (c) 2011 by Dave Rolsky.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

syntax highlighting: