Child pages
  • IntelliJ IDEA Architectural Overview
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

This document is a work in progress. Feel free to leave comments if you feel that some information should be added or clarified.

The goal of this document is to describe the architecture of IntelliJ IDEA 6.0 from a plugin developer's point of view. It will be organized in a task-based manner: rather than listing all the things that you can do with each object and describing how they are all implemented, it will try to answer questions "what can I do with this object", "how do I get to this object" and so on.

This document assumes that the reader is familiar with the basic concepts of IntelliJ IDEA plugin development. If you don't know anything at all about plugin development, you should start with the live demo and tutorials at, and then return to this document.

Virtual Files

A virtual file (com.intellij.openapi.vfs.VirtualFile) is IntelliJ IDEA's representation of a file in a filesystem (VFS). The most common case of a virtual file is a file on your local filesystem. However, IDEA supports multiple pluggable filesystem implementations, so virtual files can also represent classes in a JAR file, old revisions of files loaded from the CVS repository and so on.

The VFS level deals only with binary content. You can get or set the contents of a VirtualFile as a stream of bytes, but concepts like encodings and line separators are handled by higher levels of the system.

How do I get one?

  • From an action: (VirtualFile) dataContext.getData(DataConstants.VIRTUAL_FILE). If you are interested in multiple selection, you can also query for (VirtualFile[]) dataContext.getData(DataConstants.VIRTUAL_FILE_ARRAY).
  • From a path in the local file system: LocalFileSystem.findFileByIoFile()
  • From a PSI file: psiFile.getVirtualFile() (may return null if the PSI file exists only in memory)
  • From a document: {{

Where does it come from?

The VFS is built incrementally, by walking the filesystem up and down starting from the project root. New files appearing in the file system are detected by VFS refreshes. A refresh can be initiated programmatically (VirtualFileManager.refresh() or VirtualFile.refresh()). VFS refreshes are also caused by file system change notifications received by file system watchers (on Windows and Mac).

As a plugin developer, you may need to invoke a VFS refresh if you need to access through IDEA's APIs a file which has just been created by an external tool.

How long does it live?

A particular file on disk is represented by the same VirtualFile instance for the entire lifetime of the IDEA process. If a file is deleted, its corresponding VirtualFile instance becomes invalid (isValid() returns false and operations cause exceptions).

How do I create one?

Usually you don't: files are created either through the PSI API or through the regular API. If you do need to create a file through VFS, you can use VirtualFile.createChildData() to create a VirtualFile instance and VirtualFile.setBinaryContent() to write some data to it.

How do I get notified when it changes?

VirtualFileManager.addVirtualFileListener() allows you to receive notifications about all changes happening in the VFS.

What are the threading rules?

to be continued

  • No labels