From 5b076ae9e5e46d440ace2550edff2d72e1d16622 Mon Sep 17 00:00:00 2001 From: JT Smith Date: Sat, 14 Jan 2006 22:22:51 +0000 Subject: [PATCH] oops, forgot to check this in a long time ago --- lib/WebGUI/SQL/ResultSet.pm | 299 ++++++++++++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 lib/WebGUI/SQL/ResultSet.pm diff --git a/lib/WebGUI/SQL/ResultSet.pm b/lib/WebGUI/SQL/ResultSet.pm new file mode 100644 index 000000000..dc1c6de11 --- /dev/null +++ b/lib/WebGUI/SQL/ResultSet.pm @@ -0,0 +1,299 @@ +package WebGUI::SQL::ResultSet; + +=head1 LEGAL + + ------------------------------------------------------------------- + WebGUI is Copyright 2001-2006 Plain Black Corporation. + ------------------------------------------------------------------- + Please read the legal notices (docs/legal.txt) and the license + (docs/license.txt) that came with this distribution before using + this software. + ------------------------------------------------------------------- + http://www.plainblack.com info@plainblack.com + ------------------------------------------------------------------- + +=cut + +use strict; + +=head1 NAME + +Package WebGUI::SQL::ResultSet + +=head1 DESCRIPTION + +This class provides methods for working with SQL result sets. If you're used to working with Perl DBI, then the object returned here is similar to a statement handler. + +=head1 SYNOPSIS + + use WebGUI::SQL::ResultSet; + + my $result = WebGUI::SQL::ResultSet->prepare($query, $db); + + $result->execute([ @values ]); + + @arr = $result->array; + @arr = $result->getColumnNames; + %hash = $result->hash; + $hashRef = $result->hashRef; + $num = $result->rows; + $result->finish; + +=head1 METHODS + +These methods are available from this package: + +=cut + + +#------------------------------------------------------------------- + +=head2 array ( ) + +Returns the next row of data as an array. + +=cut + +sub array { + my $self = shift; + return $self->sth->fetchrow_array() or $self->db->session->errorHandler->fatal("Couldn't fetch array. ".$self->errorMessage); +} + + +#------------------------------------------------------------------- + +=head2 errorCode { + +Returns an error code for the current handler. + +=cut + +sub errorCode { + my $self = shift; + return $self->sth->err; +} + + +#------------------------------------------------------------------- + +=head2 errorMessage { + +Returns a text error message for the current handler. + +=cut + +sub errorMessage { + my $self = shift; + return $self->sth->errstr; +} + + +#------------------------------------------------------------------- + +=head2 execute ( [ placeholders ] ) + +Executes a prepared SQL statement. + +=head3 placeholders + +An array reference containing a list of values to be used in the placeholders defined in the SQL statement. + +=cut + +sub execute { + my $self = shift; + my $placeholders = shift || []; + my $sql = $self->{_sql}; + $self->sth->execute(@{$placeholders}) or $self->db->session->errorHandler->fatal("Couldn't execute prepared statement: $sql Root cause: ". $self->errorMessage); +} + + +#------------------------------------------------------------------- + +=head2 finish ( ) + +Releases the result set. Should be called to complete any statement handler. + +=cut + +sub finish { + my $self = shift; + return $self->sth->finish; +} + + +#------------------------------------------------------------------- + +=head2 getColumnNames { + +Returns an array of column names. Use with a "read" method. + +=cut + +sub getColumnNames { + my $self = shift; + return @{$self->sth->{NAME}} if (ref $self->sth->{NAME} eq 'ARRAY'); +} + + +#------------------------------------------------------------------- + +=head2 hash ( ) + +Returns the next row of data in the form of a hash. + +=cut + +sub hash { + my $self = shift; + my ($hashRef); + $hashRef = $self->sth->fetchrow_hashref(); + if (defined $hashRef) { + return %{$hashRef}; + } else { + return (); + } +} + + +#------------------------------------------------------------------- + +=head2 hashRef ( ) + +Returns the next row of data in the form of a hash reference. + +=cut + +sub hashRef { + my $self = shift; + my ($hashRef, %hash); + $hashRef = $self->sth->fetchrow_hashref(); + if (defined $hashRef) { + return $hashRef; + } else { + return {}; + } +} + + +#------------------------------------------------------------------- + +=head2 prepare ( sql, db ) { + +Constructor. Returns a result set statement handler. + +=head3 sql + +An SQL statement. Can use the "?" placeholder for maximum performance on multiple statements with the execute method. + +=head3 db + +A WebGUI::SQL database handler. + +=cut + +sub prepare { + my $class = shift; + my $sql = shift; + my $db = shift; + $db->session->errorHandler->debug("query: ".$sql); + my $sth = $db->dbh->prepare($sql) or $db->session->errorHandler->fatal("Couldn't prepare statement: ".$sql." : ". $db->dbh->errstr); + bless ({_sth => $sth, _sql => $sql, _db=>$db}, $class); +} + + +#------------------------------------------------------------------- + +=head2 read ( sql, db, placeholders ) + +Constructor. Returns a result set statement handler. + +=head3 sql + +An SQL query. Can use the "?" placeholder for maximum performance on multiple statements with the execute method. + +=head3 db + +A WebGUI::SQL database handler. + +=head3 placeholders + +An array reference containing a list of values to be used in the placeholders defined in the SQL statement. + +=cut + +sub read { + my $class = shift; + my $sql = shift; + my $db = shift; + my $placeholders = shift; + my $sth = $db->prepare($sql, $db); + $sth->execute($placeholders); + bless {_db=>$db, _sql=>$sql, _sth=>$sth}, $class; +} + +#------------------------------------------------------------------- + +=head2 rows ( ) + +Returns the number of rows in the result set. + +=cut + +sub rows { + my $self = shift; + return $self->sth->rows; +} + +#------------------------------------------------------------------- + +=head2 sth ( ) + +Returns the working DBI statement handler for this result set. + +=cut + +sub sth { + my $self = shift; + return $self->{_sth}; +} + + + +#------------------------------------------------------------------- + +=head2 unconditionalRead ( sql, db, placeholders ) + +Constructor. This is the same as the read method, except that it doesn't throw a fatal error if the query fails. + +=head3 sql + +An SQL query. + +=head3 db + +A WebGUI::SQL database handler. + +=head3 placeholders + +An array reference containing a list of values to be used in the placeholders defined in the SQL statement. + +=cut + +sub unconditionalRead { + my $class = shift; + my $sql = shift; + my $db = shift; + my $placeholders = shift; + $db->session->errorHandler->debug("query: ".$sql); + my $sth = $db->dbh->prepare($sql) or $db->session->errorHandler->warn("Unconditional read failed: ".$sql." : ".$db->dbh->errstr); + if ($sth) { + $sth->execute(@$placeholders) or $db->session->errorHandler->warn("Unconditional read failed: ".$sql." : ".$sth->errstr); + bless ({_sth => $sth, _sql=>$sql, _db=>$db} , $class); + } else { + return undef; + } +} + +1; +