hudson
Class FilePath

java.lang.Object
  hudson.FilePath

All Implemented Interfaces:

Serializable

public final class FilePath
extends Object
implements Serializable

File like object with remoting support.

Unlike File, which always implies a file path on the current computer, FilePath represents a file path on a specific slave or the master. Despite that, FilePath can be used much like File. It exposes a bunch of operations (and we should add more operations as long as they are generally useful), and when invoked against a file on a remote node, FilePath executes the necessary code remotely, thereby providing semi-transparent file operations.

Using FilePath smartly

The transparency makes it easy to write plugins without worrying too much about remoting, by making it works like NFS, where remoting happens at the file-system layer.

But one should note that such use of remoting may not be optional. Sometimes, it makes more sense to move some computation closer to the data, as opposed to move the data to the computation. For example, if you are just computing a MD5 digest of a file, then it would make sense to do the digest on the host where the file is located, as opposed to send the whole data to the master and do MD5 digesting there.

FilePath supports this "code migration" by in the act(FileCallable) method. One can pass in a custom implementation of FilePath.FileCallable, to be executed on the node where the data is located. The following code shows the example:

 FilePath file = ...;

 // make 'file' a fresh empty directory.
 file.act(new FileCallable<Void>() {
   // if 'file' is on a different node, this FileCallable will
   // be transfered to that node and executed there.
   public Void invoke(File f,VirtualChannel channel) {
     // f and file represents the same thing
     f.deleteContents();
     f.mkdirs();
   }
 });
 

When FilePath.FileCallable is transfered to a remote node, it will be done so by using the same Java serialization scheme that the remoting module uses. See Channel for more about this.

FilePath itself can be sent over to a remote node as a part of Callable serialization. For example, sending a FilePath of a remote node to that node causes FilePath to become "local". Similarly, sending a FilePath that represents the local computer causes it to become "remote."

Author:

Kohsuke Kawaguchi

See Also:

Serialized Form

Nested Class Summary

static class	FilePath.AbstractInterceptorCallableWrapper<T> Abstract DelegatingCallable that exposes an Before/After pattern for FilePath.FileCallableWrapperFactory that want to implement AOP-style interceptors
static interface	FilePath.FileCallable<T> Code that gets executed on the machine where the FilePath is local.
static class	FilePath.FileCallableWrapperFactory This extension point allows to contribute a wrapper around a fileCallable so that a plugin can "intercept" a call.
static class	FilePath.TarCompression Supported tar file compression methods.

Field Summary

static int

SIDE_BUFFER_SIZE

Constructor Summary

FilePath(File localPath)
To create FilePath that represents a "local" path.

FilePath(FilePath base, String rel)
Construct a path starting with a base location.

FilePath(hudson.remoting.VirtualChannel channel, String remote)
Creates a FilePath that represents a path on the given node.

Method Summary

