mirror of
https://github.com/JetBrains/intellij-sdk-code-samples.git
synced 2025-07-28 09:17:50 +08:00
92 lines
7.5 KiB
Markdown
92 lines
7.5 KiB
Markdown
[//]: # (title: Virtual Files)
|
|
|
|
<!-- Copyright 2000-2022 JetBrains s.r.o. and contributors. Use of this source code is governed by the Apache 2.0 license. -->
|
|
|
|
A [`VirtualFile`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFile.java) (VF) is the IntelliJ Platform's representation of a file in a [Virtual File System (VFS)](virtual_file_system.md).
|
|
|
|
Most commonly, a virtual file is a file in a local file system.
|
|
However, the IntelliJ Platform supports multiple pluggable file system implementations, so virtual files can also represent classes in a JAR file, old revisions of files loaded from a version control repository, and so on.
|
|
|
|
The VFS level deals only with binary content.
|
|
Contents of a `VirtualFile` are treated as a stream of bytes, but concepts like encodings and line separators are handled on higher system levels.
|
|
|
|
## How do I get a virtual file?
|
|
|
|
| Context | API |
|
|
|----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| [Action](basic_action_system.md) | [`AnActionEvent.getData(PlatformDataKeys.VIRTUAL_FILE)`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java)<br/>[`AnActionEvent.getData(PlatformDataKeys.VIRTUAL_FILE_ARRAY)`](upsource:///platform/editor-ui-api/src/com/intellij/openapi/actionSystem/AnActionEvent.java) for multiple selection |
|
|
| [Document](documents.md) | [`FileDocumentManager.getInstance().getFile()`](upsource:///platform/core-api/src/com/intellij/openapi/fileEditor/FileDocumentManager.java) |
|
|
| [PSI File](psi_files.md) | [`PsiFile.getVirtualFile()`](upsource:///platform/core-api/src/com/intellij/psi/PsiFile.java) (may return `null` if the PSI file exists only in memory) |
|
|
| Local File System Path | [`LocalFileSystem.getInstance().findFileByIoFile()`](upsource:///platform/analysis-api/src/com/intellij/openapi/vfs/LocalFileSystem.java)<br/>[`VirtualFileManager.findFileByNioPath()`/`refreshAndFindFileByNioPath()`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java) (2020.2+) |
|
|
|
|
## What can I do with it?
|
|
|
|
Typical file operations are available, such as traverse the file system, get file contents, rename, move, or delete.
|
|
Recursive iteration should be performed using `VfsUtilCore.iterateChildrenRecursively()` to prevent endless loops caused by recursive symlinks.
|
|
|
|
## Where does it come from?
|
|
|
|
The VFS is built incrementally by scanning the file system up and down, starting from the project root.
|
|
VFS _refresh_ operations detect new files appearing in the file system.
|
|
A refresh operation can be initiated programmatically using `VirtualFileManager.syncRefresh()`/`asyncRefresh()` or `VirtualFile.refresh()`.
|
|
VFS refreshes are also triggered whenever file system watchers receive file system change notifications.
|
|
|
|
Invoking a VFS refresh might be necessary for accessing a file that has just been created by an external tool through the IntelliJ Platform APIs.
|
|
|
|
## How long does a virtual file persist?
|
|
|
|
A particular file on disk is represented by equal `VirtualFile` instances for the IDE process's entire lifetime.
|
|
There may be several instances corresponding to the same file, and they can be garbage-collected.
|
|
The file is a `UserDataHolder`, and the user data is shared between those equal instances.
|
|
If a file is deleted, its corresponding VirtualFile instance becomes invalid (`isValid()` returns `false`), and operations cause exceptions.
|
|
|
|
## How do I create a virtual file?
|
|
|
|
Usually, you don't.
|
|
As a general rule, files are created either through the PSI API or through the regular `java.io.File` API.
|
|
|
|
If one needs to create a file through VFS, use `VirtualFile.createChildData()` to create a `VirtualFile` instance and `VirtualFile.setBinaryContent()` to write some data to the file.
|
|
|
|
## How do I get notified when VFS changes?
|
|
|
|
> See [Virtual file system events](virtual_file_system.md#virtual-file-system-events) for important details.
|
|
>
|
|
{type="note"}
|
|
|
|
Implement [`BulkFileListener`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/newvfs/BulkFileListener.java) and subscribe to the [message bus](messaging_infrastructure.md) topic `VirtualFileManager.VFS_CHANGES`.
|
|
For example:
|
|
|
|
```java
|
|
project.getMessageBus().connect().subscribe(VirtualFileManager.VFS_CHANGES,
|
|
new BulkFileListener() {
|
|
@Override
|
|
public void after(@NotNull List<? extends VFileEvent> events) {
|
|
// handle the events
|
|
}
|
|
});
|
|
```
|
|
|
|
See [Message Infrastructure](messaging_infrastructure.md) and [Plugin Listeners](plugin_listeners.md) for more details.
|
|
|
|
For a non-blocking alternative, starting with version 2019.2 of the platform, see [`AsyncFileListener`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/AsyncFileListener.java).
|
|
|
|
Plugins targeting versions 2017.2 or older of the platform can use the now deprecated `VirtualFileManager.addVirtualFileListener()` method, which allows you to receive notifications about all changes in the VFS.
|
|
|
|
## Are there any utilities for analyzing and manipulating virtual files?
|
|
|
|
[`VfsUtil`](upsource:///platform/analysis-api/src/com/intellij/openapi/vfs/VfsUtil.java) and [`VfsUtilCore`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VfsUtilCore.java) provide utility methods for analyzing files in the Virtual File System.
|
|
|
|
For storing a large set of Virtual Files, use dedicated `VfsUtilCore.createCompactVirtualFileSet()`.
|
|
|
|
Use [`ProjectLocator`](upsource:///platform/projectModel-api/src/com/intellij/openapi/project/ProjectLocator.java) to find the projects that contain a given virtual file.
|
|
|
|
## How do I extend VFS?
|
|
|
|
To provide an alternative file system implementation (for example, an FTP file system), implement the [`VirtualFileSystem`](upsource:///platform/core-api/src/com/intellij/openapi/vfs/VirtualFileSystem.java) class (most likely you'll also need to implement `VirtualFile`), and register your implementation via `com.intellij.virtualFileSystem` extension point (2019.2 and later) or [application component](plugin_components.md) for earlier versions.
|
|
|
|
To hook into operations performed in the local file system (for example, when developing a version control system integration that needs custom rename/move handling), implement [`LocalFileOperationsHandler`](upsource:///platform/analysis-api/src/com/intellij/openapi/vfs/LocalFileOperationsHandler.java) and register it via `LocalFileSystem.registerAuxiliaryFileOperationsHandler()`.
|
|
|
|
## What are the rules for working with VFS?
|
|
|
|
See [Virtual File System](virtual_file_system.md) for a detailed description of the VFS architecture and usage guidelines.
|