FilePath (Jenkins core 2.233 API)

java.lang.Object
- hudson.FilePath

All Implemented Interfaces:

Serializable, org.jenkinsci.remoting.SerializableOnlyOverRemoting
```
public final class FilePath
extends Object
implements org.jenkinsci.remoting.SerializableOnlyOverRemoting
```
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 agent 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:
```
 void someMethod(FilePath file) {
     // make 'file' a fresh empty directory.
     file.act(new Freshen());
 }
 // if 'file' is on a different node, this FileCallable will
 // be transferred to that node and executed there.
 private static final class Freshen implements FileCallable<Void> {
     private static final long serialVersionUID = 1;
     @Override public Void invoke(File f, VirtualChannel channel) {
         // f and file represent the same thing
         f.deleteContents();
         f.mkdirs();
         return null;
     }
 }
 
```
When FilePath.FileCallable is transferred 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:

VirtualFile, Serialized Form

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`FilePath.AbstractInterceptorCallableWrapper<T>` Abstract `DelegatingCallable` that exposes an Before/After pattern for `FilePath.FileCallableWrapperFactory` that want to implement AOP-style interceptors
`static class`	`FilePath.ExplicitlySpecifiedDirScanner` Helper class to make it easy to send an explicit list of files using `FilePath` methods.
`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

Fields
Modifier and Type	Field and Description
`static hudson.remoting.LocalChannel`	`localChannel` Channel to the current instance.
`static int`	`SIDE_BUFFER_SIZE`
`static int`	`VALIDATE_ANT_FILE_MASK_BOUND` Default bound for `validateAntFileMask(String, int, boolean)`.

Constructor Summary

Constructors
Constructor and Description
`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

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`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)`
`<V> hudson.remoting.Callable<V,IOException>`	`asCallableWith(FilePath.FileCallable<V> task)` Takes a `FilePath`+`FilePath.FileCallable` pair and returns the equivalent `Callable`.
`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 streams the data to this file using the Remoting channel.
`int`	`copyRecursiveTo(DirScanner scanner, FilePath target, String description)` Copies files according to a specified scanner to a target node.
`int`	`copyRecursiveTo(DirScanner scanner, FilePath target, String description, FilePath.TarCompression compression)` Copies files according to a specified scanner to a target node.
`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()`
`long`	`getFreeDiskSpace()` Returns the number of unallocated bytes in the partition of that file.
`static FilePath`	`getHomeDirectory(hudson.remoting.VirtualChannel ch)` Gets the `FilePath` representation of the "~" directory (User's home directory in the Unix sense) of the given channel.
`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.
`long`	`getTotalDiskSpace()` Returns the total number of bytes in the partition of that file.
`long`	`getUsableDiskSpace()` Returns the number of usable bytes in the partition of that file.
`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`	`isDescendant(String potentialChildRelativePath)` Check if the relative child is really a descendant after symlink resolution if any.
`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.
`static String`	`normalize(String path)` `File.getParent()` etc cannot handle ".." and "." in the path component very well, so remove them.
`InputStream`	`read()` Reads this file.
`InputStream`	`readFromOffset(long offset)` Reads this file from the specific offset.
`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 on the remote machine.
`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.
`Computer`	`toComputer()` If this `FilePath` represents a file on a particular `Computer`, return it.
`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.
`VirtualFile`	`toVirtualFile()` Gets the `VirtualFile` representation of this `FilePath`
`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)` Deprecated. use `validateAntFileMask(String, int)` instead
`String`	`validateAntFileMask(String fileMasks, int bound)` Same as `validateAntFileMask(String, int, boolean)` with caseSensitive set to true
`String`	`validateAntFileMask(String fileMasks, int bound, boolean caseSensitive)` Like `validateAntFileMask(String)` but performing only a bounded number of operations.
`static FormValidation`	`validateFileMask(FilePath path, String value)` Short for `validateFileMask(path, value, true)`
`static FormValidation`	`validateFileMask(FilePath path, String value, boolean caseSensitive)` Shortcut for `validateFileMask(String,boolean,boolean)` with `errorIfNotExist` true, as the left-hand side can be null.
`FormValidation`	`validateFileMask(String value)` Short for `validateFileMask(value, true, true)`
`FormValidation`	`validateFileMask(String value, boolean errorIfNotExist)` Short for `validateFileMask(value, errorIfNotExist, true)`
`FormValidation`	`validateFileMask(String value, boolean errorIfNotExist, boolean caseSensitive)` 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

Methods inherited from interface org.jenkinsci.remoting.SerializableOnlyOverRemoting
getChannelForSerialization

- Field Detail
  - VALIDATE_ANT_FILE_MASK_BOUND
