NAME

Fey::Object::Table - Base class for table-based objects

VERSION

version 0.47

SYNOPSIS

  package MyApp::User;

  use Fey::ORM::Table;

  has_table(...);

DESCRIPTION

This class is a the base class for all table-based objects. It implements a large amount of the core Fey::ORM functionality, including CRUD (create, update, delete) and loading of data from the DBMS.

METHODS

This class provides the following methods:

$class->new(...)

This method overrides the default Moose::Object constructor in order to implement cache management.

By default, object caching is disabled. In that case, this method lets its parent class do most of the work. However, unlike the standard Moose constructor, this method may sometimes not return an object. If it attempts to load object data from the DBMS and cannot find anything matching the parameters given to the constructor, it will return false.

If the constructor fails, you can check the value of $class->ConstructorError for the error message. This is done so that calling the constructor does not overwrite any value already in $@.

If caching is enabled, then this method will attempt to find a matching object in the cache. A match is determined by looking for an object which has a candidate key with the same values as are passed to the constructor.

If no match is found, it attempts to create a new object. If this succeeds, it stores it in the cache before returning it.

Constructor Parameters

The constructor accepts any attribute of the class as a parameter. This includes any column-based attributes, as well as any additional attributes defined by has_one() or has_many(). Of course, if you disabled caching for has_one() or has_many() relationships, then they are implemented as simple methods, not attributes.

If you define additional methods via Moose's has() function, and these will be accepted by the constructor as well.

Finally, the constructor accepts a parameter _from_query. This tells the constructor that the parameters passed to the constructor are the result of a SELECT. This stops the BUILD() method from attempting to load the object from the DBMS. However, you still must pass values for the primary key, so that the object is identifiable in the DBMS.

$class->ConstructorError()

If the constructor does not return an object, this will always contain the error message from the constructor. This should always be something like "Could not a find a row in SomeTable matching the values you provided to the constructor" or "Could not find a row in SomeTable where table_id = 42".

This error is cleared each time the class's constructor is called.

$class->EnableObjectCache()

$class->DisableObjectCache()

These methods enable or disable the object cache for the calling class.

$class->Count()

Returns the number of rows in the class's associated table.

$class->ClearObjectCache()

Clears the object cache for the calling class.

$class->Table()

Returns the Fey::Table object passed to has_table().

$class->SchemaClass()

Returns the name of the class associated with the class's table's schema.

$class->insert(%values)

Given a hash of column names and values, this method inserts a new row for the class's table, and returns a new object for that row.

The values for the columns can be plain scalars or object. Values will be passed through the appropriate deflators. You can also pass Fey::Literal objects of any type.

As an optimization, no object will be created in void context.

$class->insert_many( \%values, \%values, ... )

This method allows you to insert multiple rows efficiently. It expects an array of hash references. Each hash reference should contain the same set of column names as its keys. The advantage of using this method is that under the hood it uses the same DBI statement handle repeatedly. If you were to call $class->insert() repeatedly it would have to recreate the same SQL and DBI statement handle repeatedly.

In scalar context, it returns the first object created. In list context, it returns all the objects created.

As an optimization, no objects will be created in void context.

$object->update(%values)

This method accepts a hash of column keys and values, just like $class->insert(). However, it instead updates the values for an existing object's row. It will also make sure that the object's attributes are updated properly. In some cases, it will just clear the attribute, forcing it to be reloaded the next time it is accessed. This is necessary when the update value was a Fey::Literal, since that could be a function that gets interpreted by the DBMS, such as NOW().

$object->delete()

This method deletes the object's associated row from the DBMS.

The object is still usable after this method is called, but if you attempt to call any method that tries to access the DBMS it will probably blow up.

$object->pk_values_hash()

Returns a hash representing the names and values for the object's primary key. The values are returned in their raw form, regardless of any transforms specific for a primary key column.

This may return an empty hash if the primary key for the object has not yet been determined. This can happen if you try to call this method on an object before its attributes have been fetched from the dbms.

$object->pk_values_list()

Returns a list of values for the object's primary key. The values are returned in the same order as $self->primary_key() returns the columns. The values are returned in their raw form, regardless of any transforms specific for a primary key column.

This may return an empty list if the primary key for the object has not yet been determined.

METHODS FOR SUBCLASSES

Since your table-based class will be a subclass of this object, there are several methods you may want to use that are not intended for use outside of your subclasses. You may also want to subclass some of these methods in this class.

$class->_dbh($sql)

Given a Fey::SQL object, this method returns an appropriate DBI object for that SQL. Internally, it calls source_for_sql() on the schema class's Fey::DBIManager object and then calls $source->dbh() on the source.

If there is no source for the given SQL, it will die.

$object->_load_from_dbms($params)

This method will be called as part of object construction (unless _from_query was true).

By default, this method attempts to find a row in the associated table by looking at each of the table's candidate keys in turn. If the parameters passed to the constructor include values for all parts of a key, it does a select to find a matching row.

You can override this method in order to attempt to load an object based on some other method. For example, if your user table stores a username and a hashed password, you could accept an unhashed password, and then do a lookup based on the hashed value.

This method is expected to create a SELECT statement and then pass the statement and bind parameters to $object->_get_column_values().

On success, this method should simply return. If it fails, it should throw a Fey::Exception::NoSuchRow exception. See Fey::ORM::Exceptions for details.

$object->_get_column_values( $select, $bind_params )

This method takes a SELECT statement and an array reference of bind parameters. The SELECT is expected to find a single row, which should correspond to the current object. If it finds a row, it sets the corresponding attributes in the object based on the values returns by the SELECT.

AUTHOR

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 - 2015 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.