File Coverage

blib/lib/Rose/DB/Object/Std.pm
Criterion Covered Total %
statement 9 10 90.0
branch n/a
condition n/a
subroutine 3 4 75.0
pod 1 1 100.0
total 13 15 86.6


line stmt bran cond sub pod time code
1             package Rose::DB::Object::Std;
2              
3 2     2   847158 use strict;
  2         10  
  2         64  
4              
5 2     2   932 use Rose::DB::Object::Std::Metadata;
  2         7  
  2         75  
6              
7 2     2   1731 use Rose::DB::Object;
  2         6  
  2         191  
8             our @ISA = qw(Rose::DB::Object);
9              
10             our $VERSION = '0.021';
11              
12             our $Debug = 0;
13              
14             #
15             # Class methods
16             #
17              
18 0     0 1   sub meta_class { 'Rose::DB::Object::Std::Metadata' }
19              
20             #
21             # Object methods
22             #
23              
24             # Better to leave this up to the database...
25             # sub insert
26             # {
27             # my($self) = shift;
28             #
29             # my $meta = $self->meta;
30             #
31             # if($meta->column('date_created'))
32             # {
33             # $self->date_created('now') unless($self->date_created);
34             # }
35             #
36             # if($meta->column('last_modified'))
37             # {
38             # $self->last_modified('now');
39             # }
40             #
41             # $self->SUPER::insert(@_);
42             # }
43             #
44             # sub update
45             # {
46             # my($self) = shift;
47             #
48             # if($self->meta->column('last_modified'))
49             # {
50             # $self->last_modified('now');
51             # }
52             #
53             # $self->SUPER::update(@_);
54             # }
55              
56             1;
57              
58             __END__
59              
60             =head1 NAME
61              
62             Rose::DB::Object::Std - Standardized object representation of a single row in a database table.
63              
64             =head1 SYNOPSIS
65              
66             package Category;
67              
68             use base 'Rose::DB::Object::Std';
69              
70             __PACKAGE__->meta->setup
71             (
72             table => 'categories',
73              
74             columns =>
75             [
76             id => { type => 'int', primary_key => 1 },
77             name => { type => 'varchar', length => 255 },
78             description => { type => 'text' },
79             ],
80              
81             unique_key => 'name',
82             );
83              
84             ...
85              
86             package Product;
87              
88             use base 'Rose::DB::Object::Std';
89              
90             __PACKAGE__->meta->setup
91             (
92             table => 'products',
93              
94             columns =>
95             [
96             id => { type => 'int', primary_key => 1 },
97             name => { type => 'varchar', length => 255 },
98             description => { type => 'text' },
99             category_id => { type => 'int' },
100              
101             status =>
102             {
103             type => 'varchar',
104             check_in => [ 'active', 'inactive' ],
105             default => 'inactive',
106             },
107              
108             start_date => { type => 'datetime' },
109             end_date => { type => 'datetime' },
110              
111             date_created => { type => 'timestamp', default => 'now' },
112             last_modified => { type => 'timestamp', default => 'now' },
113             ],
114              
115             unique_key => 'name',
116              
117             foreign_keys =>
118             [
119             category =>
120             {
121             class => 'Category',
122             key_columns => { category_id => 'id' },
123             },
124             ],
125             );
126              
127             ...
128              
129             $product = Product->new(name => 'GameCube',
130             status => 'active',
131             start_date => '11/5/2001',
132             end_date => '12/1/2007',
133             category_id => 5);
134              
135             $product->save or die $product->error;
136              
137             $id = $product->id; # auto-generated on save
138              
139             ...
140              
141             $product = Product->new(id => $id);
142             $product->load or die $product->error;
143              
144             print $product->category->name;
145              
146             $product->end_date->add(days => 45);
147              
148             $product->save or die $product->error;
149              
150             ...
151              
152             =head1 DESCRIPTION
153              
154             L<Rose::DB::Object::Std> is a subclass of L<Rose::DB::Object> that imposes a few more constraints on the tables it fronts. In addition to the constraints described in the L<Rose::DB::Object> documentation, tables fronted by L<Rose::DB::Object::Std> objects must also fulfill the following requirements:
155              
156             =over 4
157              
158             =item * The table must have a single primary key column named "id"
159              
160             =item * The value of the "id" column must be auto-generated if absent.
161              
162             =back
163              
164             Different databases provide for auto-generated column values in different ways. Some provide a native "auto-increment" or "serial" data type, others use sequences behind the scenes.
165              
166             L<Rose::DB::Object::Std> (in cooperation with L<Rose::DB> and L<Rose::DB::Object::Std::Metadata>) attempts to hide these details from you. All you have to do is omit the value for the primary key entirely. After the object is C<save()>ed, you can retrieve the auto-selected primary key by calling the C<id()> method.
167              
168             You do have to correctly define the "id" column in the database, however. Here are examples of primary key column definitions that provide auto-generated values, one for each of the databases supported by L<Rose::DB>.
169              
170             =over
171              
172             =item * PostgreSQL
173              
174             CREATE TABLE mytable
175             (
176             id SERIAL NOT NULL PRIMARY KEY,
177             ...
178             );
179              
180             =item * MySQL
181              
182             CREATE TABLE mytable
183             (
184             id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
185             ...
186             );
187              
188             =item * Informix
189              
190             CREATE TABLE mytable
191             (
192             id SERIAL NOT NULL PRIMARY KEY,
193             ...
194             );
195              
196             =back
197              
198             Other data definitions are possible, of course, but the three definitions above are used in the L<Rose::DB::Object::Std> test suite and are therefore guaranteed to work. If you have success with alternative approaches, patches and/or new tests are welcome.
199              
200             To achieve much of this functionality, L<Rose::DB::Object::Std> uses L<Rose::DB::Object::Std::Metadata> objects. The C<meta()> method will create these form you. You should not need to do anything special if you use the idiomatic approach to defining metadata as shown in the L<synopsis|/SYNOPSIS>.
201              
202             =head1 METHODS
203              
204             Only the methods that are overridden are documented here. See the L<Rose::DB::Object> documentation for the rest.
205              
206             =over 4
207              
208             =item B<meta>
209              
210             Returns the L<Rose::DB::Object::Std::Metadata> object associated with this class. This object describes the database table whose rows are fronted by this class: the name of the table, its columns, unique keys, foreign keys, etc. See the L<Rose::DB::Object::Std::Metadata> documentation for more information.
211              
212             This can be used as both a class method and an object method.
213              
214             =back
215              
216             =head1 AUTHOR
217              
218             John C. Siracusa (siracusa@gmail.com)
219              
220             =head1 LICENSE
221              
222             Copyright (c) 2010 by John C. Siracusa. All rights reserved. This program is
223             free software; you can redistribute it and/or modify it under the same terms
224             as Perl itself.