NAME

WebFS::FileCopy - Get, put, move, copy, and delete files located by URIs

SYNOPSIS

 use WebFS::FileCopy;

 my @res = get_urls('ftp://www.perl.com', 'http://www.netscape.com');
 print $res[0]->content if $res[0]->is_success;

 # Get content from pages requiring basic authentication.
 my $req = LWP::Request->new('GET' => 'http://www.dummy.com/');
 $req->authorization_basic('my_username', 'my_password');
 @res = get_urls($req);

 put_urls('put this text', 'ftp://ftp/incoming/new', 'file:/tmp/NEW');
 move_url('file:/tmp/NEW', 'ftp://ftp/incoming/NEW.1');
 delete_urls('ftp://ftp/incoming/NEW.1', 'file:/tmp/NEW');

 copy_url('http://www.perl.com/index.html', 'ftp://ftp.host/outgoing/SIG');

 copy_urls(['file:/tmp/file1', 'http://www.perl.com/index.html],
           ['file:/tmp/DIR1/', 'file:/tmp/DIR2', 'ftp://ftp/incoming/']);

 my @list1 = list_url('file:/tmp');
 my @list2 = list_url('ftp://ftp/outgoing/');

DESCRIPTION

This package provides some simple routines to read, move, copy, and delete files as references by string URLs, URI objects or URIs embedded in HTTP::Reqeust or LWP::Request objects. All subroutines in this package that expect a URI will accept a string, a URI object, or a HTTP::Reqeust or LWP::Request with an embedded URI. If passed a HTTP::Request or LWP::Request, then the method of the object is ignored and the proper method will be used to either GET or PUT the requested UIR.

The distinction between files and directories in a URI is tested by looking for a trailing / in the path. If a trailing / exists, then the URI is considered to point to a directory, otherwise it is a file.

All of the following subroutines are exported to the users namespace automatically. If you do not want this, then require this package instead of useing it.

SUBROUTINES

get_urls uri [uri [uri ...]]

The get_urls function will fetch the documents identified by the given URIs and returns a list of HTTP::Responses. You can test if the GET succeeded by using the HTTP::Response is_success method. If is_success returns 1, then use the content method to get the contents of the GET.

Get_urls performs the GETs in parallel to speed execution and should be faster than performing individual gets.

Example printing the success and the content from each URI:

    my @uris = ('http://perl.com/', 'file:/home/me/.sig');
    my @response = get_urls(@uris);
    foreach my $res (@response) {
      print "FOR URL ", $res->request->uri;
      if ($res->is_success) {
        print "SUCCESS.  CONTENT IS\n", $res->content, "\n";
      } else {
        print "FAILED BECAUSE ", $res->message, "\n";
      }
    }

put_urls string uri [uri [uri ...]]

put_urls coderef uri [uri [uri ...]]

Put the contents of string or the return from &coderef() into the listed uris. The destination uris must be either ftp: or file: and must specify a complete file; no directories are allowed. If the first form is used with string then the contents of string will be sent. If the second form is used, then coderef is a reference to a subroutine or anonymous CODE and &coderef() will be called repeatedly until it returns '' or undef and all of the text it returns will be stored in the uris.

Upon return, put_urls returns an array, where each element contains a HTTP::Response object corresponding to the success or failure of transferring the data to the i-th uri. This object can be tested for the success or failure of the PUT by using the is_success method on the element. If the PUT was not successful, then the message method may be used to gather an error message explaining why the PUT failed. If there is invalid input to put_urls then put_urls returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context, and $@ contains a message containing explaining the invalid input.

For example, the following code, prints either YES or NO and a failure message if the put failed.

    @a = put_urls('text',
                  'http://www.perl.com/test.html',
                  'file://some.other.host/test',
                  'ftp://ftp.gps.caltech.edu/test');
    foreach $put_res (@a) {
      print $put_res->request->uri, ' ';
      if ($put_res->is_success) {
        print "YES\n";
      } else {
        print "NO ", $put_res->message, "\n";
      }
    }

copy_url uri_from uri_to [base]

Copy the content contained in the URI uri_from to the location specified by the URI uri_to. uri_from must contain the complete path to a file; no directories are allowed. uri_to must be a file: or ftp: URI and may either be a directory or a file.

If supplied, base may be used to convert uri_from and uri_to from relative URIs to absolute URIs.

On return, copy_url returns 1 on success, 0 on otherwise. On failure $@ contains a message explaining the failure. See copy_urls if you want to quickly copy a single file to multiple places or copy multiple files to one directory or both. copy_urls provides simultaneous file transfers and will do the task much faster than calling copy_url many times over. If invalid input is given to copy_url, then it returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context and $@ contains a message explaining the invalid input.

copy_urls uri_file_from uri_file_to [base]

copy_urls uri_file_from uri_dir_to [base]

Copy the content contained at the specified URIs to other locations also specified by URIs. The first argument to copy_urls is either a single URI or a reference to an array of URIs to copy. All of these URIs must contain the complete path to a file; no directories are allowed. The second argument may be a single URI or a reference to an array of URIS. If any of the destination URIs are a location of a file and not a directory, then only one URI can be passed as the first argument. If a reference to an array of URIs is passed as the second argument, then all URIs must point to directories, not files. Only file: and ftp: URIs may be used as the destination of the copy.

If supplied, base may be used to convert relative URIs to absolute URIs for all URIs supplied to copy_urls.

The copy operations of the multiple URIs are done in parallel to speed execution.

On return copy_urls returns a list of the LWP::Response from each GET performed on the from URIs. If there is invalid input to copy_urls then copy_urls returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context and contains $@ a message explaining the error. The success or failure of each GET may be tested by using is_success method on each element of the list. If the GET succeeded (is_success returns TRUE), then hash element 'put_requests' exists and is a reference to a list of LWP::Responses containing the response to the PUT. For example, the following code prints a message containing the results from copy_urls:

    my @get_res = copy_urls(......);
    foreach my $get_res (@get_res) {
      my $uri = $get_res->request->uri;
      print "GET from $uri ";
      unless ($get_res->is_success) {
        print "FAILED\n";
        next;
      }
  
      print "SUCCEEDED\n";
      foreach my $c (@{$get_res->{put_requests}}) {
        $uri = $c->request->uri;
        if ($c->is_success) {
          print "    to $uri succeeded\n"
        } else {
          print "    to $uri failed: ", $c->message, "\n";
        }
      }
    }

delete_urls uri [uri [uri ...]]

Delete the files located by the uris and return a HTTP::Response for each uri. If the uri was successfully deleted, then the is_success method returns 1, otherwise it returns 0 and the message method contains the reason for the failure.

move_url from_uri to_uri [base]

Move the contents of the from_uri URI to the to_uri URI. If base is supplied, then the from_uri and to_uri URIs are converted from relative URIs to absolute URIs using base. If the move was successful, then move_url returns 1, otherwise it returns 0 and $@ contains a message explaining why the move failed. If invalid input was given to move_url then it returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context and $@ contains a message explaining the invalid input.

list_url uri

Return a list containing the filenames in the directory located at uri. Only file and FTP directory URIs currently work. If for any reason the list can not be obtained, then list_url returns an empty list in a list context, an undefined value in a scalar context, or nothing in a void context and $@ contains a message why list_url failed.

SEE ALSO

See also the HTTP::Response, HTTP::Request, LWP::Request, and LWP::Simple.

AUTHOR

Blair Zajac <blair@akamai.com>

COPYRIGHT

Copyright (C) 1998-2001 by Blair Zajac. All rights reserved. This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself.