POE::Component::LaDBI::Response - Class encapsulating responses from

POE-Component-LaDBI documentation Contained in the POE-Component-LaDBI distribution.

Index

Code Index:

NAME

Top

POE::Component::LaDBI::Response - Class encapsulating responses from POE::Component::LaDBI::Engine.

SYNOPSIS

Top

  use POE::Component::LaDBI::Response;

  $resp = POE::Component::LaDBI::Response->new
           (Code     => 'OK',
	    HandleId => $sth_id,
	    Id       => $request_id,
	    DataType => 'TABLE',
	    Data     => $fetchall_arrayref_ret);

  $resp->code;
  $resp->handle_id;
  $resp->id;
  $resp->datatype;
  $resp->data;

  $resp->id;

DESCRIPTION

Top

$resp->new()

Args:

For the keys, capitalization does not matter. Internally the keys are lowercased.

Code

String identifier representing the error result of the request.

Valid Code values are:

OK

The POE::Component::LaDBI::Request succeeded as far as POE::Component::LaDBI::Engine is concerned.

FAILED

The POE::Component::LaDBI::Request failed. DataType will be set to either ERROR or EXCEPTION.

INVALID_HANDLE_ID

The POE::Component::LaDBI::Engine instance does not have a record of the $request-handle_id>.

Id

This is the unique cookie from the POE::Component::LaDBI::Request ($req-id>) this POE::Component::LaDBI::Response object corresponds to. There is a one for one relationship between requests and responses.

DataType

The type of data returned in Data. If you are constucting a POE::Component::LaDBI::Response object you must supply this field. However, if you are just useing the POE::Component::LaDBI::Response object returned from POE::Component::LaDBI::Engine::request() you can usually ignore this field. This is because all requests have a fixed and known response data type.

TABLE

Data is an array ref of array refs to scalars.

  Data = [ [row0col0, row0col1, ...],
           [row1col0, row1col1, ...],
           ...
         ]
NAMED_TABLE

This one is odd. See the description of selectall_hashref() in DBI. For *_hashref() calls in DBI you have to provide the database table field which will be the hash key into this hash table. The values corresponding to each key is a hash of the rows returned from the select or fetch. I did not invent this and do not quite understand why.

  Data = {
          row0colX_val => {col0_name => row0_val, col1_name => row0_val, ...},
	  row1colX_val => {col0_name => row1_val, col1_name => row1_val, ...},
           ...
         }
ROW

Data is an array ref of scalars.

  Data = [ elt0, elt1, ... ]
NAMED_ROW

Data is an hash ref containing name-value pairs of each data item in the row; the name is the column name, the value is the column value.

  Data = { col0_name => elt0, col1_name => elt1, ... }
COLUMN
  Data = [ elt0, elt1, ... ]
RC

Return code is a scalar valude returned from the DBI call.

  Data = $rc
RV

Return Value is a scalar value returned from the DBI call.

  Data = $rv
SQL

This is the data type for the return value from DBI::quote() call.

  Data = $sql_string
ERROR

There was an error for the DBI call. This indicates the DBI call returned undef. The data value is a hash ref with two keys 'err' and 'errstr'. These keys corresponed to the DBI calls of the same name: $h->err and $h->errstr.

  Data = { err => $handle->err, errstr => $handle->errstr }
EXCEPTION

There was an exception thrown from the DBI call. This indicates the DBI call called a die(). All DBI calles executed by POE::Component::LaDBI::Engine are wrapped in a eval {} to catch any exceptions, like when RaiseError is set.

  Data = $@

Data

The value of this field is described above. It can be a scalar, hashref, arrayref, or undef.

Accessor Functions

$resp->code()
$resp->id()
$resp->datatype()
$resp->data()

Get/Set accessor funtions to the same data described in the new() constructor.

EXPORT

None by default.

AUTHOR

Top

Sean Egan, <seanegan:bigfoot_com>

SEE ALSO

Top