FilePath	absolutize() Absolutizes this FilePath and returns the new one.
<V,E extends Throwable> V	act(hudson.remoting.Callable<V,E> callable) Executes some program on the machine that this FilePath exists, so that one can perform local file operations.
<T> T	act(FilePath.FileCallable<T> callable) Executes some program on the machine that this FilePath exists, so that one can perform local file operations.
<T> hudson.remoting.Future<T>	actAsync(FilePath.FileCallable<T> callable) Executes some program on the machine that this FilePath exists, so that one can perform local file operations.
int	archive(ArchiverFactory factory, OutputStream os, DirScanner scanner) Archives this directory into the specified archive format, to the given OutputStream, by using DirScanner to choose what files to include.
int	archive(ArchiverFactory factory, OutputStream os, FileFilter filter)
int	archive(ArchiverFactory factory, OutputStream os, String glob)
FilePath	child(String relOrAbsolute) The same as FilePath(FilePath,String) but more OO.
void	chmod(int mask) Sets the file permission.
void	copyFrom(org.apache.commons.fileupload.FileItem file) Place the data from FileItem into the file location specified by this FilePath object.
void	copyFrom(FilePath src) Convenience method to call copyTo(FilePath).
void	copyFrom(InputStream in) Replaces the content of this file by the data from the given InputStream.
void	copyFrom(URL url) Reads the URL on the current VM, and writes all the data to this FilePath (this is different from resolving URL remotely.)
int	copyRecursiveTo(FilePath target) Copies the contents of this directory recursively into the specified target directory.
int	copyRecursiveTo(String fileMask, FilePath target) Copies the files that match the given file mask to the specified target node.
int	copyRecursiveTo(String fileMask, String excludes, FilePath target) Copies the files that match the given file mask to the specified target node.
void	copyTo(FilePath target) Copies this file to the specified target.
void	copyTo(OutputStream os) Sends the contents of this file into the given OutputStream.
void	copyToWithPermission(FilePath target) Copies this file to the specified target, with file permissions and other meta attributes intact.
Launcher	createLauncher(TaskListener listener) Creates a Launcher for starting processes on the node that has this file.
FilePath	createTempDir(String prefix, String suffix) Creates a temporary directory inside the directory represented by 'this'
FilePath	createTempFile(String prefix, String suffix) Creates a temporary file in the directory that this FilePath object designates.
FilePath	createTextTempFile(String prefix, String suffix, String contents) Creates a temporary file in this directory and set the contents to the given text (encoded in the platform default encoding)
FilePath	createTextTempFile(String prefix, String suffix, String contents, boolean inThisDirectory) Creates a temporary file in this directory (or the system temporary directory) and set the contents to the given text (encoded in the platform default encoding)
void	createZipArchive(OutputStream os) Deprecated. as of 1.315. Use zip(OutputStream) that has more consistent name.
void	createZipArchive(OutputStream os, String glob) Deprecated. as of 1.315 Use zip(OutputStream,String) that has more consistent name.
boolean	delete() Deletes this file.
void	deleteContents() Deletes all the contents of this directory, but not the directory itself
void	deleteRecursive() Deletes this directory, including all its contents recursively.
String	digest() Computes the MD5 digest of the file in hex string.
boolean	equals(Object o)
boolean	exists() Checks if the file exists.
String	getBaseName() Gets the file name portion except the extension.
hudson.remoting.VirtualChannel	getChannel()
String	getName() Gets just the file name portion without directories.
FilePath	getParent() Gets the parent file.
String	getRemote() Gets the full path of the file on the remote machine.
int	hashCode()
boolean	installIfNecessaryFrom(URL archive, TaskListener listener, String message) Given a tgz/zip file, extracts it to the given target directory, if necessary.
boolean	isDirectory() Checks if the file is a directory.
boolean	isRemote() Returns true if this FilePath represents a remote file.
long	lastModified() Gets the last modified time stamp of this file, by using the clock of the machine where this file actually resides.
long	length() Returns the file size in bytes.
List<FilePath>	list() List up files and directories in this directory.
List<FilePath>	list(FileFilter filter) List up files in this directory, just like File.listFiles(FileFilter).
FilePath[]	list(String includes) List up files in this directory that matches the given Ant-style filter.
FilePath[]	list(String includes, String excludes) List up files in this directory that matches the given Ant-style filter.
FilePath[]	list(String includes, String excludes, boolean defaultExcludes) List up files in this directory that matches the given Ant-style filter.
List<FilePath>	listDirectories() List up subdirectories.
void	mkdirs() Creates this directory.
int	mode() Gets the file permission bit mask.
void	moveAllChildrenTo(FilePath target) Moves all the contents of this directory into the specified directory, then delete this directory itself.
InputStream	read() Reads this file.
String	readLink() Resolves symlink, if the given file is a symlink.
String	readToString() Reads this file into a string, by using the current system encoding.
void	renameTo(FilePath target) Rename this file/directory to the target filepath.
FilePath	sibling(String rel) Short for getParent().child(rel).
void	symlinkTo(String target, TaskListener listener) Creates a symlink to the specified target.
int	tar(OutputStream out, DirScanner scanner) Uses the given scanner on 'this' directory to list up files and then archive it to a tar stream.
int	tar(OutputStream out, FileFilter filter)
int	tar(OutputStream out, String glob) Writes files in 'this' directory to a tar stream.
String	toString() Deprecated.
void	touch(long timestamp) Creates a file (if not already exist) and sets the timestamp.
URI	toURI() Converts this file to the URI, relative to the machine on which this file is available.
void	untar(FilePath target, FilePath.TarCompression compression) When this FilePath represents a tar file, extracts that tar file.
void	untarFrom(InputStream _in, FilePath.TarCompression compression) Reads the given InputStream as a tar file and extracts it into this directory.
void	unzip(FilePath target) When this FilePath represents a zip file, extracts that zip file.
void	unzipFrom(InputStream _in) Reads the given InputStream as a zip file and extracts it into this directory.
String	validateAntFileMask(String fileMasks) Validates the ant file mask (like "foo/bar/*.txt, zot/*.jar") against this directory, and try to point out the problem.
String	validateAntFileMask(String fileMasks, int bound) Like validateAntFileMask(String) but performing only a bounded number of operations.
static FormValidation	validateFileMask(FilePath pathOrNull, String value) Shortcut for validateFileMask(String) in case the left-hand side can be null.
FormValidation	validateFileMask(String value) Short for validateFileMask(value,true)
FormValidation	validateFileMask(String value, boolean errorIfNotExist) Checks the GLOB-style file mask.
FormValidation	validateRelativeDirectory(String value)
FormValidation	validateRelativeDirectory(String value, boolean errorIfNotExist) A convenience method over validateRelativePath(String, boolean, boolean).
FormValidation	validateRelativePath(String value, boolean errorIfNotExist, boolean expectingFile) Validates a relative file path from this FilePath.
FilePath	withSuffix(String suffix) Returns a FilePath by adding the given suffix to this path name.
OutputStream	write() Writes to this file.
void	write(String content, String encoding) Overwrites this file by placing the given String as the content.
void	zip(FilePath dst)
void	zip(OutputStream os) Creates a zip file from this directory or a file and sends that to the given output stream.
int	zip(OutputStream out, DirScanner scanner) Uses the given scanner on 'this' directory to list up files and then archive it to a zip stream.
void	zip(OutputStream os, FileFilter filter) Creates a zip file from this directory by using the specified filter, and sends the result to the given output stream.
void	zip(OutputStream os, String glob) Creates a zip file from this directory by only including the files that match the given glob.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