```
public static int VALIDATE_ANT_FILE_MASK_BOUND
```
    Default bound for validateAntFileMask(String, int, boolean).
    
    Since:
    
    1.592
  - SIDE_BUFFER_SIZE
```
public static int SIDE_BUFFER_SIZE
```
  - localChannel
```
@NonNull
public static final hudson.remoting.LocalChannel localChannel
```
    Channel to the current instance.
- Constructor Detail
  - FilePath
```
public FilePath(@CheckForNull
                hudson.remoting.VirtualChannel channel,
                @NonNull
                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(@NonNull
                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(@NonNull
                FilePath base,
                @NonNull
                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
  - normalize
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static String normalize(@NonNull
                                                                                                      String path)
```
    File.getParent() etc cannot handle ".." and "." in the path component very well, so remove them.
  - getRemote
```
public String getRemote()
```
    Gets the full path of the file on the remote machine.
  - createZipArchive
```
@Deprecated
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
```
@Deprecated
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), inserting a top-level directory into the ZIP.
    
    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(@NonNull
                                      URL archive,
                                      @CheckForNull
                                      TaskListener listener,
                                      @NonNull
                                      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 will be created.
    - The timestamp of the archive is left in the installation directory upon extraction.
    - If the timestamp left in the directory does not match 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. (For example, you could use ClassLoader.getResource(java.lang.String).)
    
    listener - If non-null, a message will be printed to this listener once this method decides to extract an archive, or if there is any issue.
    
    message - a message to be printed in case extraction will proceed.
    
    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 streams the data to this file using the Remoting channel.
    This is different from resolving URL remotely. If you instead wished to open an HTTP(S) URL on the remote side, prefer RobustHTTPClient.copyFromRemotely.
    
    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
  - asCallableWith
```
public <V> hudson.remoting.Callable<V,IOException> asCallableWith(FilePath.FileCallable<V> task)
```
    Takes a FilePath+FilePath.FileCallable pair and returns the equivalent Callable. When executing the resulting Callable, it executes act(FileCallable) on this FilePath.
    
    Since:
    
    1.522
  - 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
  - toVirtualFile
```
public VirtualFile toVirtualFile()
```
    Gets the VirtualFile representation of this FilePath
    
    Since:
    
    1.532
  - toComputer
```
@CheckForNull
public Computer toComputer()
```
    If this FilePath represents a file on a particular Computer, return it. Otherwise null.
    
    Since:
    
    1.571
  - 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
```
@CheckForNull
public FilePath sibling(String rel)
```
    Short for getParent().child(rel). Useful for getting other files in the same directory.
    
    Returns:
    
    null if getParent() would have
  - withSuffix
```
public FilePath withSuffix(String suffix)
```
    Returns a FilePath by adding the given suffix to this path name.
  - child
```
@NonNull
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
```
@CheckForNull
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:
    
    Files.createTempDirectory(Path, String, FileAttribute[])
  - 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
  - getFreeDiskSpace
```
public long getFreeDiskSpace()
                      throws IOException,
                             InterruptedException
```
    Returns the number of unallocated bytes in the partition of that file.
    
    Throws:
    
    IOException
    
    InterruptedException
    
    Since:
    
    1.542
  - getTotalDiskSpace
```
public long getTotalDiskSpace()
                       throws IOException,
                              InterruptedException
```
    Returns the total number of bytes in the partition of that file.
    
    Throws:
    
    IOException
    
    InterruptedException
    
    Since:
    
    1.542
  - getUsableDiskSpace
```
public long getUsableDiskSpace()
                        throws IOException,
                               InterruptedException
```
    Returns the number of usable bytes in the partition of that file.
    
    Throws:
    
    IOException
    
    InterruptedException
    
    Since:
    
    1.542
  - 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)
    Only supports setting read, write, or execute permissions for the owner, group, or others, so the largest permissible value is 0777. Attempting to set larger values (i.e. the setgid, setuid, or sticky bits) will cause an IOException to be thrown.
    
    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
```
@NonNull
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
```
@NonNull
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
```
@NonNull
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
```
@NonNull
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
```
@NonNull
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
```
@NonNull
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,
                        InterruptedException
```
    Reads this file.
    
    Throws:
    
    IOException
    
    InterruptedException
  - readFromOffset
```
public InputStream readFromOffset(long offset)
                           throws IOException,
                                  InterruptedException
```
    Reads this file from the specific offset.
    
    Throws:
    
    IOException
    
    InterruptedException
    
    Since:
    
    1.586
  - readToString
```
public String readToString()
                    throws IOException,
                           InterruptedException
```
    Reads this file into a string, by using the current system encoding on the remote machine.
    
    Throws:
    
    IOException
    
    InterruptedException
  - 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 on the remote machine.
    
    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
    
    See Also:
    
    Util.getDigestOf(File)
  - 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
  - copyRecursiveTo
```
public int copyRecursiveTo(DirScanner scanner,
                           FilePath target,
                           String description)
                    throws IOException,
                           InterruptedException
