VirtualFile (Jenkins core 2.316 API)

java.lang.Object
- jenkins.util.VirtualFile

All Implemented Interfaces:

Serializable, Comparable<VirtualFile>
```
public abstract class VirtualFile
extends Object
implements Comparable<VirtualFile>, Serializable
```
Abstraction over File, FilePath, or other items such as network resources or ZIP entries. Assumed to be read-only and makes very limited assumptions, just enough to display content and traverse directories.
To obtain a VirtualFile representation for an existing file, use forFile(File) or FilePath.toVirtualFile()
How are VirtualFile and FilePath different?

FilePath abstracts away Files on machines that are connected over Channel, whereas VirtualFile makes no assumption about where the actual files are, or whether there really exists Files somewhere. This makes VirtualFile more abstract.
Opening files from other machines
While VirtualFile is marked Serializable, it is not safe in general to transfer over a Remoting channel. (For example, an implementation from forFilePath(hudson.FilePath) could be sent on the same channel, but an implementation from forFile(java.io.File) will not.) Thus callers should assume that methods such as open() will work only on the node on which the object was created.
Since some implementations may in fact use external file storage, callers may request optional APIs to access those services more efficiently. Otherwise, for example, a plugin copying a file previously saved by ArtifactManager to an external storage service which tunneled a stream from open() using RemoteInputStream would wind up transferring the file from the service to the Jenkins master and then on to an agent. Similarly, if DirectoryBrowserSupport rendered a link to an in-Jenkins URL, a large file could be transferred from the service to the Jenkins master and then on to the browser. To avoid this overhead, callers may check whether an implementation supports toExternalURL().

Since:

1.532

See Also:

DirectoryBrowserSupport, FilePath, Serialized Form

Constructor Summary

Constructors
Constructor and Description

VirtualFile()

Constructors
Constructor and Description
`VirtualFile()`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`abstract boolean`	`canRead()` Checks whether this file can be read.
`abstract VirtualFile`	`child(String name)` Obtains a child file.
`int`	`compareTo(VirtualFile o)` Does case-insensitive comparison.
`boolean`	`containsSymLinkChild(boolean noFollowLinks)`
`boolean`	`equals(Object obj)` Compares according to `toURI()`.
`abstract boolean`	`exists()` Checks whether this file exists.
`static VirtualFile`	`forFile(File f)` Creates a virtual file wrapper for a local file.
`static VirtualFile`	`forFilePath(FilePath f)` Creates a virtual file wrapper for a remotable file.
`abstract String`	`getName()` Gets the base name, meaning just the last portion of the path name without any directories.
`abstract VirtualFile`	`getParent()` Gets the parent file.
`int`	`hashCode()` Hashes according to `toURI()`.
`boolean`	`hasSymlink(boolean noFollowLinks)` Determines when a VirtualFile has a recognized symlink.
`boolean`	`isDescendant(String childRelativePath)` Check if the relative path is really a descendant of this folder, following the symbolic links.
`abstract boolean`	`isDirectory()` Checks whether this file exists and is a directory.
`abstract boolean`	`isFile()` Checks whether this file exists and is a plain file.
`abstract long`	`lastModified()` Gets the file timestamp.
`abstract long`	`length()` Gets the file length.
`abstract VirtualFile[]`	`list()` Lists children of this directory.
`VirtualFile[]`	`list(boolean noFollowLinks)` Lists children of this directory.
`String[]`	`list(String glob)` Deprecated. use `list(String, String, boolean)` instead
`Collection<String>`	`list(String includes, String excludes, boolean useDefaultExcludes)` Lists recursive files of this directory with pattern matching.
`Collection<String>`	`list(String includes, String excludes, boolean useDefaultExcludes, boolean noFollowLinks)` Lists recursive files of this directory with pattern matching.
`List<VirtualFile>`	`listOnlyDescendants()` Lists only the children that are descendant of the root directory (not necessarily the current VirtualFile).
`int`	`mode()` Gets the file’s Unix mode, if meaningful.
`abstract InputStream`	`open()` Opens an input stream on the file so its contents can be read.
`InputStream`	`open(boolean noFollowLinks)` Opens an input stream on the file so its contents can be read.
`String`	`readLink()` If this file is a symlink, returns the link target.
`<V> V`	`run(hudson.remoting.Callable<V,IOException> callable)` Does some calculations in batch.
`boolean`	`supportIsDescendant()` Determine if the implementation supports the `isDescendant(String)` method TODO un-restrict it in a weekly after the patch
`boolean`	`supportsQuickRecursiveListing()`
`URL`	`toExternalURL()` Optionally obtains a URL which may be used to retrieve file contents from any process on any node.
`String`	`toString()` Displays `toURI()`.
`abstract URI`	`toURI()` Gets a URI.
`int`	`zip(OutputStream outputStream, String includes, String excludes, boolean useDefaultExcludes, boolean noFollowLinks, String prefix)` Create a ZIP archive from the list of folders/files using the includes and excludes to filter them.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - VirtualFile
```
public VirtualFile()
```
- Method Detail
  - getName