SIDE_BUFFER_SIZE

public static int SIDE_BUFFER_SIZE

Constructor Detail

FilePath

public FilePath(hudson.remoting.VirtualChannel channel,
                String remote)

Creates a FilePath that represents a path on the given node.

Parameters:

channel - To create a path that represents a remote path, pass in a Channel that's connected to that machine. If null, that means the local file path.

FilePath

public FilePath(File localPath)

To create FilePath that represents a "local" path.

A "local" path means a file path on the computer where the constructor invocation happened.

FilePath

public FilePath(FilePath base,
                String rel)

Construct a path starting with a base location.

Parameters:

base - starting point for resolution, and defines channel

rel - a path which if relative will be resolved against base

Method Detail

getRemote

public String getRemote()

Gets the full path of the file on the remote machine.

createZipArchive

public void createZipArchive(OutputStream os)
                      throws IOException,
                             InterruptedException

Deprecated. as of 1.315. Use zip(OutputStream) that has more consistent name.

Creates a zip file from this directory or a file and sends that to the given output stream.

Throws:

IOException

InterruptedException

zip

public void zip(OutputStream os)
         throws IOException,
                InterruptedException

Creates a zip file from this directory or a file and sends that to the given output stream.

Throws:

IOException

InterruptedException

zip

public void zip(FilePath dst)
         throws IOException,
                InterruptedException

Throws:

IOException

InterruptedException

zip

public void zip(OutputStream os,
                FileFilter filter)
         throws IOException,
                InterruptedException

Creates a zip file from this directory by using the specified filter, and sends the result to the given output stream.

Parameters:

filter - Must be serializable since it may be executed remotely. Can be null to add all files.

Throws:

IOException

InterruptedException

Since:

1.315

createZipArchive

public void createZipArchive(OutputStream os,
                             String glob)
                      throws IOException,
                             InterruptedException

Deprecated. as of 1.315 Use zip(OutputStream,String) that has more consistent name.

Creates a zip file from this directory by only including the files that match the given glob.

Parameters:

glob - Ant style glob, like "**/*.xml". If empty or null, this method works like createZipArchive(OutputStream)

Throws:

IOException

InterruptedException

Since:

1.129

zip

public void zip(OutputStream os,
                String glob)
         throws IOException,
                InterruptedException

Creates a zip file from this directory by only including the files that match the given glob.

Parameters:

