CopyTree::VendorProof(3pm)

NAME
CopyTree::VendorProof - Perl extension for a generic interface to inplement a copy method between [a local computer and a remote file system] or [a remote file system and itself] or [local computer to local computer]. An example remote system would be Microsoft's Sharepoint file storeage, which takes commands via https

The supported (very basic) copy funtionalities mimics the unix cp -rf command - copies SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.

SYNOPSIS
  use CopyTree::VendorProof;
        my $cpobj = CopyTree::VendorProof->new;
        my $sharepointobj = SharePoint::SOAPHandler ->new;
        my $localfileobj = CopyTree::VendorProof::LocalFileOp ->new;

        $sharepointobj ->sp_creds_domain('spserver.spdomain.org:443'); #do not include protocal ('https://')
        $sharepointobj ->sp_creds_user('DOMAIN_NAME_CAPS\username');
        $sharepointobj ->sp_creds_password('ch1ckens');
        $sharepointobj ->sp_authorizedroot('https://spserver.spdomain.org:443/someroot/dir_under_which_Shared_Documents_appear');

        $cpobj -> src('Shared Documents/somedir', $sharepointobj);#SOAPHandler objects always takes Shared Documents/ as start of a path
        $cpobj -> src('Shared Documents/somefile', $sharepointobj);#SOAPHandler objects always takes Shared Documents/ as start of a path
        $cpobj -> src('/home/username/Documents/somedir', $localfileobj);
        $cpobj -> dst('/home/username/Documents', $localfileobj);
        $cpobj ->cp;
        $cpobj ->reset; #clears all src and dst

DESCRIPTION
This module provides a generic interface to inplement a copy method between [a local computer and a remote file system] or [a remote file system and itself] or [local computer to local computer].

The supported (very basic) copy funtionalities mimics the unix cp command - copies SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY.

This whole project arose when I needed to automate file transfers between a locally mounted file system (be it just local files or samba) and a remote Microsoft Sharepoint server. Since at the time of writing (mid 2011), there wasn't a way to locally mount Sharepoint directories that's connected through https, I'd decided to write connector modules for it. Half way down the process, it occurred to me that this will not be the last time some vendor provides a stupid interface for their services, so I reorganized this module to be adaptable to changes - as long as I can establish some basic functions of single file transfer, I can plug this module in and do more complex stuff such as copy entire directories.

This adaptablity resulted in the semi complex model used to invoke a copy. You basically need at least 2 objects for copy to work. You need this module (CopyTree::VendorProof) to provide a base class to copy stuff with, but you also need at least one more module to provide data connection methods for retrieving a file, posting a file, listing a directory, and doing some sort of file tests for each protocol (be it a protocol for local file operations or a protocol for sharepoint operations). In other words, you need an extra module per protocol, so if you want to copy from local to sharepoint, you need to load CopyTree::VendorProof::LocalFileOp (which I wrote) AND SharePoint::SOAPHandler (which I also wrote). You would add sources and destinations of files you wish to copy via $vendorproof_instance ->src ($path, $connector_instance) and $vendorproof_instance ->dst($destinationpath, $another_connector_instance). Once you've added all your sources, you would then run $vendorproof_instance ->cp; which would complete the copy operation as per your src, dst definitions.

The copy schemes are similar to unix' cp -rf ; i.e. copies SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY. Noting that:

   directory copies are recursive, and
   all copies are default overwrite

The primary use of this module is on a linux / unix system that needs to interact with a remote system.

