The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
slackget10-0.11
++
/ slackget10::Network::Connection

NAME

slackget10::Network::Connection - A wrapper for network operation in slack-get

VERSION

Version 1.0.0

SYNOPSIS

This class is anoter wrapper for slack-get. It will encapsulate all network operation. This class can chang a lot before the release and it may be rename in slackget10::NetworkConnection.

Some words about subclass

WARNING: The slackget10::Network::Connection::* "drivers" API changed with version 1.0.0

This class use subclass like slackget10::Network::Connection::HTTP or slackget10::Network::Connection::FTP as "drivers" for a specific protocol. You can add a "driver" class for a new protocol easily by creating a module in the slackget10::Network::Connection:: namespace. You must know that all class the slackget10::Network::Connection::* must implements the following methods (the format is : <method name(<arguments>)> : <returned value>, parmameters between [] are optionnals):

        - __test_server : a float (the server response time)
        - __fetch_file([$remote_filename],[$local_file]) : a boolean (1 or 0). NOTE: this method store the fetched file on the hard disk. If $local_file is not defined, fetch() must store the file in <config:update-directory> or in "download_directory" (constructor parameter).
        - __get_file([$remote_filename]) : the file content

Moreover, this "driver" have to respect the namming convention : the protocol name it implements in upper case (for example, if you implements a driver for the rsync:// protocol the module must be called slackget10::Network::Connection::RSYNC.pm).

CONSTRUCTOR

new

WARNING: Since version 1.0.0 of this module you can't instanciate a slackget10::Network::Connection object with a constructor with 1 argument. The followinf syntax is deprecated and no longer supported :

        my $connection = slackget10::Network::Connection->new('http://www.nymphomatic.org/mirror/linuxpackages/Slackware-10.1/');

You can force this class to behave like the old version by setting $slackget10::Network::Connection::ENABLE_DEPRECATED_COMPATIBILITY_MODE to 1 *BEFORE* calling the constructor.

This constructor take the followings arguments :

        host : a hostname (mandatory)
        path : a path on the remote host
        files : a arrayref wich contains a list of files to download
        config : a reference to a slackget10::Config object (mandatory if "download_directory" is not defined)
        download_directory : a directory where this object can store fetched files (mandatory if "config" is not defined)
        InlineStates : a hashref which contains the reference to event handlers (mandatory)
        

        use slackget10::Network::Connection;
        
        (1)
        my $connection = slackget10::Network::Connection->new(
                        host => 'http://www.nymphomatic.org',
                        path => '/mirror/linuxpackages/Slackware-10.1/',
                        files => ['FILELIST.TXT','PACKAGES.TXT','CHECKSUMS.md5'], # Be carefull that it's the files parameter not file. file is the current working file.
                        config => $config,
                        InlineStates => {
                                progress => \&handle_progress ,
                                download_error => \&handle_download_error ,
                                download_finished => \&handle_download_finished,
                        }
        );
        $connection->fetch_all or die "An error occur during the download\n";
        
        or (the recommended way) :
        
        (2)
        my $connection = slackget10::Network::Connection->new(
                        host => 'http://www.nymphomatic.org',
                        path => '/mirror/linuxpackages/Slackware-10.1/',
                        config => $config,
                        InlineStates => {
                                progress => \&handle_progress ,
                                download_error => \&handle_download_error ,
                                download_finished => \&handle_download_finished,
                        }
        );
        my $file = $connection->get_file('FILELIST.TXT') or die "[ERROR] unable to download FILELIST.TXT\n";
        
        Instead of using the "config" parameter you can use "download_directory" :
        
        my $connection = slackget10::Network::Connection->new(
                        host => 'http://www.nymphomatic.org',
                        path => '/mirror/linuxpackages/Slackware-10.1/',
                        download_directory => "/tmp/",
                        InlineStates => {
                                progress => \&handle_progress ,
                                download_error => \&handle_download_error ,
                                download_finished => \&handle_download_finished,
                        }
        );
        my $file = $connection->get_file('FILELIST.TXT') or die "[ERROR] unable to download FILELIST.TXT\n";
        
        or :
        
        my $status = $connection->fetch('FILELIST.TXT',"$config->{common}->{'update-directory'}/".$server->shortname."/cache/FILELIST.TXT");
        die "[ERROR] unable to download FILELIST.TXT\n" unless ($status);

The global way (1) is not recommended because of the lake of control on the downloaded file. For example, if there is only 1 download which fail, fetch_all will return undef and you don't know which download have failed.

The recommended way is to give to the constructor the following arguments :

        host : the host (with the protocol, do not provide 'ftp.lip6.fr' provide ftp://ftp.lip6.fr. The protocol will be automatically extracted and used to load the correct "driver")
        path : the path to the working directory on the server (Ex: '/pub/linux/distributions/slackware/slackware-10.1/'). Don't provide a 'file' argument.
        config : the slackget10::Config object of the application
        mode : a mode between 'normal' or 'secure'. This is only when you attempt to connect to a daemon (front-end/daemon or daemon/daemon connection). 'secure' use SSL connection (** not yet implemented **).
        InlineStates : see above.

EVENTS

Since the version 1.0.0 this class is event driven. To manage those events *YOU HAVE* to pass an InlineStates argument to the constructor (new).

There is 3 events generated by this class :

        * progress : this event is throw when a progress is detected on file download. The handler will receive the followings parameters (in this order) : the downloaded filename, the amount of data downloaded, the total size of the remote file.
        
        * download_error : this is throw when an error occured during download. The handler will receive the following parameters (in this order) : the downloaded filename, a slackget10::Status object.
        
        *download_finished : this is throw when a download finished successfully. The handler will receive the following parameters (in this order) : the downloaded filename, a slackget10::Status object.

FUNCTIONS

is_url

Take a string as argument and return TRUE (1) if $string is an http or ftp URL and FALSE (0) else

        print "$string is a valid URL\n" if($connection->is_url($string)) ;

parse_url

extract the following informations from $url :

        - the protocol 
        - the server
        - the file (with its total path)

For example :

        $connection->parse_url("ftp://ftp.lip6.fr/pub/linux/distributions/slackware/slackware-current/slackware/n/dhcp-3.0.1-i486-1.tgz");

Will extract :

        - protocol = ftp
        - host = ftp.lip6.fr
        - file = /pub/linux/distributions/slackware/slackware-current/slackware/n/dhcp-3.0.1-i486-1.tgz

This method return TRUE (1) if all goes well, else return FALSE (0)

strip_slash

Remove extra slash (/) in the URL and return the URL.

        my $url = $connection->strip_slash('http://ftp.infinityperl.org//slackware-repository////CHECKSUMS.md5') ;

DEBUG_show_data_section

test_server

This method test the response time of the mirror, by making a new connection to the server and downloading the FILELIST.TXT file. Be aware of the fact that after testing the connection you will have a new connection (if you were previously connected the previous connection is closed).

        my $time = $connection->test_server() ;

This method call the <DRIVER>->__test_server() method.

get_file

Download and return a given file.

        my $file = $connection->get_file('PACKAGES.TXT') ;

This method also generate events based on the returned value. If nothing is returned it throw the "download_error" event, else it throw the "download_finished" event.

At this for the moment this method throw a "progress" event with a progress value set at -1.

This method call the <DRIVER>->__get_file() method.

fetch_file

Download and store a given file.

        $connection->fetch_file() ; # download the file $connection->file and store it at $config->{common}->{'update-directory'}/$connection->file, this way is not recommended
        or
        $connection->fetch_file($remote_file) ; # download the file $remote_file and store it at $config->{common}->{'update-directory'}/$connection->file, this way is not recommended
        or
        $connection->fetch_file('PACKAGES.TXT',"$config->{common}->{'update-directory'}/".$current_specialfilecontainer_object->id."/PACKAGES.TXT") ; # This is the recommended way.
        # This is equivalent to : $connection->fetch_file($remote_file,$local_file) ;

This method return a slackget10::Status object with the following object declaration :

        my $status =  slackget10::Status->new(codes => {
                0 => "All goes well.\n",
                1 => "An error occured "
        });

A more explicit error string can be concatenate to state 1. This method also generate events based on the returned value. If nothing is returned it throw the "download_error" event, else it throw the "download_finished" event.

At this for the moment this method throw a "progress" event with a progress value set at -1.

This method call the <DRIVER>->__fetch_file() method.

fetch_all

This method fetch all files declare in the "files" parameter of the constructor.

        $connection->fetch_all or die "Unable to fetch all files\n";

This method save all files in the $config->{common}->{'update-directory'} (or in the "download_directory") directory (so you have to manage yourself the files deletion/replacement problems).

post_event

ACCESSORS

All accessors can get or set a value. You can use them like that :

        $proto->my_accessor('a value'); # to set the value of the parameter controlled by this accessor
        
        my $value = $proto->my_accessor ; # to get the value of the parameter controlled by this accessor

The common accessors are :

protocol

return the protocol of the current Connection object as a string :

        my $proto = $connection->protocol ;

host

return the host of the current Connection object as a string :

        my $host = $connection->host ;

file

return the file of the current Connection object as a string :

        my $file = $connection->file ;

files

return the list of files of the current Connection object as an array reference :

        my $arrayref = $connection->files ;

path

return the path of the current Connection object as a string :

        my $path = $connection->path ;

AUTHOR

DUPUIS Arnaud, <a.dupuis@infinityperl.org>

BUGS

Please report any bugs or feature requests to bug-slackget10@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=slackget10. 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 slackget10

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2005 DUPUIS Arnaud, All Rights Reserved.

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