glob - Ant style glob, like "**/*.xml". If empty or null, this method works like createZipArchive(OutputStream)

Throws:

IOException

InterruptedException

Since:

1.315

zip

public int zip(OutputStream out,
               DirScanner scanner)
        throws IOException,
               InterruptedException

Uses the given scanner on 'this' directory to list up files and then archive it to a zip stream.

Throws:

IOException

InterruptedException

archive

public int archive(ArchiverFactory factory,
                   OutputStream os,
                   DirScanner scanner)
            throws IOException,
                   InterruptedException

Archives this directory into the specified archive format, to the given OutputStream, by using DirScanner to choose what files to include.

Returns:

number of files/directories archived. This is only really useful to check for a situation where nothing is archived.

Throws:

IOException

InterruptedException

archive

public int archive(ArchiverFactory factory,
                   OutputStream os,
                   FileFilter filter)
            throws IOException,
                   InterruptedException

Throws:

IOException

InterruptedException

archive

public int archive(ArchiverFactory factory,
                   OutputStream os,
                   String glob)
            throws IOException,
                   InterruptedException

Throws:

IOException

InterruptedException

unzip

public void unzip(FilePath target)
           throws IOException,
                  InterruptedException

When this FilePath represents a zip file, extracts that zip file.

Parameters:

target - Target directory to expand files to. All the necessary directories will be created.

Throws:

IOException

InterruptedException

Since:

1.248

See Also:

unzipFrom(InputStream)

untar

public void untar(FilePath target,
                  FilePath.TarCompression compression)
           throws IOException,
                  InterruptedException

When this FilePath represents a tar file, extracts that tar file.

Parameters:

target - Target directory to expand files to. All the necessary directories will be created.

compression - Compression mode of this tar file.

Throws:

IOException

InterruptedException

Since:

1.292

See Also:

untarFrom(InputStream, TarCompression)

unzipFrom

public void unzipFrom(InputStream _in)
               throws IOException,
                      InterruptedException

Reads the given InputStream as a zip file and extracts it into this directory.

Parameters:

_in - The stream will be closed by this method after it's fully read.

Throws:

IOException

InterruptedException

Since:

1.283

See Also:

unzip(FilePath)

absolutize

public FilePath absolutize()
                    throws IOException,
                           InterruptedException

Absolutizes this FilePath and returns the new one.

Throws:

IOException

InterruptedException

symlinkTo

public void symlinkTo(String target,
                      TaskListener listener)
               throws IOException,
                      InterruptedException

Creates a symlink to the specified target.

Parameters:

target - The file that the symlink should point to.

listener - If symlink creation requires a help of an external process, the error will be reported here.

Throws:

IOException

InterruptedException

Since:

1.456

readLink

public String readLink()
                throws IOException,
                       InterruptedException

Resolves symlink, if the given file is a symlink. Otherwise return null.

If the resolution fails, report an error.

Throws:

IOException

InterruptedException

Since:

1.456

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

untarFrom

public void untarFrom(InputStream _in,
                      FilePath.TarCompression compression)
               throws IOException,
                      InterruptedException

Reads the given InputStream as a tar file and extracts it into this directory.

Parameters:

_in - The stream will be closed by this method after it's fully read.

compression - The compression method in use.

Throws:

IOException

InterruptedException

Since:

1.292

installIfNecessaryFrom

public boolean installIfNecessaryFrom(URL archive,
                                      TaskListener listener,
                                      String message)
                               throws IOException,
                                      InterruptedException

Given a tgz/zip file, extracts it to the given target directory, if necessary.

This method is a convenience method designed for installing a binary package to a location that supports upgrade and downgrade. Specifically,

• If the target directory doesn't exist it'll be created.
• The timestamp of the .tgz file is left in the installation directory upon extraction.
• If the timestamp left in the directory doesn't match with the timestamp of the current archive file, the directory contents will be discarded and the archive file will be re-extracted.
• If the connection is refused but the target directory already exists, it is left alone.

Parameters:

archive - The resource that represents the tgz/zip file. This URL must support the "Last-Modified" header. (Most common usage is to get this from ClassLoader.getResource(String))

listener - If non-null, a message will be printed to this listener once this method decides to extract an archive.

Returns:

true if the archive was extracted. false if the extraction was skipped because the target directory was considered up to date.

Throws:

