FileSyncTask

Extends \Task

The FileSyncTask class copies files either to or from a remote host, or locally on the current host. It allows rsync to transfer the differences between two sets of files across the network connection, using an efficient checksum-search algorithm.

There are 4 different ways of using FileSyncTask:

  1. For copying local files.
  2. For copying from the local machine to a remote machine using a remote shell program as the transport (ssh).
  3. For copying from a remote machine to the local machine using a remote shell program.
  4. For listing files on a remote machine.

This is extended from Federico's original code, all his docs are kept in here below.

author

Federico Cargnelutti fede.carg@gmail.com

author

Anton Stöckl anton@stoeckl.de

version

$Revision$

package

phing.tasks.ext

see
example

Methods

Executes the rsync command and returns the exit code.

executeCommand() : integer
throws

Response

integer

Return code from execution.

Returns the rsync command line options.

getCommand() : string

Response

string

Returns the textual description of the task

getDescription() : string
inherited

Response

string

The text description of the task

Returns an error message based on a given error code.

getErrorMessage(integer $code) : null|string

Arguments

$code

integer

Error code

Response

null|string

Returns the location within the buildfile this task occurs. Used by {@link BuildException} to give detailed error messages.

getLocation() : \Location
inherited

Response

\Location

The location object describing the position of this task within the buildfile.

Returns the owning target of this task.

getOwningTarget() : \Target
inherited

Response

\Target

The target object that owns this task

Returns a reference to current project

getProject() : \Project
inherited

Response

\Project

Reference to current porject object

Returns a name

getRegisterSlot(string $slotName) : \RegisterSlot
inherited

Arguments

$slotName

string

Response

\RegisterSlot

Returns the wrapper object for runtime configuration

getRuntimeConfigurableWrapper() : \RuntimeConfigurable
inherited

Response

\RuntimeConfigurable

The wrapper object used by this task

Returns the name of task, used only for log messages

getTaskName() : string
inherited

Response

string

Name of this task

Returns the name of the task under which it was invoked, usually the XML tagname

getTaskType() : string
inherited

Response

string

The type of this task (XML Tag)

Called by the parser to let the task initialize properly.

init() 
inherited

Should throw a BuildException if something goes wrong with the build

This is abstract here, but may not be overloaded by subclasses.

throws

Logs a message with the given priority.

log(string $msg, integer $level = \Project::MSG_INFO) : void
inherited

Arguments

$msg

string

The message to be logged.

$level

integer

The message's priority at this message should have

Called by the project to let the task do it's work. This method may be called more than once, if the task is invoked more than once. For example, if target1 and target2 both depend on target3, then running <em>phing target1 target2</em> will run all tasks in target3 twice.

main() 
inherited abstract

Should throw a BuildException if someting goes wrong with the build

This is abstract here. Must be overloaded by real tasks.

Configure this task if it hasn't been done already.

maybeConfigure() 
inherited

Perfrom this task

perform() 
inherited
throws

Makes backups into hierarchy based in $dir.

setBackupDir( $dir) : void

Arguments

$dir

This changes the way rsync checks if the files have been changed and are in need of a transfer.

setChecksum(boolean $checksum) : void

Without this option, rsync uses a "quick check" that (by default) checks if each file’s size and time of last modification match between the sender and receiver. This option changes this to compare a 128-bit checksum for each file that has a matching size.

Arguments

$checksum

boolean

Tells rsync to delete extraneous files from the receiving side, but only for the directories that are being synchronized. Files that are excluded from transfer are also excluded from being deleted.

setDelete(boolean $delete) : void

Arguments

$delete

boolean

Sets a textual description of the task

setDescription(string $desc) 
inherited

Arguments

$desc

string

The text describing the task

Sets the destination directory. If the option remotehost is not included in the build.xml file, rsync will point to a local directory instead.

setDestinationDir(string $dir) : void

Arguments

$dir

string

This makes rsync perform a trial run that doesn’t make any changes (and produces mostly the same output as a real run). It is most commonly used in combination with the -v, --verbose and/or -i, --itemize-changes options to see what an rsync command is going to do before one actually runs it.

setDryRun(boolean $dryRun) : void

Arguments

$dryRun

boolean

Sets exclude matching pattern.

setExclude(string $exclude) : void

Arguments

$exclude

string

Exclude files matching patterns from $file, Blank lines in $file and lines starting with ';' or '#' are ignored.

setExcludeFile(string $file) : void

Arguments

$file

string

Sets the identity file for public key transfers.

setIdentityFile( $identity) : void

Arguments

$identity

Sets the isRemoteConnection property.

setIsRemoteConnection(boolean $isRemote) : void

Arguments

$isRemote

boolean

Requests a simple itemized list of the changes that are being made to each file, including attribute changes.

