/ 
Data-AnyXfer-0.1
River stage zero No dependents
/ Data::AnyXfer

NAME

Data::AnyXfer - data transfer base class

DESCRIPTION

This is a base class for data transfers. It does nothing on it's own except log calls to methods for tracing.

ATTRIBUTES

callback

This is an optional callback on the hashref returned by "transform". It should be a subroutine that takes a Data::AnyXfer object and a hash reference as arguments, e.g.

use Intranet::MGReports::Import::Lettings;

sub debug {
  my ( $import, $data ) = @_;
  $import->log->debug( Dumper($data) );
  return 1;
}

my $import = Intranet::MGReports::Import:Lettings->new(
   callback => \&debug,    #
);

If the callback returns a false value, then the run will stop.

Note that the callback is passed a copy of the record, and any modifications will not be saved.

Generally this will only be used for testing and debugging.

log

This is an optional Log::Log4perl::Logger object. It defaults to the logger returned by Core::Log4perl, and can be used for logging events during a script, e.g.

$self->log->warn("Fnorjd!");

METHODS

test

Data::AnyXfer->test(1);

Sets or retreives the testing flag to trigger different behaviour.

tmp_dir

my $tmp_dir = Data::AnyXfer->tmp_dir;
say $tmp_dir; # --> /tmp/tmp_dir-user-pid-random_chars

Or...

my $tmp_dir = Data::AnyXfer->tmp_dir({
  name    => 'my-project',
  cleanup => 0,  # don't delete dir
});
say $tmp_dir' # --> /tmp/my-project-user-pid-random_chars

Returns a Path::Class::Dir object representing a recently created directory. The directory will have the user and pid embedded in it and will be deleted when the program exits, unless 'cleanup' argument set to false or the TMP_NO_CLEANUP environment variable is set to true.

run

$self->run();

This method populates the data needed to run reports, by doing the following:

It runs the "initialize" method. If that returns false value, it stops. Otherwise, it calls the "fetch_next" method until it returns false.

If "fetch_next" returns an object, then it calls the "transform" method on that object, expecting a hashref in return.

If there is a "callback" defined, that is called with the hashref.

If the hashref is defined and has keys, then it calls the "store" method to save the data.

initialize

if ($self->initialize) { ... }

This method initializes the system for the data transfer. This may involve opening files, connecting to databases, initialising objects, etc.

It returns false on failure. Any wrappers around this method should check for false in the original method before continuing, e.g.

around 'initialize' => sub {
  my ($orig, $self) = @_;
  $self->$orig() or return;

  ...
};

fetch_next

while (my $res = $self->fetch_next) { ... }

This method provides an iterator for the data source. It should return an object that can be processed by the "transform" method, or undef when there is no more data.

An example iterator for a DBIx::Class::ResultSet might be

around 'fetch_next' => sub {
  my ( $orig, $self ) = @_;
  $self->$orig or return;
  $self->rs->next;
};

transform

my $rec = $self->transform($res);

This method should transform the object returns by "fetch_next" into a hash reference.

The transform method should return either a hash reference, or undef.

If undef is returned, the "store" and "callback" methods will not be called.

store

$self->store($rec);

This method stores the record returned by "transform". It returns a false value on failure.

finalize

$self->finalize();

This method finalizes any data after all records have been saved. It returns a false value on faulure.

COPYRIGHT

This software is copyright (c) 2019, Anthony Lucas.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.