perl.

POE-Component-LaDBI documentation Contained in the POE-Component-LaDBI distribution. 
package POE::Component::LaDBI::Response;

use v5.6.0;
use strict;
use warnings;

our $VERSION = '1.0';

our @CODES = qw(OK FAILED INVALID_HANDLE_ID);

our @DATATYPES = qw(ERROR EXCEPTION RC RV TABLE NAMED_TABLE ROW NAMED_ROW
		    COLUMN SQL);


sub new {
  my $o = shift;
  my $class = ref($o) || $o;
  my $self = bless {}, $class;

  # force args into hash
  my (%a) = @_;

  # force all keys lowercase
  my (%args) = map { lc($_), $a{$_} } keys %a;

  # force 'code' value uppercase; ignore if it doesn't exist
  $args{code} = uc($args{code}) if exists $args{code};

  # force 'datatype' value uppercase; ignore if it doesn't exist
  $args{datatype} = uc($args{datatype}) if exists $args{datatype};

  return $self->_init(%args);
} #end: new()


sub _init {
  my $self = shift;
  my (%args) = @_;

  return unless $self->_validate_code(%args);
  return unless $self->_validate_handle_id(%args);
  return unless $self->_validate_id(%args);
  return unless $self->_validate_data(%args);
  return unless $self->_validate_datatype(%args);

  $self->{code    } = delete $args{code    };
  $self->{handleid} = delete $args{handleid};
  $self->{id      } = delete $args{id      };
  $self->{data    } = delete $args{data    };
  $self->{datatype} = delete $args{datatype};


  if (keys %args) {
    warn __PACKAGE__ . "->new() unknown argument(s): ".join(',', keys %args);
  }

  return $self;
} #end: _init()


sub _validate_code {
  my $self = shift;
  my (%args) = @_;

  unless (defined $args{code}) {
    warn __PACKAGE__ . "->new() 'Code' argument required.";
    return;
  }

  unless (grep {$args{code} eq $_} @CODES) {
    warn __PACKAGE__ . "->new() value of 'Code' argument ($args{code}) not implemented.";
    return;
  }

  return $self;
} #end: _validate_code()


sub _validate_handle_id {
  my $self = shift;
  my (%args) = @_;

  return $self;
} #end: _validate_id()


sub _validate_id {
  my $self = shift;
  my (%args) = @_;

  unless (defined $args{id}) {
    warn __PACKAGE__ . "->new() 'Id' argument required.";
    return;
  }

  return $self;
} #end: _validate_id()


sub _validate_data {
  my $self = shift;
  my (%args) = @_;

  if (defined $args{data} and !defined $args{datatype}) {
    warn __PACKAGE__ . "->new() 'Data' argument must also be acompanied by a 'DataType' argument.";
    return;
  }

  return $self;
} #end: _validate_data()


sub _validate_datatype {
  my $self = shift;
  my (%args) = @_;

  if (defined $args{datatype} and !defined $args{data}) {
    warn __PACKAGE__ . "->new() 'DataType' argument must also be acompanied by a 'Data' argument.";
    return;
  }

  if (defined $args{datatype} and !grep {$args{datatype} eq $_} @DATATYPES) {
    warn __PACKAGE__ . "->new() value of 'DataType' argument ($args{datatype}) not implemented.";
    return;
  }

  return $self;
} #end: _validate_datatype()


sub code      {my $k='code'    ; @_==2 and $_[0]->{$k} = $_[1]; $_[0]->{$k}; }
sub handle_id {my $k='handleid'; @_==2 and $_[0]->{$k} = $_[1]; $_[0]->{$k}; }
sub datatype  {my $k='datatype'; @_==2 and $_[0]->{$k} = $_[1]; $_[0]->{$k}; }
sub data      {my $k='data'    ; @_==2 and $_[0]->{$k} = $_[1]; $_[0]->{$k}; }

sub id { $_[0]->{id}; }


1;
__END__