|disconnect||Class or instance method. You can pass in a handle or this will call db_Main to get the standard one. In either case, it will rollback any current transaction (if you arent auto-committing) and disconnect the handle.|
|dbi_commit||Class or instance method. By default the dbh managed by this module has AutoCommit off. Call this to commit your transactions.|
|construct||Class method. Mainly for internal use. This method takes a hash (usually one bound to a statement handle) and turns it into an object of the subclass through which it was called.|
|special_sql||Class method. Accepts sql SELECT statements returns a list (not a reference or iterator) of objects in the class through which it was called. Be careful with column names, they need to be the genuine names of columns in the underlying table.|
|retrieve_all||Class method. Pass a list of key/value pairs or a single hash ref. The only legal key is order_by, its value will be used literally directly after ORDER BY (that means, dont include the ORDER BY keywords in your value). Returns a list of objects.|
|retrieve_by_pk||Class method. Pass a single primary key value. Returns the row with that primary key value as an object or undef if no such row is found.|
|retrieve||Class method. Similar to retrieve in Class::DBI. If called with one argument, that argument is taken as a primary key and the request is forwarded to retrieve_by_pk. If called with multiple arguments (or no arguments), those arguments are forwarded to search.|
Class method. Similar to search in Class::DBI. Call with the key/value
pairs you want to match in a simple list.
Returns a list of objects one each for every row that matched the search criterion.
Add a single hash reference as the last parameter if you like. That hash reference may only contain these keys:
|page||A synonymn for search to better match the Class::DBI::Sweet API. Note that you must set the rows key in the hash reference passed as the last argument. You may also set the page key. See above.|
|lazy_fetch||Instance method. Call with the column name you want to fetch. Returns nothing useful, but sets the column with the value from the corresponding row in the underlying table.|
|create||Class method. Call with a hash reference whose keys are the column names you want to populate. The value will be quoted for you according to the corresponding quote_* method in the subclass.|
|_next_primary_key||Class method. Returns the next value of the sequence associated with the underlying table. This is not reproduceable, it actually increments the sequence. It only works if the database is using a sequence for the table and the model implements get_sequence_name.|
|find_or_create||Class method. Call with a hash reference of search criteria (think of a WHERE clause). First, it calls search, taking a single resulting object. If that works, you get the object. Otherwise, it calls create with your hash reference and returns the new object.|
|update||Instance method. Issues an UPDATE to SET the dirty values from the invocant. Returns nothing useful, although it could die if the dbh has problems.|
|delete||Instance method. Deletes the underlying row from its table and renders the invocant reference unusable.|
|get||Instance method. Call with a list of columns whose values you want. Returns the values in the invocant for the columns you requested. If you requested only one column a scalar is returned. Otherwise, you get a list.|
|set||Instance method. Call with a list of key/value pairs for columns that you want to change. Returns nothing useful.|
|quote_attribute||Instance method. Primarily for internal use. Call with a column name. Returns the value in the column quoted so SQL will take it.|
|quote_scalar||Class or instance method. Call with a column name and a value. Returns the value quoted for SQL as if it were stored in the column of an object. Even if you call this as an instance method, the instance values are not used.|
|get_db_options||Subclasses are welcome to override this with a meaningful routine. The one here returns an empty hash reference. Yours should provide data given as extra options to DBI during connection.|
|stringify_self||Returns the id of the row.|
You can include any useful method you like in your subclass, but these are the ones this module needs.
get_table_name Return the name of the table in the database that your class models. get_sequence_name Return the name of the sequence associated with your table. This is needed for the create method. get_essential_cols Return an array reference containing the columns you want to fetch automatically during retrieve, search, etc. get_primary_col We assume that each table has a unique primary key (though we assume nothing about its name). Return the name of that column. get_primary_key An instance method. Return the value of the primary key for the invocant. set_COL_NAME Provide one of these for each column. Called on an existing object with a new value. It must store the value in the objects hash (whose keys are the column labels) AND set the dirty flag for the column so that eventual updates will be effective. Some callers may expect to receive the new value in return, document whether it returns that value or not. Example: get_COL_NAME Provide one of these for each column. Return the unquoted value in the column. Example: quote_COL_NAME Called as a class or instance method with one argument. Take that argument, hold it up to the light, examine in detail. Then return something that has the same value properly quoted for SQL.
Note that you should not look in the object, even if one is used as the invocant. Always only work on the other argument.
COL_NAME (completely optional) Provide one of these for each column only if you like. Dispatch to get_ and set_ methods based on the arguments you receive. These methods are NEVER called internally, but your callers might like them. Example (with apologies to Dr. Conway):
There is no caching. This means two things: (1) no sql statement is prepared with bind parameter place holders and stored for possible reuse (2) objects are always built for each row retrieved, even if there is a live object for that row elsewhere in memory.
There are no triggers. If you need these, put them in the accessors as needed. Feel free to override construct.
There are no iterators. Class::DBI makes iterators, but they only delay object instantiation, the full query results are pulled from the beginning. Replicating that behavior seems like the pursuit of diminishing returns.
Phil Crow <firstname.lastname@example.org>
Copyright (c) 2006, Phil Crow.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.
|perl v5.20.3||GANTRY::UTILS::MODEL (3)||2016-04-03|