```
    Copies files according to a specified scanner to a target node.
    
    Parameters:
    
    scanner - a way of enumerating some files (must be serializable for possible delivery to remote side)
    
    target - the destination basedir
    
    description - a description of the fileset, for logging purposes
    
    Returns:
    
    the number of files copied
    
    Throws:
    
    IOException
    
    InterruptedException
    
    Since:
    
    1.532
  - copyRecursiveTo
```
public int copyRecursiveTo(DirScanner scanner,
                           FilePath target,
                           String description,
                           @NonNull
                           FilePath.TarCompression compression)
                    throws IOException,
                           InterruptedException
```
    Copies files according to a specified scanner to a target node.
    
    Parameters:
    
    scanner - a way of enumerating some files (must be serializable for possible delivery to remote side)
    
    target - the destination basedir
    
    description - a description of the fileset, for logging purposes
    
    compression - compression to use
    
    Returns:
    
    the number of files copied
    
    Throws:
    
    IOException
    
    InterruptedException
    
    Since:
    
    2.196
  - 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
```
@Deprecated
public String validateAntFileMask(String fileMasks)
                                       throws IOException,
                                              InterruptedException
```
    Deprecated. use validateAntFileMask(String, int) instead
    
    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
```
    Same as validateAntFileMask(String, int, boolean) with caseSensitive set to true
    
    Throws:
    
    IOException
    
    InterruptedException
  - validateAntFileMask
```
@CheckForNull
public String validateAntFileMask(String fileMasks,
                                                int bound,
                                                boolean caseSensitive)
                                         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; try VALIDATE_ANT_FILE_MASK_BOUND
    
    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(@CheckForNull
                                              FilePath path,
                                              String value)
                                       throws IOException
```
    Short for validateFileMask(path, value, true)
    
    Throws:
    
    IOException
  - validateFileMask
```
public static FormValidation validateFileMask(@CheckForNull
                                              FilePath path,
                                              String value,
                                              boolean caseSensitive)
                                       throws IOException
```
    Shortcut for validateFileMask(String,boolean,boolean) with errorIfNotExist true, as the left-hand side can be null.
    
    Throws:
    
    IOException
  - validateFileMask
```
public FormValidation validateFileMask(String value)
                                throws IOException
```
    Short for validateFileMask(value, true, true)
    
    Throws:
    
    IOException
  - validateFileMask
```
public FormValidation validateFileMask(String value,
                                       boolean errorIfNotExist)
                                throws IOException
```
    Short for validateFileMask(value, errorIfNotExist, true)
    
    Throws:
    
    IOException
  - validateFileMask
```
public FormValidation validateFileMask(String value,
                                       boolean errorIfNotExist,
                                       boolean caseSensitive)
                                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.
  - getHomeDirectory
```
public static FilePath getHomeDirectory(hudson.remoting.VirtualChannel ch)
                                 throws InterruptedException,
                                        IOException
```
    Gets the FilePath representation of the "~" directory (User's home directory in the Unix sense) of the given channel.
    
    Throws:
    
    InterruptedException
    
    IOException
  - isDescendant
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public boolean isDescendant(@NonNull
                                                                                                   String potentialChildRelativePath)
                                                                                            throws IOException,
                                                                                                   InterruptedException
```
    Check if the relative child is really a descendant after symlink resolution if any. TODO un-restrict it in a weekly after the patch
    
    Throws:
    
    IOException
    
    InterruptedException

Class FilePath

Using FilePath smartly

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Methods inherited from interface org.jenkinsci.remoting.SerializableOnlyOverRemoting

Field Detail

VALIDATE_ANT_FILE_MASK_BOUND

SIDE_BUFFER_SIZE

localChannel

Constructor Detail

FilePath

FilePath

FilePath

Method Detail

normalize

getRemote

createZipArchive

zip

zip

zip

createZipArchive

zip

zip

archive

archive

archive

unzip

untar

unzipFrom

absolutize

symlinkTo

readLink

equals

hashCode

untarFrom

installIfNecessaryFrom

copyFrom

copyFrom

copyFrom

copyFrom

act

actAsync

act

asCallableWith

toURI

toVirtualFile

toComputer

mkdirs

deleteRecursive

deleteContents

getBaseName

getName

sibling

withSuffix

child

getParent

createTempFile

createTextTempFile

createTextTempFile

createTempDir

delete

exists

lastModified

touch

isDirectory

length

getFreeDiskSpace

getTotalDiskSpace

getUsableDiskSpace

chmod

mode

list

listDirectories

list

list

list

list

Using `FilePath` smartly