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__

=head1 NAME

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

=head1 SYNOPSIS

  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;

=head1 DESCRIPTION

=over 4

=item C<$resp-E<gt>new()>

Args:

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

=over 4

=item C<Code>

String identifier representing the error result of the request.

Valid C<Code> values are:

=over 4

=item C<OK>

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

=item C<FAILED>

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

=item C<INVALID_HANDLE_ID>

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

=back

=item C<Id>

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

=item C<DataType>

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

=over 4

=item C<TABLE>

Data is an array ref of array refs to scalars.

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

=item C<NAMED_TABLE>

This one is odd. See the description of C<selectall_hashref()> in L<DBI>.
For *_hashref() calls in C<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, ...},
           ...
         }

=item C<ROW>

Data is an array ref of scalars.

  Data = [ elt0, elt1, ... ]

=item C<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, ... }

=item C<COLUMN>

  Data = [ elt0, elt1, ... ]

=item C<RC>

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

  Data = $rc

=item C<RV>

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

  Data = $rv

=item C<SQL>

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

  Data = $sql_string

=item C<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: C<$h-E<gt>err> and
C<$h-E<gt>errstr>.

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

=item C<EXCEPTION>

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

  Data = $@

=back

=item C<Data>

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

=back

=head3 Accessor Functions

=item C<$resp-E<gt>code()>

=item C<$resp-E<gt>id()>

=item C<$resp-E<gt>datatype()>

=item C<$resp-E<gt>data()>

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

=back


=head2 EXPORT

None by default.

=head1 AUTHOR

Sean Egan, E<lt>seanegan:bigfoot_comE<gt>

=head1 SEE ALSO

L<perl>.

=cut