```
@NonNull
public abstract String getName()
```
    Gets the base name, meaning just the last portion of the path name without any directories. For a “root directory” this may be the empty string.
    
    Returns:
    
    a simple name (no slashes)
  - toURI
```
@NonNull
public abstract URI toURI()
```
    Gets a URI. Should at least uniquely identify this virtual file within its root, but not necessarily globally.
    When toExternalURL() is implemented, that same value could be used here, unless some sort of authentication is also embedded.
    
    Returns:
    
    a URI (need not be absolute)
  - getParent
```
public abstract VirtualFile getParent()
```
    Gets the parent file. Need only operate within the originally given root.
    
    Returns:
    
    the parent
  - isDirectory
```
public abstract boolean isDirectory()
                             throws IOException
```
    Checks whether this file exists and is a directory.
    
    Returns:
    
    true if it is a directory, false if a file or nonexistent
    
    Throws:
    
    IOException - in case checking status failed
  - isFile
```
public abstract boolean isFile()
                        throws IOException
```
    Checks whether this file exists and is a plain file.
    
    Returns:
    
    true if it is a file, false if a directory or nonexistent
    
    Throws:
    
    IOException - in case checking status failed
  - readLink
```
@CheckForNull
public String readLink()
                              throws IOException
```
    If this file is a symlink, returns the link target.
    The default implementation always returns null. Some implementations may not support symlinks under any conditions.
    
    Returns:
    
    a target (typically a relative path in some format), or null if this is not a link
    
    Throws:
    
    IOException - if reading the link, or even determining whether this file is a link, failed
    
    Since:
    
    2.118
  - exists
```
public abstract boolean exists()
                        throws IOException
```
    Checks whether this file exists. The behavior is undefined for symlinks; if in doubt, check readLink() first.
    
    Returns:
    
    true if it is a plain file or directory, false if nonexistent
    
    Throws:
    
    IOException - in case checking status failed
  - list
```
@NonNull
public abstract VirtualFile[] list()
                                     throws IOException
```
    Lists children of this directory. Only one level deep.
    
    Returns:
    
    a list of children (files and subdirectories); empty for a file or nonexistent directory
    
    Throws:
    
    IOException - if this directory exists but listing was not possible for some other reason
  - list
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
 @NonNull
public VirtualFile[] list(boolean noFollowLinks)
                                                                                                    throws IOException
```
    Lists children of this directory. Only one level deep. This is intended to allow the caller to provide LinkOption.NOFOLLOW_LINKS to ignore symlinks. However, this cannot be enforced. The base implementation here in VirtualFile ignores the openOptions. Some VirtualFile subclasses may not be able to provide an implementation in which NOFOLLOW_LINKS is used or makes sense. Implementations are free to ignore openOptions. Some subclasses of VirtualFile may not have a concept of symlinks.
    
    Parameters:
    
    noFollowLinks - if true then do not follow links.
    
    Returns:
    
    a list of children (files and subdirectories); empty for a file or nonexistent directory
    
    Throws:
    
    IOException - if it could not be opened
  - supportsQuickRecursiveListing
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public boolean supportsQuickRecursiveListing()
```
  - hasSymlink
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public boolean hasSymlink(boolean noFollowLinks)
                                                                                          throws IOException
```
    Determines when a VirtualFile has a recognized symlink. A recognized symlink can be the file itself or any containing directory between it and the optional root directory. If there is no provided root directory then only the file itself is considered. This base implementation ignores the existence of symlinks.
    
    Parameters:
    
    noFollowLinks - if true, then do not follow links.
    
    Returns:
    
    True if the file is a symlink or is referenced within a containing symlink directory before reaching the root directory.
    
    Throws:
    
    IOException - If there is a problem accessing the file.
  - listOnlyDescendants
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
 @NonNull
public List<VirtualFile> listOnlyDescendants()
                                                                                                                       throws IOException
```
    Lists only the children that are descendant of the root directory (not necessarily the current VirtualFile). Only one level deep.
    
    Returns:
    
    a list of descendant children (files and subdirectories); empty for a file or nonexistent directory
    
    Throws:
    
    IOException - if this directory exists but listing was not possible for some other reason
  - list