VendorProof Class Methods
The methods provided in this module (base class) include:

  new
                my $ctvp_inst = CopyTree::VendorProof ->new;
                creates a new VendorProof object instance

  reset
                $ctvp_inst ->reset;
                clears any previously set sources and destinations, retuns the instance.

  src
                $ctvp_inst ->src($path, $path_instance)
                adds a source and the connector instance of said source
                you may add multiple sources by invoking this multiple times

  dst
                $ctvp_inst ->dst($dstpath, $dstpath_instance)
                adds a destination and its connector instance

  cp
                $ctvp_inst ->cp;
                starts copy operation based on the $ctvp_inst->src and $ctvp_inst->dst that's initiated

  copy_meth_deci
                internal method - if source and destination are using the same object (for example, both on sharepoint), do not use the local memory as an intermediate data cache

  ls_tree
                $ctvp_inst ->ls_tree($path)
                returns a hash ref of the tree structure under $path, which files are undef, and dirs are references to yet another anonymous hash

  ls_tree_fdret ( $root_path_name, $hashref)
                takes a $root_path_name and the $hashref returned from a previous $ctvp->ls_tree and returns (\@files, \@dirs) with the $root_path_name added on as the parent of these @files and @dirs

  path
                This is not used by the VendorProof instance.  Instead, it provides a base class for connector instances to use to set a $path variable.  Not really used and not extensively tested.

  fdls_ret
                This method is provided as a base class for connector instances to use.  It provides common code for fdls methods from different connector objects.

        Of the aformentioned methods, new, path, and reset are the only methods that do not require additional connector objects to function, although path has the sole function of providing a base class to connector objects.

Object specific instance methods for the base class CopyTree::VendorProof:
Before you start involking CopyTree::VendorProof ->new, you'd better set up class instances for your source(s) and destination. These class instances will provide class specific methods for file operations, which CopyTree::VendorProof relies on to carry out the cp -rf functionality. Since these are class methods, the first item from @_ is the instance itself, and should be stored in $inst, or whatever you'd like to call it. The required class methods are described below (note that unless you're writing connecters other than CopyTree::VendorProof::LocalFileOp or SharePoint::SOAPHandler, you will not need to know them):

  0. new
        which takes no arguments, but blesses an anonymous hash into the data connection object and returns it

  1. fdls
        which takes two arguments:
                an option ($lsoption) that's one of 'f', 'd', 'fdarrayrefs', or ''
                and a directory path $startpath.
                The lsoption is passed to the SUPER class fdls_ret, and is not handled at this level.
        This method will generate @files and @dirs, which are lists of files and directories that start with $startpath,
        And return $self -> SUPER::fdls_ret ($lsoption, \@files, \@dirs),
        which is ultimately a listing of the directory content, being one of
                @files, @dirs, (\@files, \@dirs), or  @files_and_dirs) depending on the options being 'f', 'd', 'fdarrayrefs' or ''

  2. is_fd
        which takes a single argument of a file or dir $path,
        and returns 'd' for directory,
                'f' for file,
                'pd' for non-existing, but has a valid parent dir,
                '0' for non of the above.

  3. read_into_memory
        which takes the $sourcepath of a file,
        and reads (slurps) it into a scalar $binfile #preferably in binmode,
        and returns it as \$binfile

  4. write_from_memory
        which takes the reference to a scalar $binfile (\$binfile)  PLUS
        a destination path, and writes the scalar to the destination.
        no return is necessary

  5. copy_local_files
        which takes the $source and $destination files on the same file system,
        and copies from $source to $destination.  No return is necessary.  This
        method is included such that entirely remote operations may transfer faster,
        without an intermediate 'download to local machine' step.

  6. cust_mkdir
        which takes a $dirpath and creates the dir.  If the parent of $dirpah
        does not exist, give a warning and do not do anything

  7. cust_rmdir
        which takes a $dirpath and removes the entire dir tree from $dirpath
        croaks / dies if $dirpath is not a dir. No return is necessary.
        To make things easier, when writing this method, use

        my ($filesref, $dirsref) = $inst -> ls_tree_fdret( $dirpath, $inst -> ls_tree($dirpath);

        to get array references of @files and @dirs under $dirpath
        Note: ls_tree and ls_tree_fdret uses fdls, and are parent classes in CopyTree::VendorProof

  8. cust_rmfile
        which takes a $filepath and removes it.
        croaks / dies if $file is not a file.

  EXPORT
None by default.

SEE ALSO
Check out CopyTree::VendorProof::LocalFileOp and SharePoint::SOAPHandler.

AUTHOR
dbmolester, dbmolester de gmail.com<gt>

COPYRIGHT AND LICENSE
Copyright (C) 2011 by dbmolester

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.