Please consider doing a bit of code review of MyLibrary::Librarian.pm. At the risk of giving people information overload, I have attached my first public draft of Librarian.pm, a Perl package enabling programmers to create, edit, delete, and find librarians in an underlying MyLibrary database, without having to know the database's structure.
If you have copious spare time, I am hoping you could take a look at the attached file and tell me if it make sense to you as well as how it might be improved. -- Eric "Trying To Get Many Eyes" Morgan University Libraries of Notre Dame (574) 631-8604
Librarian.pm
Description: application/applefile
package MyLibrary::Librarian;
use MyLibrary::DB;
use Carp qw(croak);
use strict;
=head1 NAME
MyLibrary::Librarian
=head1 SYNOPSIS
# use the module
use MyLibrary::Librarian;
# create a new librarian
my $librarian = MyLibrary::Librarian->new;
# give the librarian characteristics
$librarian->name('Fred Kilgour');
$librarian->email('[EMAIL PROTECTED]');
$librarian->telephone('1 (800) 555-1212');
$librarian->url('http://oclc.org/~kilgour/');
# associate (classify) the librarian with term ids
$librarian->term_ids(3, 614, 601);
# save the librarian to the database; create a new record
$librarian->commit;
# get the id of the current librarian object
$id = $librarian->librarian_id;
# get a librarian based on an id
my $librarian = MyLibrary::Librarian->new(id => $id);
# display information about the librarian
print ' ID: ', $librarian->librarian_id, "\n";
print ' Name: ', $librarian->name, "\n";
print ' Email: ', $librarian->email, "\n";
print 'Telephone: ', $librarian->telephone, "\n";
print ' URL: ', $librarian->url, "\n";
# get all librarians
my @librarians = MyLibrary::Librarian->get_librarians;
# process each librarian
foreach my $l (@librarians) {
# print each librarian's name and email address
print $l->name, ' <', $l->email, "> \n";
}
=head1 DESCRIPTION
Use this module to get and set the characteristics of librarians to a MyLibrary
database. Characteristics currently include: ID (primary database key), name, email
address, telephone number, home page URL, and a set of integers (primary database
keys) denoting what terms the librarian has been classified under.
=head1 METHODS
This section describes the methods available in the package.
=head2 new
Use this method to create a librarian object. Called with no options, this method
creates an empty object. Called with an id option, this method uses the id as a
database key and fills the librarian object with data from the underlying database.
# create a new librarian object
my $librarian = MyLibrary::Librarian->new;
# create a librarian object based on a previously existing ID
my $librarian = MyLibrary::Librarian->new(id => 3);
=head2 librarian_id
This method returns an integer representing the database key of the currently created
librarian object.
# get id of current librarian object
my $id = $librarian->librarian_id;
You cannot set the librarian_id attribute.
=head2 name
This method gets and sets the name from the librarian from the current librarian
object:
# get the name of the current librarian object
my $name = $librarian->name;
# set the current librarian object's name
$librarian->name('Melvile Dewey');
=head2 telephone
Use this method to get and set the telephone number of the current librarian object:
# get the telephone number
my $phone = $librarian->telephone;
# set the current librarian object's telephone number
$librarian->telephone('1 (800) 555-1212');
=head2 email
Like the telephone and name methods, use this method to get and set the librarian
object's email attribute:
# get the email address
my $email_address = $librarian->email;
# set the current librarian object's email address
$librarian->email('[EMAIL PROTECTED]');
=head2 url
Set or get the URL attribute of the librarian object using this method:
# get the URL attribute
my $home_page = $librarian->url;
# set the URL
$librarian->url('http://dewey.library.nd.edu/');
=head2 term_id
This method gets and sets the database keys denoting how this librarian object is
classified. Given no input, it returns a list of integers. Any input give is expected
to be a list of integers.
# set the term id's
$librarian->term_id(33, 24, 83);
# get the term id's of the current librarian object
my @ids = librarian->term_id;
# require the Term package
use MyLibrary::Term;
# process each id
foreach my $i (@ids) {
# create a term object
my $term->MyLibrary::Term->new(id => $i);
# print the term associated with the librarian object
print $librarian-name, ' has been classified with the term: ',
$term->name, ".\n";
}
=head2 commit
Use this method to save the librarian object's attributes to the underlying database.
If the object's data has never been saved before, then this method will create a new
record in the database. If you used the new and passed it an id option, then this
method will update the underlying database.
This method will return true upon success.
# save the current librarian object to the underlying database
$librarian->commit;
=head2 delete
This method simply deletes the current librarian object from the underlying database.
# delete (drop) this librarian from the database
$librarian->delete();
=head2 get_librarians
Use this method to get all the librarians from the underlying database. This method
returns an array of objects enabling you to loop through each object in the array and
subsequent characteristics of each object;
# get all librarians
my @librarians = MyLibrary::Librarian->get_librarians;
# process each librarian
foreach my $l (@librarians) {
# print the name
print $l->name, "\n";
}
=head1 AUTHOR
Eric Lease Morgan <[EMAIL PROTECTED]>
=head1 HISTORY
September 29, 2003 - first public release.
=cut
sub new {
# declare local variables
my ($class, %opts) = @_;
my $self = {};
my @term_ids = ();
# check for an id
if ($opts{id}) {
# get a handle
my $dbh = MyLibrary::DB->dbh();
# find this record
my $rv = $dbh->selectrow_hashref('SELECT * FROM librarians WHERE
librarian_id = ?', undef, $opts{id});
# check for success
if (ref($rv) eq "HASH") {
# fill myself up with the fetched data
$self = bless ($rv, $class);
# get the term_ids for this librarian
my $rows = $dbh->prepare ("SELECT term_id FROM
items4librarians WHERE librarian_id = " . $opts{id});
$rows->execute;
# process each row
while (my $r = $rows->fetchrow_array) {
# push the value onto an array
push (@term_ids, $r)
}
# add the term ids to the object
$self->term_ids(@term_ids);
}
# return nothing
else { return }
}
# return the object
return bless ($self, $class);
}
sub librarian_id {
my $self = shift;
return $self->{librarian_id};
}
sub telephone {
# declare local variables
my ($self, $telephone) = @_;
# check for the existance of a telephone number
if ($telephone) { $self->{telephone} = $telephone }
# return it
return $self->{telephone};
}
sub name {
# declare local variables
my ($self, $name) = @_;
# check for the existance of a name
if ($name) { $self->{name} = $name }
# return it
return $self->{name};
}
sub email {
# declare local variables
my ($self, $email) = @_;
# check for the existance of an email address
if ($email) { $self->{email} = $email }
# return it
return $self->{email};
}
sub term_ids {
# get myself and then the ids
my $self = shift;
my @ids = @_;
# check for ids and stuff them into the attribute
if (@ids) { $self->{term_ids} = [EMAIL PROTECTED] }
# return a dereferenced array
return @{$self->{term_ids}};
}
sub url {
# declare local variables
my ($self, $url) = @_;
# check for the existance of librarian's url
if ($url) { $self->{url} = $url }
# return it
return $self->{url};
}
sub commit {
# get myself, :-)
my $self = shift;
# get a database handle
my $dbh = MyLibrary::DB->dbh();
# see if the object has an id
if ($self->librarian_id()) {
# update the librarians table with this id
my $return = $dbh->do('UPDATE librarians SET name = ?, telephone = ?,
email = ?, url = ? WHERE librarian_id = ?', undef, $self->name(), $self->telephone(),
$self->email(), $self->url(), $self->librarian_id());
if ($return != 1) { croak "Librarian update in commit() failed.
$return records were updated." }
# delete records in the items4librarians table for this librarian
$return = $dbh->do('DELETE FROM items4librarians WHERE librarian_id =
?', undef, $self->librarian_id);
if ($return != 1) { croak "Librarian update in commit() failed. Unable
to delete from items4librarians. $return records were updated." }
# recreate join records in items4librarians
foreach ($self->term_ids) {
$return = $dbh->do('INSERT INTO items4librarians (term_id,
librarian_id) values (?, ?)', undef, $_, $self->librarian_id);
if ($return != 1) { croak "Librarian update in commit()
failed. Unable to insert into items4librarians. $return records were updated." }
}
}
else {
# get a new sequence
my $id = MyLibrary::DB->nextID();
# create a new record
my $return = $dbh->do('INSERT INTO librarians (librarian_id, name,
telephone, email, url) VALUES (?, ?, ?, ?, ?)', undef, $id, $self->name(),
$self->telephone(), $self->email(), $self->url());
if ($return != 1) { croak 'Librarian commit() failed.'; }
$self->{librarian_id} = $id;
# create join records in items4librarians
foreach ($self->term_ids) {
$return = $dbh->do('INSERT INTO items4librarians (term_id,
librarian_id) values (?, ?)', undef, $_, $self->librarian_id);
if ($return != 1) { croak "Librarian update in commit()
failed. Unable to insert into items4librarians. $return records were updated." }
}
}
# done
return 1;
}
sub delete {
my $self = shift;
if ($self->{librarian_id}) {
my $dbh = MyLibrary::DB->dbh();
my $rv = $dbh->do('DELETE FROM librarians WHERE librarian_id = ?',
undef, $self->{librarian_id});
if ($rv != 1) { croak ("Deleted $rv records. I'll bet this isn't what
you wanted.") }
return 1;
}
return 0;
}
sub get_librarians {
# scope varibles
my $self = shift;
my @rv = ();
# create and execute a query
my $dbh = MyLibrary::DB->dbh();
my $rows = $dbh->prepare('SELECT librarian_id FROM librarians');
$rows->execute;
# process each found row
while (my $r = $rows->fetchrow_array) {
# fill up the return value
push(@rv, $self->new(id => $r));
}
# return the array
return @rv;
}
# return true, or else
1;