```
@Deprecated
 @NonNull
public String[] list(String glob)
                                    throws IOException
```
    Deprecated. use list(String, String, boolean) instead
    
    Throws:
    
    IOException
  - list
```
@NonNull
public Collection<String> list(@NonNull
                                        String includes,
                                        @CheckForNull
                                        String excludes,
                                        boolean useDefaultExcludes)
                                 throws IOException
```
    Lists recursive files of this directory with pattern matching.
    The default implementation calls list() recursively inside run(hudson.remoting.Callable<V, java.io.IOException>) and applies filtering to the result. Implementations may wish to override this more efficiently.
    
    Parameters:
    
    includes - comma-separated Ant-style globs as per Util.createFileSet(File, String, String) using / as a path separator; the empty string means no matches (use SelectorUtils.DEEP_TREE_MATCH if you want to match everything except some excludes)
    
    excludes - optional excludes in similar format to includes
    
    useDefaultExcludes - as per AbstractFileSet.setDefaultexcludes(boolean)
    
    Returns:
    
    a list of /-separated relative names of children (files directly inside or in subdirectories)
    
    Throws:
    
    IOException - if this is not a directory, or listing was not possible for some other reason
    
    Since:
    
    2.118
  - list
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
 @NonNull
public Collection<String> list(@NonNull
                                                                                                                String includes,
                                                                                                                @CheckForNull
                                                                                                                String excludes,
                                                                                                                boolean useDefaultExcludes,
                                                                                                                boolean noFollowLinks)
                                                                                                         throws IOException
```
    Lists recursive files of this directory with pattern matching.
    The default implementation calls list() recursively inside run(hudson.remoting.Callable<V, java.io.IOException>) and applies filtering to the result. Implementations may wish to override this more efficiently. This method allows the user to specify that symlinks should not be followed by passing noFollowLinks as true. However, some implementations may not be able to reliably prevent link following. The base implementation here in VirtualFile ignores this parameter.
    
    Parameters:
    
    includes - comma-separated Ant-style globs as per Util.createFileSet(File, String, String) using / as a path separator; the empty string means no matches (use SelectorUtils.DEEP_TREE_MATCH if you want to match everything except some excludes)
    
    excludes - optional excludes in similar format to includes
    
    useDefaultExcludes - as per AbstractFileSet.setDefaultexcludes(boolean)
    
    noFollowLinks - if true then do not follow links.
    
    Returns:
    
    a list of /-separated relative names of children (files directly inside or in subdirectories)
    
    Throws:
    
    IOException - if this is not a directory, or listing was not possible for some other reason
    
    Since:
    
    2.275 and 2.263.2
  - containsSymLinkChild
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public boolean containsSymLinkChild(boolean noFollowLinks)
                                                                                                    throws IOException
```
    Throws:
    
    IOException
  - zip
```
public int zip(OutputStream outputStream,
               String includes,
               String excludes,
               boolean useDefaultExcludes,
               boolean noFollowLinks,
               String prefix)
        throws IOException
```
    Create a ZIP archive from the list of folders/files using the includes and excludes to filter them.
    The default implementation calls other existing methods to list the folders/files, then retrieve them and zip them all.
    
    Parameters:
    
    includes - comma-separated Ant-style globs as per Util.createFileSet(File, String, String) using / as a path separator; the empty string means no matches (use SelectorUtils.DEEP_TREE_MATCH if you want to match everything except some excludes)
    
    excludes - optional excludes in similar format to includes
    
    useDefaultExcludes - as per AbstractFileSet.setDefaultexcludes(boolean)
    
    noFollowLinks - if true then do not follow links.
    
    prefix - the partial path that will be added before each entry inside the archive. If non-empty, a trailing slash will be enforced.
    
    Returns:
    
    the number of files inside the archive (not the folders)
    
    Throws:
    
    IOException - if this is not a directory, or listing was not possible for some other reason
    
    Since:
    
    2.275 and 2.263.2
  - child
```
@NonNull
public abstract VirtualFile child(@NonNull
                                           String name)
```
    Obtains a child file.
    
    Parameters:
    
    name - a relative path, possibly including / (but not ..)
    
    Returns:
    
    a representation of that child, whether it actually exists or not
  - length
```
public abstract long length()
                     throws IOException
```
    Gets the file length.
    
    Returns:
    
    a length, or 0 if inapplicable (e.g. a directory)
    
    Throws:
    
    IOException - if checking the length failed
  - lastModified
```
public abstract long lastModified()
                           throws IOException
```
    Gets the file timestamp.
    
    Returns:
    
    a length, or 0 if inapplicable
    
    Throws:
    
    IOException - if checking the timestamp failed
  - mode
