public abstract class VirtualFile extends Object implements Comparable<VirtualFile>, Serializable
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()
FilePath abstracts away File
s on machines that are connected over Channel
, whereas
VirtualFile
makes no assumption about where the actual files are, or whether there really exists
File
s somewhere. This makes VirtualFile more abstract.
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()
.
DirectoryBrowserSupport
,
FilePath
,
Serialized FormConstructor and Description |
---|
VirtualFile() |
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.
|
@NonNull public abstract String getName()
@NonNull public abstract URI toURI()
When toExternalURL()
is implemented, that same value could be used here,
unless some sort of authentication is also embedded.
public abstract VirtualFile getParent()
public abstract boolean isDirectory() throws IOException
IOException
- in case checking status failedpublic abstract boolean isFile() throws IOException
IOException
- in case checking status failed@CheckForNull public String readLink() throws IOException
The default implementation always returns null. Some implementations may not support symlinks under any conditions.
IOException
- if reading the link, or even determining whether this file is a link, failedpublic abstract boolean exists() throws IOException
readLink()
first.IOException
- in case checking status failed@NonNull public abstract VirtualFile[] list() throws IOException
IOException
- if this directory exists but listing was not possible for some other reason@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) @NonNull public VirtualFile[] list(boolean noFollowLinks) throws IOException
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.noFollowLinks
- if true then do not follow links.IOException
- if it could not be opened@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean supportsQuickRecursiveListing()
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean hasSymlink(boolean noFollowLinks) throws IOException
noFollowLinks
- if true, then do not follow links.IOException
- If there is a problem accessing the file.@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) @NonNull public List<VirtualFile> listOnlyDescendants() throws IOException
IOException
- if this directory exists but listing was not possible for some other reason@Deprecated @NonNull public String[] list(String glob) throws IOException
list(String, String, boolean)
insteadIOException
@NonNull public Collection<String> list(@NonNull String includes, @CheckForNull String excludes, boolean useDefaultExcludes) throws IOException
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.
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)
/
-separated relative names of children (files directly inside or in subdirectories)IOException
- if this is not a directory, or listing was not possible for some other reason@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
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.
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./
-separated relative names of children (files directly inside or in subdirectories)IOException
- if this is not a directory, or listing was not possible for some other reason@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean containsSymLinkChild(boolean noFollowLinks) throws IOException
IOException
public int zip(OutputStream outputStream, String includes, String excludes, boolean useDefaultExcludes, boolean noFollowLinks, String prefix) throws IOException
The default implementation calls other existing methods to list the folders/files, then retrieve them and zip them all.
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.IOException
- if this is not a directory, or listing was not possible for some other reason@NonNull public abstract VirtualFile child(@NonNull String name)
name
- a relative path, possibly including /
(but not ..
)public abstract long length() throws IOException
IOException
- if checking the length failedpublic abstract long lastModified() throws IOException
IOException
- if checking the timestamp failedpublic int mode() throws IOException
readLink()
), the mode is that of the link target, not the link itself.rw-r--r--
; -1 by default, meaning unknown or inapplicableIOException
- if checking the mode failedpublic abstract boolean canRead() throws IOException
IOException
- if checking status failedpublic abstract InputStream open() throws IOException
IOException
- if it could not be opened@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public InputStream open(boolean noFollowLinks) throws IOException
noFollowLinks
- if true do not follow links.IOException
- if it could not be openedpublic final int compareTo(VirtualFile o)
compareTo
in interface Comparable<VirtualFile>
public final int hashCode()
toURI()
.
public <V> V run(hudson.remoting.Callable<V,IOException> callable) throws IOException
V
- a value typecallable
- something to run all at once (only helpful if any mentioned files are on the same system)IOException
- if remote communication failed@CheckForNull public URL toExternalURL() throws IOException
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.
https://gist.githubusercontent.com/ACCT/GISTID/raw/COMMITHASH/FILE
, or null if there is no such supportIOException
toURI()
@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean supportIsDescendant()
isDescendant(String)
method
TODO un-restrict it in a weekly after the patch@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class) public boolean isDescendant(String childRelativePath) throws IOException
child(String)
.
TODO un-restrict it in a weekly after the patchIOException
public static VirtualFile forFile(File f)
f
- a disk file (need not exist)public static VirtualFile forFilePath(FilePath f)
f
- a local or remote file (need not exist)Copyright © 2004–2021. All rights reserved.