/ 
Net-FTP-Robust-0.05
River stage one • 1 direct dependent • 1 total dependent
/ Net::FTP::Robust

NAME

Net::FTP::Robust - download files over FTP

SYNOPSIS

my $ftp = Net::FTP::Robust->new
 ( Host    => $host
 , Port    => $port
 );

# when needed, many attempts will be made to retrieve all
$ftp->get($remote_dir, $local_dir);
$ftp->get($remote_dir);

# to get client-side errors as well:
use Log::Report;       # get 'try()'
try { $ftp->get(...) };
if($@) {...}

# make the process more verbose, start with
Log::Report mode => 'VERBOSE';
Log::Report mode => 'DEBUG';

# to catch all reports: errors, warnings, debugs etc
try { $ftp->get(...) } mode => 'DEBUG';
push @trace, $@->exceptions; # simply prints all
$@->reportFatal;             # re-cast real errors

DESCRIPTION

This module is specialized in (on the moment only) downloading large data-sets (gigabytes) autonomously. It uses Net::FTP, and adds various algorithms to work around various common problems. In general, local errors are fatal and server or network errors are recovered.

See "DETAILS" far down on this page for more explanations and limitations.

METHODS

Constructors

Net::FTP::Robust->new(OPTIONS)

    Use to connect to one ftp-server. All OPTIONS which start with capitals are passed to Net::FTP method new().

    Option        --Default
host            <undef>
login_attempts  10
login_delay     60
password        '-anonymous@'
skip_names      <skip hidden files>
user            'anonymous'

    . host => HOSTNAME

      Alternative for the Host parameter for Net::FTP subroutine new.

    . login_attempts => INTEGER

      How many different connections will we use. Between each attempt, we wait login_delay seconds. When '0' is specified, it will continue forever: you can solve problems discovered in the logs.

    . login_delay => INTEGER

      How much time to wait between retries which require to login again, in seconds.

    . password => STRING

    . skip_names => CODE

      Do not attempt directories or files which contain certain patterns. When the CODE returns 1, then the element will be ignored. Typically, the CODE will apply some regular expressions.

      The CODE reference will get three arguments: the ftp object (Net::FTP) with established connection, the full remote path of the entry, and the basename of the entry.

    . user => STRING

Download

$obj->get(FROM, [TO])

    The FROM directory or file on the remote server is copied TO a local directory (defaults to '.')

DETAILS

Comparison

Net::FTP implements the FTP protocol. Various modules on CPAN asbtract the transport protocol further, for instance Net::FTP::Recurse. Each module has its own focus. Net::FTP::Robust is specialized in retries and logging, to retrieve data which takes hours to download, sometimes over quite instable connections. It uses Log::Report which can connect to various logging frameworks for its messages.

Limitations

The get() will collect directories recursively or single files.

When a new get() is ran with the same destination directory, then the download will continue where it left-of. Files which were only partially downloaded will get downloaded only for the missing part.

Files will not get deleted, not on the server and not on the client. Symbolic links on the server are invisible on the local copy.

When downloading, the name of the directory and file will temporarily be mangled: only when the download is completed, the real name will show up. For UNIX, the names will temporarily start with a dot, to be hidden from the standard ls(1) output.

When you have the permission from your OS, the modification time will get copied from the source as well.

SEE ALSO

This module is part of Net-FTP-Robust distribution version 0.05, built on November 16, 2009. Website: http://perl.overmeer.net. See also Net::FTPSSL.

COPYRIGHTS

Copyrights of the perl code and the related documentation by 2009 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html