```
public int mode()
         throws IOException
```
    Gets the file’s Unix mode, if meaningful. If the file is symlink (see readLink()), the mode is that of the link target, not the link itself.
    
    Returns:
    
    for example, 0644 ~ rw-r--r--; -1 by default, meaning unknown or inapplicable
    
    Throws:
    
    IOException - if checking the mode failed
    
    Since:
    
    2.118
  - canRead
```
public abstract boolean canRead()
                         throws IOException
```
    Checks whether this file can be read.
    
    Returns:
    
    true normally
    
    Throws:
    
    IOException - if checking status failed
  - open
```
public abstract InputStream open()
                          throws IOException
```
    Opens an input stream on the file so its contents can be read.
    
    Returns:
    
    an open stream
    
    Throws:
    
    IOException - if it could not be opened
  - open
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public InputStream open(boolean noFollowLinks)
                                                                                        throws IOException
```
    Opens an input stream on the file so its contents can be read.
    
    Parameters:
    
    noFollowLinks - if true do not follow links.
    
    Returns:
    
    an open stream
    
    Throws:
    
    IOException - if it could not be opened
  - compareTo
```
public final int compareTo(VirtualFile o)
```
    Does case-insensitive comparison.
    
    Specified by:
    
    compareTo in interface Comparable<VirtualFile>
  - equals
```
public final boolean equals(Object obj)
```
    Compares according to toURI().
    
    Overrides:
    
    equals in class Object
  - hashCode
```
public final int hashCode()
```
    Hashes according to toURI().
    
    Overrides:
    
    hashCode in class Object
  - toString
```
public final String toString()
```
    Displays toURI().
    
    Overrides:
    
    toString in class Object
  - run
```
public <V> V run(hudson.remoting.Callable<V,IOException> callable)
          throws IOException
```
    Does some calculations in batch. For a remote file, this can be much faster than doing the corresponding operations one by one as separate requests. The default implementation just calls the block directly.
    
    Type Parameters:
    
    V - a value type
    
    Parameters:
    
    callable - something to run all at once (only helpful if any mentioned files are on the same system)
    
    Returns:
    
    the callable result
    
    Throws:
    
    IOException - if remote communication failed
    
    Since:
    
    1.554
  - toExternalURL
```
@CheckForNull
public URL toExternalURL()
                                throws IOException
```
    Optionally obtains a URL which may be used to retrieve file contents from any process on any node. For example, given cloud storage this might produce a permalink to the file.
    Only http and https protocols are permitted. It is recommended to use RobustHTTPClient.downloadFile to work with these URLs.
    This is only meaningful for isFile(): no ZIP etc. archiving protocol is defined to allow bulk access to directory trees.
    Any necessary authentication must be encoded somehow into the URL itself; do not include any tokens or other authentication which might allow access to unrelated files (for example ArtifactManager builds from a different job). Authentication should be limited to download, not upload or any other modifications.
    The URL might be valid for only a limited amount of time or even only a single use; this method should be called anew every time an external URL is required.
    
    Returns:
    
    an externally usable URL like https://gist.githubusercontent.com/ACCT/GISTID/raw/COMMITHASH/FILE, or null if there is no such support
    
    Throws:
    
    IOException
    
    Since:
    
    2.118
    
    See Also:
    
    toURI()
  - supportIsDescendant
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public boolean supportIsDescendant()
```
    Determine if the implementation supports the isDescendant(String) method TODO un-restrict it in a weekly after the patch
  - isDescendant
```
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public boolean isDescendant(String childRelativePath)
                                                                                            throws IOException
```
    Check if the relative path is really a descendant of this folder, following the symbolic links. Meant to be used in coordination with child(String). TODO un-restrict it in a weekly after the patch
    
    Throws:
    
    IOException
  - forFile
```
public static VirtualFile forFile(File f)
```
    Creates a virtual file wrapper for a local file.
    
    Parameters:
    
    f - a disk file (need not exist)
    
    Returns:
    
    a wrapper
  - forFilePath
```
public static VirtualFile forFilePath(FilePath f)
```
    Creates a virtual file wrapper for a remotable file.
    
    Parameters:
    
    f - a local or remote file (need not exist)
    
    Returns:
    
    a wrapper

Class VirtualFile

How are VirtualFile and FilePath different?

Opening files from other machines

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

VirtualFile

Method Detail

getName

toURI

getParent

isDirectory

isFile

readLink

exists

list

list

supportsQuickRecursiveListing

hasSymlink

listOnlyDescendants

list

list

list

containsSymLinkChild

zip

child

length

lastModified

mode

canRead

open

open

compareTo

equals

hashCode

toString

run

toExternalURL

supportIsDescendant

isDescendant

forFile

forFilePath