NAME

POE::Component::Net::FTP - non-blocking wrapper around Net::FTP

SYNOPSIS

    use strict;
    use warnings;

    use POE qw(Component::Net::FTP);

    die "Usage: perl ftp.pl <host> <login> <password> <file_to_upload>\n"
        unless @ARGV == 4;

    my ( $Host, $Login, $Pass, $File ) = @ARGV;

    my $poco = POE::Component::Net::FTP->spawn;

    POE::Session->create(
        package_states => [ main => [ qw(_start response) ], ],
    );

    $poe_kernel->run;

    sub _start {
        $poco->process( {
                event       => 'response',
                commands    => [
                    { new   => [ $Host         ] },
                    { login => [ $Login, $Pass ] },
                    { put   => [ $File         ] },
                ],
            }
        );
    }

    sub response {
        my $in_ref = $_[ARG0];
        if ( $in_ref->{is_error} ) {
            print "Failed on $in_ref->{is_error} command: "
                     . "$in_ref->{last_error}\n";
        }
        else {
            print "Success!\n";
        }
        $poco->shutdown;
    }

Using event based interface is also possible.

DESCRIPTION

The module is a non-blocking wrapper around Net::FTP module with an accent on "wrapper". In other words, to use this module you'd need to read up the docs for Net::FTP module as this wrapper is literally a wrapper.

The is also a module POE::Component::Client::FTP, you might want to check it out although it was not fitting my requirements hence the creation of this module.

CONSTRUCTOR

spawn

    my $poco = POE::Component::Net::FTP>spawn;

    POE::Component::Net::FTP->spawn(
        alias           => 'ftp',
        stop_on_error   => 0,
        options         => {
            debug => 1,
            trace => 1,
            # POE::Session arguments for the component
        },
        debug           => 1, # output some debug info
    );

The spawn method returns a POE::Component::Net::FTP object. It takes a few arguments, all of which are optional. The possible arguments are as follows:

alias

    ->spawn( alias => 'ftp' );

Optional. Specifies a POE Kernel alias for the component.

stop_on_error

    ->spawn( stop_on_error => 1 );

Optional. Takes either true or false values. If set to a true value will stop and return if any of the series of commands failed. Otherwise will try to execute all the commands (this probably won't make sense until you read up on process() method/event). Defaults to: 1

options

    ->spawn(
        options => {
            trace => 1,
            default => 1,
        },
    );

Optional. A hashref of POE Session options to pass to the component's session.

debug

    ->spawn(
        debug => 1
    );

When set to a true value turns on output of debug messages. Defaults to: 0.

METHODS

process

    $poco->process( {
            event       => 'event_for_output',
            commands    => [
                { new   => [ $Host         ] },
                { login => [ $Login, $Pass ] },
                { put   => [ $File         ] },
            ],
            _blah       => 'pooh!',
            session     => 'other',
        }
    );

Takes a hashref as an argument, does not return a sensible return value. See process event's description for more information.

session_id

    my $poco_id = $poco->session_id;

Takes no arguments. Returns component's session ID.

shutdown

    $poco->shutdown;

Takes no arguments. Shuts down the component.

ACCEPTED EVENTS

process

    $poe_kernel->post( ftp => process => {
            event       => 'event_for_output',
            commands    => [
                { new   => [ $Host         ] },
                { login => [ $Login, $Pass ] },
                { put   => [ $File         ] },
            ],
            _blah       => 'pooh!',
            session     => 'other',
        }
    );

Instructs the component to call a series (or just one) methods of Net::FTP object. Takes a hashref as an argument, the possible keys/value of that hashref are as follows:

event

    { event => 'results_event', }

Mandatory. Specifies the name of the event to emit when results are ready. See OUTPUT section for more information.

commands

    commands    => [
        { new   => [ $Host         ] },
        { login => [ $Login, $Pass ] },
        { put   => [ $File         ] },
    ],

Mandatory. This is the "wrapper" part. The commands argument takes an arrayref of hashrefs. The first call to this event/method must contain new as the first command afterwards the Net::FTP object will be the same one until you pass in a new new command. The hashrefs are all single key/value pairs. The key is the method of Net::FTP object you wish to call and the value is an arrayref of arguments to pass into that method. Error checking will be done by the component, see "OUTPUT" section for details.

session

    { session => 'other' }

    { session => $other_session_reference }

    { session => $other_session_ID }

Optional. Takes either an alias, reference or an ID of an alternative session to send output to.

user defined

    {
        _user    => 'random',
        _another => 'more',
    }

Optional. Any keys starting with _ (underscore) will not affect the component and will be passed back in the result intact.

shutdown

    $poe_kernel->post( ftp => 'shutdown' );

Takes no arguments. Tells the component to shut itself down.

OUTPUT

    $VAR1 = {
        'commands' => [ { 'new'   => [ 'ftp.host.com'  ] },
                        { 'login' => [ 'login', 'pass' ] },
                        { 'put'   => [ 'test.txt'      ] },
        ],
        'responses' => [ [ 1   ],
                         [ '1' ],
                         [ 'test.txt' ]
        ]
    };

The event handler set up to handle the event which you've specified in the event argument to process() method/event will recieve input in the $_[ARG0] in a form of a hashref. The possible keys/value of that hashref are as follows:

responses

    'responses' => [ [ 1   ],
                        [ '1' ],
                        [ 'test.txt' ]
    ]

The responses key will contain an arrayref as a value. Each element of that arrayref will also be an arrayref which will be the return value of the "command" which was passed into commands arrayref to process() event/method (i.e. the return value of the "command" passed as a third element in commands arrayref will be the the third element in responses arrayref). If a particular command (read "method call") failed the return value will be the return value of Net::FTP's message() method (where applicable), for new() method (on falure) the element will contain the value of $@.

is_error

    { 'is_error'    => 'login' }

If any of the methods listed in commands arrayref of process event/method failed then is_error key will be present and it's value will be the name of the method that failed.

last_error

    { 'last_error' => 'Login authentication failed' }

If any of the methods listed in commands arrayref of process event/method failed then last_error key will be present and it's value will be the error message explaining the falure.

user defined

    { '_blah' => 'foos' }

Any arguments beginning with _ (underscore) passed into the EXAMPLE() event/method will be present intact in the result.

SEE ALSO

POE, Net::FTP

AUTHOR

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

BUGS

Please report any bugs or feature requests to bug-poe-component-net-ftp at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-Net-FTP. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc POE::Component::Net::FTP

You can also look for information at:

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-Net-FTP

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/POE-Component-Net-FTP

• CPAN Ratings

  http://cpanratings.perl.org/d/POE-Component-Net-FTP

• Search CPAN

  http://search.cpan.org/dist/POE-Component-Net-FTP

COPYRIGHT & LICENSE

Copyright 2008 Zoffix Znet, all rights reserved.

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

cpanm POE::Component::Net::FTP

perl -MCPAN -e shell
install POE::Component::Net::FTP