setItemizeChanges(boolean $itemizeChanges) : void

Arguments

$itemizeChanges

boolean

Sets the location within the buildfile this task occurs. Called by the parser to set location information.

setLocation(\Location $location) 
inherited

Arguments

$location

\Location

The location object describing the position of this task within the buildfile.

Sets the command options.

setOptions(string $options) : void

Arguments

$options

string

Sets the owning target this task belongs to.

setOwningTarget(\Target $target) 
inherited

Arguments

$target

\Target

References the project to the current component.

setProject(\Project $project) : void
inherited

Arguments

$project

\Project

The reference to the current project

Sets the remote host.

setRemoteHost(string $host) : void

Arguments

$host

string

This option allows you to provide a password for accessing a remote rsync daemon. Note that this option is only useful when accessing an rsync daemon using the built in transport, not when using a remote shell as the transport.

setRemotePass(string $pass) : void

Arguments

$pass

string

Allows the user to choose an alternative remote shell program to use for communication between the local and remote copies of rsync. Typically, rsync is configured to use ssh by default, but you may prefer to use rsh on a local network.

setRemoteShell(string $shell) : void

Arguments

$shell

string

Specifies the user to log in as on the remote machine. This also may be specified in the properties file.

setRemoteUser(string $user) : void

Arguments

$user

string

Sets the path to the rsync command.

setRsyncPath(string $path) : void

Arguments

$path

string

Sets the wrapper object this task should use for runtime configurable elements.

setRuntimeConfigurableWrapper(\RuntimeConfigurable $wrapper) 
inherited

Arguments

$wrapper

\RuntimeConfigurable

The wrapper object this task should use

Sets the source directory.

setSourceDir(string $dir) : void

Arguments

$dir

string

Sets the name of this task for log messages

setTaskName(string $name) : string
inherited

Arguments

$name

string

Response

string

A string representing the name of this task for log

Sets the type of the task. Usually this is the name of the XML tag

setTaskType( $name) 
inherited

Arguments

$name

Increases the amount of information you are given during the transfer. By default, rsync works silently. A single -v will give you information about what files are being transferred and a brief summary at the end.

setVerbose(boolean $verbose) : void

Arguments

$verbose

boolean

Properties

Path to rsync command.

rsyncPath : string
var

Type(s)

string

Source directory.

sourceDir : string

For remote sources this must contain user and host, e.g.: user@host:/my/source/dir

var

Type(s)

string

Destination directory.

destinationDir : string

For remote targets this must contain user and host, e.g.: user@host:/my/target/dir

var

Type(s)

string

Remote host.

remoteHost : string
var

Type(s)

string

Rsync auth username.

remoteUser : string
var

Type(s)

string

Rsync auth password.

remotePass : string
var

Type(s)

string

Remote shell.

remoteShell : string
var

Type(s)

string

Exclude file matching pattern.

exclude : string
var

Type(s)

string

Excluded patterns file.

excludeFile : string
var

Type(s)

string

This option creates a backup so users can rollback to an existing restore point. The remote directory is copied to a new directory specified by the user.

backupDir : string
var

Type(s)

string

Default command options.

defaultOptions : string

r - recursive p - preserve permissions K - treat symlinked dir on receiver as dir z - compress l - copy symlinks as symlinks

var

Type(s)

string

Connection type.

isRemoteConnection : boolean
var

Type(s)

boolean

This option increases the amount of information you are given during the transfer. The verbose option set to true will give you information about what files are being transferred and a brief summary at the end.

verbose : boolean
var

Type(s)

boolean

This option makes rsync perform a trial run that doesn’t make any changes (and produces mostly the same output as a real run).

dryRun : boolean
var

Type(s)

boolean

This option makes requests a simple itemized list of the changes that are being made to each file, including attribute changes.

itemizeChanges : boolean
var

Type(s)

boolean

This option will cause rsync to skip files based on checksum, not mod-time & size.

checksum : boolean
var

Type(s)

boolean

This option deletes files that don't exist on sender.

delete : boolean
var

Type(s)

boolean

Identity file.

identityFile : string
var

Type(s)

string

Owning Target object

target : \Target
inherited
var

Type(s)

\Target

Description of the task

description : string
inherited
var

Type(s)

string

Internal taskname (req)

taskType : string
inherited
var

Type(s)

string

Taskname for logger

taskName : string
inherited
var

Type(s)

string

Stored buildfile location

location : \Location
inherited
var

Type(s)

\Location

Wrapper of the task

wrapper : \RuntimeConfigurable
inherited
var

Type(s)

\RuntimeConfigurable

Holds a reference to the project that a project component (a task, a target, etc.) belongs to

project : \Project
inherited
var

A reference to the current project instance

Type(s)

\Project