NAME

Net::FTP::Versioning - Extends Net::FTP get() and put() methods to add versioning support to them

SYNOPSIS

        use Net::FTP::Versioning;
  
        # Start your ftp connection as you do when using Net::FTP.
        $ftp = Net::FTP::Versioning->new("some.host.name", Debug => 0)
                or die "Cannot connect to some.host.name: $@";
        $ftp->login("anonymous",'-anonymous@')
                or die "Cannot login ", $ftp->message;
        $ftp->cwd("/pub")
                or die "Cannot change working directory ", $ftp->message;

        # Now, get the remote file but activate versioning support
        # so your local file (if it exists) will be rotated until
        # $NROTATIONS instead of being silently overwritten
        $NROTATIONS = 2;
        $ftp->get("that.file", versions => $NROTATIONS)
                or die "get failed ", $ftp->message;
        
        # Also, print the transfer time in seconds
        print "File transfered in: ", $ftp->transferTime(), "seconds.\n";
          
        $ftp->quit;

ABSTRACT

Net::FTP::Versioning inherits all methods from Net::FTP and can be used in substitution of it. Extends the get() and put() methods to add versioning support to them. A new transferTime() method was added to report the file transfer time in seconds.

DESCRIPTION

Net::FTP::Versioning extends Net::FTP->get() and Net::FTP->put() to add versioning support to these methods.

Versioning support means that, when you are getting a remote file, if exists a local file with the same name of the file you're going to download, the local file can be rotated instead of just being overwriten. The same thing occurs if you are uploading a file with put() and in the remote ftp server already exists a file with the name you are uploading - the remote file can be rotated too.

The rotation procedure simply renames the existing file with a ".1", ".2", ".3" ... ".N" suffix, until the number of versions you wish to use.

Depending on the file sizes and the number of rotations you're using, the rotation process could take significant time. This would give the fake idea that the file transfer time took longer than it really took. Remember that with versioning enabled, the extended get() and put() methods will rotate the existing files before making the file transfer.

For this reason, I added a transferTime() method that returns the actual file transfer time, recorded after the versioning code already finished. You can, of course, use transferTime() even if you're not enabling versioning.

CONSTRUCTOR

new ([ HOST ] [, OPTIONS ])

Just like Net::FTP->new(). Refer to its documentation.

METHODS

get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]][, versions => N])

Works like** Net::FTP->get() does but accepts an extra optional option, 'versions', that can be used to enable versioning support;

** if you enable versioning, unlike Net::FTP->get(), this method will not accept a filehandle as the LOCAL_FILE, since it could not know the name of the local file to be rotated. It croaks an error message in this case.

put ( LOCAL_FILE [, REMOTE_FILE][, versions => N ] )

Works just like Net::FTP->put() does but accepts an extra optional option, 'versions', that can be used to enable versioning support;

transferTime()

Returns an integer standing for the time in seconds taken by the last file transfer accomplished by get() or put() methods.

ALL OTHER Net::FTP METHODS

All other Net::FTP methods are inherited and perfectly usable. Refer to Net::FTP documentation to know about them.

INTERNALS

I didn't touch the networking code of get() and put() methods of Net::FTP. I just added the versioning code. The file transfers are performed by using the original get() and put() methods from Net::FTP, by calling them with $self->SUPER::get(@_) and $self->SUPER::put(@_).

SEE ALSO

Net::FTP

AUTHOR

Bruno Negrao. Contact info: see in http://www.qmailwiki.org/User:Bnegrao

COPYRIGHT AND LICENSE

Copyright 2005 by Bruno Negrao

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