IOException

InterruptedException

Since:

1.299

copyFrom

public void copyFrom(URL url)
              throws IOException,
                     InterruptedException

Reads the URL on the current VM, and writes all the data to this FilePath (this is different from resolving URL remotely.)

Throws:

IOException

InterruptedException

Since:

1.293

copyFrom

public void copyFrom(InputStream in)
              throws IOException,
                     InterruptedException

Replaces the content of this file by the data from the given InputStream.

Throws:

IOException

InterruptedException

Since:

1.293

copyFrom

public void copyFrom(FilePath src)
              throws IOException,
                     InterruptedException

Convenience method to call copyTo(FilePath).

Throws:

IOException

InterruptedException

Since:

1.311

copyFrom

public void copyFrom(org.apache.commons.fileupload.FileItem file)
              throws IOException,
                     InterruptedException

Place the data from FileItem into the file location specified by this FilePath object.

Throws:

IOException

InterruptedException

act

public <T> T act(FilePath.FileCallable<T> callable)
      throws IOException,
             InterruptedException

Executes some program on the machine that this FilePath exists, so that one can perform local file operations.

Throws:

IOException

InterruptedException

actAsync

public <T> hudson.remoting.Future<T> actAsync(FilePath.FileCallable<T> callable)
                                   throws IOException,
                                          InterruptedException

Executes some program on the machine that this FilePath exists, so that one can perform local file operations.

Throws:

IOException

InterruptedException

act

public <V,E extends Throwable> V act(hudson.remoting.Callable<V,E> callable)
      throws IOException,
             InterruptedException,
             E extends Throwable

Executes some program on the machine that this FilePath exists, so that one can perform local file operations.

Throws:

IOException

InterruptedException

E extends Throwable

toURI

public URI toURI()
          throws IOException,
                 InterruptedException

Converts this file to the URI, relative to the machine on which this file is available.

Throws:

IOException

InterruptedException

mkdirs

public void mkdirs()
            throws IOException,
                   InterruptedException

Creates this directory.

Throws:

IOException

InterruptedException

deleteRecursive

public void deleteRecursive()
                     throws IOException,
                            InterruptedException

Deletes this directory, including all its contents recursively.

Throws:

IOException

InterruptedException

deleteContents

public void deleteContents()
                    throws IOException,
                           InterruptedException

Deletes all the contents of this directory, but not the directory itself

Throws:

IOException

InterruptedException

getBaseName

public String getBaseName()

Gets the file name portion except the extension. For example, "foo" for "foo.txt" and "foo.tar" for "foo.tar.gz".

getName

public String getName()

Gets just the file name portion without directories. For example, "foo.txt" for "../abc/foo.txt"

sibling

public FilePath sibling(String rel)

Short for getParent().child(rel). Useful for getting other files in the same directory.

withSuffix

public FilePath withSuffix(String suffix)

Returns a FilePath by adding the given suffix to this path name.

child

public FilePath child(String relOrAbsolute)

The same as FilePath(FilePath,String) but more OO.

Parameters:

relOrAbsolute - a relative or absolute path

Returns:

a file on the same channel

getParent

public FilePath getParent()

Gets the parent file.

Returns:

parent FilePath or null if there is no parent

createTempFile

public FilePath createTempFile(String prefix,
                               String suffix)
                        throws IOException,
                               InterruptedException

Creates a temporary file in the directory that this FilePath object designates.

Parameters:

prefix - The prefix string to be used in generating the file's name; must be at least three characters long

suffix - The suffix string to be used in generating the file's name; may be null, in which case the suffix ".tmp" will be used

Returns:

The new FilePath pointing to the temporary file

Throws:

IOException

InterruptedException

See Also:

File.createTempFile(String, String)

createTextTempFile

public FilePath createTextTempFile(String prefix,
                                   String suffix,
                                   String contents)
                            throws IOException,
                                   InterruptedException

Creates a temporary file in this directory and set the contents to the given text (encoded in the platform default encoding)

Parameters:

prefix - The prefix string to be used in generating the file's name; must be at least three characters long

suffix - The suffix string to be used in generating the file's name; may be null, in which case the suffix ".tmp" will be used

contents - The initial contents of the temporary file.

Returns:

The new FilePath pointing to the temporary file

Throws:

IOException

InterruptedException

See Also:

File.createTempFile(String, String)

createTextTempFile

public FilePath createTextTempFile(String prefix,
                                   String suffix,
                                   String contents,
                                   boolean inThisDirectory)
                            throws IOException,
                                   InterruptedException

Creates a temporary file in this directory (or the system temporary directory) and set the contents to the given text (encoded in the platform default encoding)

Parameters:

prefix - The prefix string to be used in generating the file's name; must be at least three characters long

suffix - The suffix string to be used in generating the file's name; may be null, in which case the suffix ".tmp" will be used

contents - The initial contents of the temporary file.

inThisDirectory - If true, then create this temporary in the directory pointed to by this. If false, then the temporary file is created in the system temporary directory (java.io.tmpdir)

Returns:

The new FilePath pointing to the temporary file

Throws:

IOException

InterruptedException

See Also:

File.createTempFile(String, String)

createTempDir

public FilePath createTempDir(String prefix,
                              String suffix)
                       throws IOException,
                              InterruptedException

Creates a temporary directory inside the directory represented by 'this'

Parameters:

prefix - The prefix string to be used in generating the directory's name; must be at least three characters long

suffix - The suffix string to be used in generating the directory's name; may be null, in which case the suffix ".tmp" will be used

Returns:

The new FilePath pointing to the temporary directory

Throws:

IOException

InterruptedException

Since:

1.311

See Also:

File.createTempFile(String, String)

delete

public boolean delete()
               throws IOException,
                      InterruptedException

Deletes this file.

Returns:

true, for a modicum of compatibility

Throws:

IOException - if it exists but could not be successfully deleted

InterruptedException

exists

public boolean exists()
               throws IOException,
                      InterruptedException

Checks if the file exists.

Throws:

IOException

InterruptedException

lastModified

public long lastModified()
                  throws IOException,
                         InterruptedException

Gets the last modified time stamp of this file, by using the clock of the machine where this file actually resides.

Throws:

IOException

InterruptedException

See Also:

File.lastModified(), touch(long)

touch

public void touch(long timestamp)
           throws IOException,
                  InterruptedException

Creates a file (if not already exist) and sets the timestamp.

Throws:

IOException

InterruptedException

Since:

1.299

isDirectory

public boolean isDirectory()
                    throws IOException,
                           InterruptedException

Checks if the file is a directory.

Throws:

IOException

InterruptedException

length

public long length()
            throws IOException,
                   InterruptedException

Returns the file size in bytes.

Throws:

IOException

InterruptedException

Since:

1.129

chmod

public void chmod(int mask)
           throws IOException,
                  InterruptedException

Sets the file permission. On Windows, no-op.

Parameters:

mask - File permission mask. To simplify the permission copying, if the parameter is -1, this method becomes no-op.

please note mask is expected to be an octal if you use chmod command line values, so preceded by a '0' in java notation, ie chmod(0644)

Throws:

IOException

InterruptedException

Since:

1.303

See Also:

mode()

mode

public int mode()
         throws IOException,
                InterruptedException,
                PosixException

Gets the file permission bit mask.

Returns:

-1 on Windows, since such a concept doesn't make sense.

Throws:

IOException

InterruptedException

PosixException

Since:

1.311

See Also:

chmod(int)

list

public List<FilePath> list()
                    throws IOException,
                           InterruptedException

List up files and directories in this directory.

This method returns direct children of the directory denoted by the 'this' object.

Throws:

IOException

InterruptedException

listDirectories

public List<FilePath> listDirectories()
                               throws IOException,
                                      InterruptedException

List up subdirectories.

Returns:

can be empty but never null. Doesn't contain "." and ".."

Throws:

IOException

InterruptedException

list

public List<FilePath> list(FileFilter filter)
                    throws IOException,
                           InterruptedException

List up files in this directory, just like File.listFiles(FileFilter).

Parameters:

filter - The optional filter used to narrow down the result. If non-null, must be Serializable. If this FilePath represents a remote path, the filter object will be executed on the remote machine.

Throws:

IOException

InterruptedException

list

public FilePath[] list(String includes)
                throws IOException,
                       InterruptedException

List up files in this directory that matches the given Ant-style filter.

Parameters:

includes - See FileSet for the syntax. String like "foo/*.zip" or "foo/**/*.xml"

Returns:

can be empty but always non-null.

Throws:

IOException

InterruptedException

list

public FilePath[] list(String includes,
                       String excludes)
                throws IOException,
                       InterruptedException

List up files in this directory that matches the given Ant-style filter.

Parameters:

includes -

excludes - See FileSet for the syntax. String like "foo/*.zip" or "foo/**/*.xml"

Returns:

can be empty but always non-null.

Throws:

IOException

InterruptedException

Since:

1.407

list

public FilePath[] list(String includes,
                       String excludes,
                       boolean defaultExcludes)
                throws IOException,
                       InterruptedException

List up files in this directory that matches the given Ant-style filter.

Parameters:

includes -

excludes - See FileSet for the syntax. String like "foo/*.zip" or "foo/**/*.xml"

defaultExcludes - whether to use the ant default excludes

Returns:

can be empty but always non-null.

Throws:

IOException

InterruptedException

Since:

1.465

read

public InputStream read()
                 throws IOException

Reads this file.

Throws:

IOException

readToString

public String readToString()
                    throws IOException

Reads this file into a string, by using the current system encoding.

Throws:

IOException

write

public OutputStream write()
                   throws IOException,
                          InterruptedException

Writes to this file. If this file already exists, it will be overwritten. If the directory doesn't exist, it will be created.

I/O operation to remote FilePath happens asynchronously, meaning write operations to the returned OutputStream will return without receiving a confirmation from the remote that the write happened. I/O operations also happens asynchronously from the Channel.call(Callable) operations, so if you write to a remote file and then execute Channel.call(Callable) and try to access the newly copied file, it might not be fully written yet.

Throws:

IOException

InterruptedException

write

public void write(String content,
                  String encoding)
           throws IOException,
                  InterruptedException

Overwrites this file by placing the given String as the content.

Parameters:

encoding - Null to use the platform default encoding.

Throws:

IOException

InterruptedException

Since:

1.105

digest

public String digest()
              throws IOException,
                     InterruptedException

Computes the MD5 digest of the file in hex string.

Throws:

IOException

InterruptedException

renameTo

public void renameTo(FilePath target)
              throws IOException,
                     InterruptedException

Rename this file/directory to the target filepath. This FilePath and the target must be on the some host

Throws:

IOException

InterruptedException

moveAllChildrenTo

public void moveAllChildrenTo(FilePath target)
                       throws IOException,
                              InterruptedException

Moves all the contents of this directory into the specified directory, then delete this directory itself.

Throws:

IOException

InterruptedException

Since:

1.308.

copyTo

public void copyTo(FilePath target)
            throws IOException,
                   InterruptedException

Copies this file to the specified target.

Throws:

IOException

InterruptedException

copyToWithPermission

public void copyToWithPermission(FilePath target)
                          throws IOException,
                                 InterruptedException

Copies this file to the specified target, with file permissions and other meta attributes intact.

Throws:

IOException

InterruptedException

Since:

1.311

copyTo

public void copyTo(OutputStream os)
            throws IOException,
                   InterruptedException

Sends the contents of this file into the given OutputStream.

Throws:

IOException

InterruptedException

copyRecursiveTo

public int copyRecursiveTo(FilePath target)
                    throws IOException,
                           InterruptedException

Copies the contents of this directory recursively into the specified target directory.

Returns:

the number of files copied.

Throws:

IOException

InterruptedException

Since:

1.312

copyRecursiveTo

public int copyRecursiveTo(String fileMask,
                           FilePath target)
                    throws IOException,
                           InterruptedException

Copies the files that match the given file mask to the specified target node.

Parameters:

fileMask - Ant GLOB pattern. String like "foo/bar/*.xml" Multiple patterns can be separated by ',', and whitespace can surround ',' (so that you can write "abc, def" and "abc,def" to mean the same thing.

Returns:

the number of files copied.

Throws:

IOException

InterruptedException

copyRecursiveTo

public int copyRecursiveTo(String fileMask,
                           String excludes,
                           FilePath target)
                    throws IOException,
                           InterruptedException

Copies the files that match the given file mask to the specified target node.

Parameters:

fileMask - Ant GLOB pattern. String like "foo/bar/*.xml" Multiple patterns can be separated by ',', and whitespace can surround ',' (so that you can write "abc, def" and "abc,def" to mean the same thing.

excludes - Files to be excluded. Can be null.

Returns:

the number of files copied.

Throws:

IOException

InterruptedException

tar

public int tar(OutputStream out,
               String glob)
        throws IOException,
               InterruptedException

Writes files in 'this' directory to a tar stream.

Parameters:

glob - Ant file pattern mask, like "**/*.java".

Throws:

IOException

InterruptedException

tar

public int tar(OutputStream out,
               FileFilter filter)
        throws IOException,
               InterruptedException

Throws:

IOException

InterruptedException

tar

public int tar(OutputStream out,
               DirScanner scanner)
        throws IOException,
               InterruptedException

Uses the given scanner on 'this' directory to list up files and then archive it to a tar stream.

Throws:

IOException

InterruptedException

createLauncher

public Launcher createLauncher(TaskListener listener)
                        throws IOException,
                               InterruptedException

Creates a Launcher for starting processes on the node that has this file.

Throws:

IOException

InterruptedException

Since:

1.89

validateAntFileMask

public String validateAntFileMask(String fileMasks)
                           throws IOException,
                                  InterruptedException

Validates the ant file mask (like "foo/bar/*.txt, zot/*.jar") against this directory, and try to point out the problem.

This is useful in conjunction with FormValidation.

Returns:

null if no error was found. Otherwise returns a human readable error message.

Throws:

IOException

InterruptedException

Since:

1.90

See Also:

validateFileMask(FilePath, String)

validateAntFileMask

public String validateAntFileMask(String fileMasks,
                                  int bound)
                           throws IOException,
                                  InterruptedException

Like validateAntFileMask(String) but performing only a bounded number of operations.

Whereas the unbounded overload is appropriate for calling from cancelable, long-running tasks such as build steps, this overload should be used when an answer is needed quickly, such as for validateFileMask(String) or anything else returning FormValidation.

If a positive match is found, null is returned immediately. A message is returned in case the file pattern can definitely be determined to not match anything in the directory within the alloted time. If the time runs out without finding a match but without ruling out the possibility that there might be one, InterruptedException is thrown, in which case the calling code should give the user the benefit of the doubt and use FormValidation.Kind.OK (with or without a message).

Parameters:

bound - a maximum number of negative operations (deliberately left vague) to perform before giving up on a precise answer; 10_000 is a reasonable pick

Throws:

InterruptedException - not only in case of a channel failure, but also if too many operations were performed without finding any matches

IOException

Since:

1.484

validateFileMask

public static FormValidation validateFileMask(FilePath pathOrNull,
                                              String value)
                                       throws IOException

Shortcut for validateFileMask(String) in case the left-hand side can be null.

Throws:

IOException

validateFileMask

public FormValidation validateFileMask(String value)
                                throws IOException

Short for validateFileMask(value,true)

Throws:

IOException

validateFileMask

public FormValidation validateFileMask(String value,
                                       boolean errorIfNotExist)
                                throws IOException

Checks the GLOB-style file mask. See validateAntFileMask(String). Requires configure permission on ancestor AbstractProject object in request, or admin permission if no such ancestor is found.

Throws:

IOException

Since:

1.294

validateRelativePath

public FormValidation validateRelativePath(String value,
                                           boolean errorIfNotExist,
                                           boolean expectingFile)
                                    throws IOException

Validates a relative file path from this FilePath. Requires configure permission on ancestor AbstractProject object in request, or admin permission if no such ancestor is found.

Parameters:

value - The relative path being validated.

errorIfNotExist - If true, report an error if the given relative path doesn't exist. Otherwise it's a warning.

expectingFile - If true, we expect the relative path to point to a file. Otherwise, the relative path is expected to be pointing to a directory.

Throws:

IOException

validateRelativeDirectory

public FormValidation validateRelativeDirectory(String value,
                                                boolean errorIfNotExist)
                                         throws IOException

A convenience method over validateRelativePath(String, boolean, boolean).

Throws:

IOException

validateRelativeDirectory

public FormValidation validateRelativeDirectory(String value)
                                         throws IOException

Throws:

IOException

toString

@Deprecated
public String toString()

Deprecated.

Overrides:

toString in class Object

getChannel

public hudson.remoting.VirtualChannel getChannel()

isRemote

public boolean isRemote()

Returns true if this FilePath represents a remote file.