Copy

<copy>

Purpose/Function

The principal Trebuchet task: copies (transfers) files from one location to another; can also copy Java-type resources (i.e., jar contents) to disk (either local or remote) by specifying one or more resource:/ source uris.

There are several ways of using this task.

copy specified URIs to a single target location (use either <uri> or <source-uri> to specify these);
copy source URIs to their corresponding target locations (use the <uri-pair> tag illustrated below);
copy an entire directory to a target location (set the sourceDir attribute); forces an Ls- operation first;
copy the contents of a directory matching a given pattern to a target location (add a pattern element using the <source> tag); forces an Ls- operation first.

The first two modes do not involve scanning or listing; hence, if the paths are incorrect, the operation will not succeed in those cases.

Attributes

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
cleanup	`boolean`	true	delete all caches upon termination of the operation
cleanupList	`boolean`	true	(if cleanup is false) delete the List cache upon termination of the operation
copyCache	`ncsa.tools.trebuchet.core.cache.CopyCache`	`null`	use this copy cache for the operation
copyCacheFile	`java.io.File`	`null`	use this copy cache for the operation
flatten	`boolean`	false	put all source files at the top-level of the target location (create a shallow target)
includeAncestors	`boolean`	false	make all the target ancestors for each corresponding source URI
listCache	`ncsa.tools.trebuchet.core.cache.ListCache`	`null`	use this list cache (and create a copy cache from it, if one is not set)
listCacheFile	`java.io.File`	`null`	use this list cache (and create a copy cache from it, if one is not set)
move	`boolean`	false	delete the source after the transfer
sourceDir	`java.net.URI`	`null`	copy this entire directory
target	`java.net.URI`	`null`	single target location

Listener control attributes

NAME	TYPE	DEFAULT VALUE	DESCRIPTION
event	`boolean`	true	if listener is a `ProgressListener`, send an event
log4j	`boolean`	false	if listener is a `ProgressListener`, use log4j
stdout	`boolean`	false	if listener is a `ProgressListener`, use stdout

Elements

TAG	TYPE	COUNT	DESCRIPTION
`<configuration>`	`ncsa.tools.trebuchet.core.types.TrebuchetConfiguration`	0:1	configuration with additional non-default settings
`<source>`	`ncsa.tools.common.types.uri.UriPattern`	0:1	pattern to use with ls-operation
`<source-uri>`	`java.net.URI`	0:N	source location
`<uri>`	`java.net.URI`	0:N	source location
`<uri-pair>`	`ncsa.tools.ogrescript.trebuchet.types.UriPair`	0:N	source-to-target pairing

Listener elements

TAG	TYPE	COUNT	DESCRIPTION
`<listener>`	`ncsa.tools.trebuchet.core.IOperationListener`	0:N	generic tag, must be used in conjunction with the absolute tag; see Overriding Relative Tags
`<logging-listener>`	`ncsa.tools.trebuchet.core.IOperationListener`	0:N	built-in type; see listeners
`<copy-progress-listener>`	`ncsa.tools.trebuchet.core.IOperationListener`	0:N	built-in type; see listeners
`<file-progress-listener>`	`ncsa.tools.trebuchet.core.IOperationListener`	0:N	built-in type; see listeners
`<list-progress-listener>`	`ncsa.tools.trebuchet.core.IOperationListener`	0:N	built-in type; see listeners
`<list-metadata-listener>`	`ncsa.tools.trebuchet.core.IOperationListener`	0:N	built-in type; see listeners

ReturnValues

DEFAULT NAME	TYPE
copy	`ncsa.tools.trebuchet.core.operations.CacheBasedOperation`

NOTES

For a given task, all source uris must share a common scheme and endpoint, and all target uris must share a common scheme and endpoint.
Cleanup defaults to true, so caches that are used will be deleted unless otherwise indicated. The operation is returned only if cleanup is false.
If includeAncestors is true, the task forces mkdir on the ancestors of the corresponding target (only applies to <uri-pair> operations).
For move operations, if directories which remain empty after the deletion should also be deleted, delete-all-empty-dirs must be explicitly set to true in the configuration.
It is possible to point the task at pre-existing caches, either as objects in the environment or as files.
Any additional settings passed in using the configuration object will be added to the default settings (the latter must be explicitly overridden if they are not desired).
An Ls- operation done in conjunction with <copy> by adding a <pattern> or setting sourceDir will automatically set the list-recursive property to true.

Examples

<ogrescript>
   <!-- MOVE FILES TO THE TARGET -->
   <copy move="true" target="file:${runtime.dir}">
       <source-uri>${WRFsrc.uri}/real.exe</source-uri>
       <source-uri>${WRFsrc.uri}/wrf.exe</source-uri>
       <source-uri>${WRFsrc.uri}/timediff.exe</source-uri>
       <source-uri>${WRFsrc.uri}/fix_fcstlen.csh</source-uri>
       <source-uri>${WRFsrc.uri}/run_wrf.csh</source-uri>
       <source-uri>${WRFsrc.uri}/run_wrf.tar</source-uri>
       <source-uri>${WRFsrc.uri}/run_wps.csh</source-uri>
       <source-uri>${WRFsrc.uri}/run_wps.tar</source-uri>
       <source-uri>${WRFsrc.uri}/run_real.csh</source-uri>
   </copy>

   <!-- COPY FILES, RENAMING THEM -->
   <copy>
       <uri-pair source="${RTsrc.uri}/wrf.namelist.template" target="file:${runtime.dir}/namelist0"/>
       <uri-pair source="${RTsrc.uri}/wps.namelist.template" target="file:${runtime.dir}/namelist1"/>
   </copy>

   <!-- COPY A DIRECTORY -->
   <copy sourceDir="gsissh://tungsten.ncsa.uiuc.edu/u/ncsa/arossi/test"
   	 target="gsissh://tg-login.ncsa.teragrid.org/home/ncsa/arossi"/>

   <!-- COPY ALL MATCHING FILES INTO TOP LEVEL OF TARGET -->
   <copy target="file:${runtime.dir}" flatten="true">
  	<configuration>
  	    <property name="transferMode" value="gridftp-stream"/>
       	    <property name="target-active" value="true" type="boolean"/>
       	    <property name="tcpBufferSize" value="2097152" type="int"/> 
  	</configuration>
        <source base="mssftp://mss.ncsa.uiuc.edu/u/ncsa/bjewett/RT/NAM/00">
           <include>**/*eta*</include>
        </source>
   </copy>
</ogrescript>

Child pages