Package com.intellij.openapi.vfs

Class VirtualFile

java.lang.Object

com.intellij.openapi.util.UserDataHolderBase

com.intellij.openapi.vfs.VirtualFile

All Implemented Interfaces:

ModificationTracker, UserDataHolder, UserDataHolderEx

Direct Known Subclasses:

AbstractVcsVirtualFile, CoreJarVirtualFile, CoreLocalVirtualFile, HttpVirtualFile, LightVirtualFileBase, NewVirtualFile, ResourceBundleAsVirtualFile, StubVirtualFile

public abstract class VirtualFile
extends UserDataHolderBase
implements ModificationTracker

Represents a file in VirtualFileSystem. A particular file is represented by equal VirtualFile instances for the entire lifetime of the IDE process, unless the file is deleted, in which case isValid() will return false.

VirtualFile instances are created on request, so there can be several instances corresponding to the same file. All of them are equal, have the same hashCode and use shared storage for all related data, including user data (see UserDataHolder).

If an in-memory implementation of VirtualFile is required, LightVirtualFile can be used.

Please see Virtual File System for a high-level overview.

See Also:

VirtualFileSystem, VirtualFileManager, VfsUtil

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	VirtualFile.PropName Acceptable values for "propertyName" argument of VFilePropertyChangeEvent().

Field Summary

Fields

Modifier and Type	Field and Description
static VirtualFile[]	EMPTY_ARRAY
static java.lang.String	PROP_ENCODING Used as a property name in the VirtualFilePropertyEvent fired when the encoding of a VirtualFile changes.
static java.lang.String	PROP_HIDDEN Used as a property name in the VirtualFilePropertyEvent fired when a visibility of a VirtualFile changes.
static java.lang.String	PROP_NAME Used as a property name in the VirtualFilePropertyEvent fired when the name of a VirtualFile changes.
static java.lang.String	PROP_SYMLINK_TARGET Used as a property name in the VirtualFilePropertyEvent fired when a symlink target of a VirtualFile changes.
static java.lang.String	PROP_WRITABLE Used as a property name in the VirtualFilePropertyEvent fired when write permission of a VirtualFile changes.

Fields inherited from interface com.intellij.openapi.util.ModificationTracker

EVER_CHANGED, NEVER_CHANGED

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	VirtualFile()

Method Summary

Modifier and Type	Method and Description
abstract byte []	contentsToByteArray() Returns file content as an array of bytes.
byte []	contentsToByteArray(boolean cacheContent) Returns file content as an array of bytes.
VirtualFile	copy(java.lang.Object requestor, VirtualFile newParent, java.lang.String copyName)
VirtualFile	createChildData(java.lang.Object requestor, java.lang.String name) Creates a new file in this directory.
VirtualFile	createChildDirectory(java.lang.Object requestor, java.lang.String name) Creates a subdirectory in this directory.
void	delete(java.lang.Object requestor) Deletes this file.
boolean	exists()
VirtualFile	findChild(java.lang.String name) Finds child of this file with the given name.
VirtualFile	findFileByRelativePath(java.lang.String relPath) Finds file by path relative to this file.
VirtualFile	findOrCreateChildData(java.lang.Object requestor, java.lang.String name)
byte []	getBOM()
VirtualFile	getCanonicalFile() Resolves all symbolic links containing in a path to this file and returns a link target.
java.lang.String	getCanonicalPath() Resolves all symbolic links containing in a path to this file and returns a path to a link target (in platform-independent format).
java.nio.charset.Charset	getCharset()
abstract VirtualFile[]	getChildren() Gets the child files.
java.lang.String	getDetectedLineSeparator()
java.lang.String	getExtension() Gets the extension of this file.
abstract VirtualFileSystem	getFileSystem() Gets the VirtualFileSystem this file belongs to.
FileType	getFileType() Returns the FileType of this file, or FileTypes.UNKNOWN if a type cannot be determined (i.e.
abstract java.io.InputStream	getInputStream() Gets the InputStream for this file.
abstract long	getLength() File length in bytes.
long	getModificationCount()
long	getModificationStamp() Gets modification stamp value.
abstract java.lang.String	getName() Gets the name of this file.
java.lang.CharSequence	getNameSequence()
java.lang.String	getNameWithoutExtension() Gets the file name without the extension.
java.io.OutputStream	getOutputStream(java.lang.Object requestor) Creates the OutputStream for this file.
abstract java.io.OutputStream	getOutputStream(java.lang.Object requestor, long newModificationStamp, long newTimeStamp) Gets the OutputStream for this file and sets modification stamp and time stamp to the specified values after closing the stream.
abstract VirtualFile	getParent() Gets the parent VirtualFile.
abstract java.lang.String	getPath() Gets the path of this file.
java.lang.String	getPresentableName()
java.lang.String	getPresentableUrl() Fetches "presentable URL" of this file.
abstract long	getTimeStamp() Gets the timestamp for this file.
java.lang.String	getUrl() Returns the URL of this file.
boolean	is(VFileProperty property) Checks whether this file has a specific property.
boolean	isCharsetSet()
abstract boolean	isDirectory() Checks whether this file is a directory.
boolean	isInLocalFileSystem()
boolean	isRecursiveOrCircularSymLink() Returns true if this file is a symlink that is either recursive (i.e.
abstract boolean	isValid() Checks whether this VirtualFile is valid.
static boolean	isValidName(java.lang.String name) Deprecated. use VirtualFileSystem.isValidName(String)
abstract boolean	isWritable() Checks whether this file could be modified.
void	move(java.lang.Object requestor, VirtualFile newParent) Moves this file to another directory.
protected boolean	nameEquals(java.lang.String name)
void	refresh(boolean asynchronous, boolean recursive) Refreshes the cached file information from the physical file system.
abstract void	refresh(boolean asynchronous, boolean recursive, java.lang.Runnable postRunnable) The same as refresh(boolean, boolean) but also runs postRunnable after the operation is completed.
void	rename(java.lang.Object requestor, java.lang.String newName) Renames this file to the newName.
void	setBinaryContent(byte [] content)
void	setBinaryContent(byte [] content, long newModificationStamp, long newTimeStamp)
void	setBinaryContent(byte [] content, long newModificationStamp, long newTimeStamp, java.lang.Object requestor)
void	setBOM(byte [] BOM)
void	setCharset(java.nio.charset.Charset charset)
void	setCharset(java.nio.charset.Charset charset, java.lang.Runnable whenChanged)
void	setCharset(java.nio.charset.Charset charset, java.lang.Runnable whenChanged, boolean fireEventsWhenChanged)
void	setDetectedLineSeparator(java.lang.String separator)
void	setPreloadedContentHint(byte[] preloadedContentHint)
void	setWritable(boolean writable)
protected void	storeCharset(java.nio.charset.Charset charset)
java.lang.String	toString()

Methods inherited from class com.intellij.openapi.util.UserDataHolderBase

changeUserMap, clearUserData, clone, copyCopyableDataTo, copyUserDataTo, getCopyableUserData, getUserData, getUserDataString, getUserMap, isUserDataEmpty, putCopyableUserData, putUserData, putUserDataIfAbsent, replace, setUserMap

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

EMPTY_ARRAY

public static final VirtualFile[] EMPTY_ARRAY

PROP_NAME

public static final java.lang.String PROP_NAME

Used as a property name in the VirtualFilePropertyEvent fired when the name of a VirtualFile changes.

See Also:

VirtualFileListener.propertyChanged(com.intellij.openapi.vfs.VirtualFilePropertyEvent), VirtualFilePropertyEvent.getPropertyName(), Constant Field Values

PROP_ENCODING

public static final java.lang.String PROP_ENCODING

Used as a property name in the VirtualFilePropertyEvent fired when the encoding of a VirtualFile changes.

See Also:

VirtualFileListener.propertyChanged(com.intellij.openapi.vfs.VirtualFilePropertyEvent), VirtualFilePropertyEvent.getPropertyName(), Constant Field Values

PROP_WRITABLE

public static final java.lang.String PROP_WRITABLE

Used as a property name in the VirtualFilePropertyEvent fired when write permission of a VirtualFile changes.

See Also:

VirtualFileListener.propertyChanged(com.intellij.openapi.vfs.VirtualFilePropertyEvent), VirtualFilePropertyEvent.getPropertyName(), Constant Field Values

PROP_HIDDEN

public static final java.lang.String PROP_HIDDEN

Used as a property name in the VirtualFilePropertyEvent fired when a visibility of a VirtualFile changes.

See Also:

VirtualFileListener.propertyChanged(com.intellij.openapi.vfs.VirtualFilePropertyEvent), VirtualFilePropertyEvent.getPropertyName(), Constant Field Values

PROP_SYMLINK_TARGET

public static final java.lang.String PROP_SYMLINK_TARGET

Used as a property name in the VirtualFilePropertyEvent fired when a symlink target of a VirtualFile changes.

See Also:

VirtualFileListener.propertyChanged(com.intellij.openapi.vfs.VirtualFilePropertyEvent), VirtualFilePropertyEvent.getPropertyName(), Constant Field Values

Constructor Detail

VirtualFile

protected VirtualFile()

Method Detail

getName

public abstract java.lang.String getName()

Gets the name of this file.

See Also:

getNameSequence()

getNameSequence

public java.lang.CharSequence getNameSequence()

getFileSystem

public abstract VirtualFileSystem getFileSystem()

Gets the VirtualFileSystem this file belongs to.

Returns:

the VirtualFileSystem

getPath

public abstract java.lang.String getPath()

Gets the path of this file. Path is a string that uniquely identifies a file within a given VirtualFileSystem. Format of the path depends on the concrete file system. For LocalFileSystem it is an absolute file path with file separator characters (File.separatorChar) replaced to the forward slash ('/').

Returns:

the path

getUrl

public java.lang.String getUrl()

Returns the URL of this file. The URL is a string that uniquely identifies a file in all file systems. It has the following format: <protocol>://<path>.

File can be found by its URL using VirtualFileManager.findFileByUrl(java.lang.String) method.

Please note these URLs are intended for use withing VFS - meaning they are not necessarily RFC-compliant.

Returns:

the URL consisting of protocol and path

See Also:

VirtualFileManager.findFileByUrl(java.lang.String), getPath(), VirtualFileSystem.getProtocol()

getPresentableUrl

public final java.lang.String getPresentableUrl()

Fetches "presentable URL" of this file. "Presentable URL" is a string to be used for displaying this file in the UI.

Returns:

the presentable URL.

See Also:

VirtualFileSystem.extractPresentableUrl(java.lang.String)

getExtension

public java.lang.String getExtension()

Gets the extension of this file. If file name contains '.' extension is the substring from the last '.' to the end of the name (not including the '.'), otherwise extension is null.

Returns:

the extension or null if file name doesn't contain '.'

getNameWithoutExtension

public java.lang.String getNameWithoutExtension()

Gets the file name without the extension. If file name contains '.', the substring till the last '.' is returned. Otherwise, the value of getName() is returned.

Returns:

the name without extension

rename

public void rename(java.lang.Object requestor,
                   java.lang.String newName)
            throws java.io.IOException

Renames this file to the newName.

This method should only be called within write action.

Parameters:

requestor - any object to control who called this method. Note that it is considered to be an external change if requestor is null. See VirtualFileEvent.getRequestor()

newName - the new file name

Throws:

java.io.IOException - if file failed to be renamed

isWritable

public abstract boolean isWritable()

Checks whether this file could be modified. Note that this value may be cached and may differ from write permission of the physical file.

Returns:

true if this file is writable, false otherwise

setWritable

public void setWritable(boolean writable)
                 throws java.io.IOException

Throws:

java.io.IOException

isDirectory

public abstract boolean isDirectory()

Checks whether this file is a directory.

Returns:

true if this file is a directory, false otherwise

is

public boolean is(VFileProperty property)

Checks whether this file has a specific property.

Returns:

true if the file has a specific property, false otherwise

getCanonicalPath

public java.lang.String getCanonicalPath()

Resolves all symbolic links containing in a path to this file and returns a path to a link target (in platform-independent format).

Note: please use this method judiciously. In most cases VFS clients don't need to resolve links in paths and should work with those provided by a user.

Returns:

getPath() if there are no symbolic links in a file's path; getCanonicalFile().getPath() if the link was successfully resolved; null otherwise

getCanonicalFile

public VirtualFile getCanonicalFile()

Resolves all symbolic links containing in a path to this file and returns a link target.

Note: please use this method judiciously. In most cases VFS clients don't need to resolve links in paths and should work with those provided by a user.

Returns:

this if there are no symbolic links in a file's path; instance of VirtualFile if the link was successfully resolved; null otherwise

isValid

public abstract boolean isValid()

Checks whether this VirtualFile is valid. File can be invalidated either by deleting it or one of its parents with delete(java.lang.Object) method or by an external change. If file is not valid only Object.equals(java.lang.Object), Object.hashCode(), getName(), getPath(), getUrl(), getPresentableUrl() and methods from UserDataHolder can be called for it. Using any other methods for an invalid VirtualFile instance produce unpredictable results.

Returns:

true if this is a valid file, false otherwise

getParent

public abstract VirtualFile getParent()

Gets the parent VirtualFile.

Returns:

the parent file or null if this file is a root directory

getChildren

public abstract VirtualFile[] getChildren()

Gets the child files.

Returns:

array of the child files or null if this file is not a directory

findChild

public VirtualFile findChild(java.lang.String name)

Finds child of this file with the given name.

Parameters:

name - the file name to search by

Returns:

the file if found any, null otherwise

findOrCreateChildData

public VirtualFile findOrCreateChildData(java.lang.Object requestor,
                                         java.lang.String name)
                                  throws java.io.IOException

Throws:

java.io.IOException

getFileType

public FileType getFileType()

Returns the FileType of this file, or FileTypes.UNKNOWN if a type cannot be determined (i.e. file type is not registered via FileTypeRegistry).

Performance notice: consider using FileTypeRegistry.isFileOfType(com.intellij.openapi.vfs.VirtualFile, com.intellij.openapi.fileTypes.FileType) or FileTypeRegistry.getFileTypeByFileName(java.lang.CharSequence) if this method is to be called for massive file collections, e.g. in BulkFileListener. See FileTypeRegistry javadoc for the details.

See Also:

FileTypeRegistry

findFileByRelativePath

public VirtualFile findFileByRelativePath(java.lang.String relPath)

Finds file by path relative to this file.

Parameters:

relPath - the relative path with / used as separators

Returns:

the file if found any, null otherwise

createChildDirectory

public VirtualFile createChildDirectory(java.lang.Object requestor,
                                        java.lang.String name)
                                 throws java.io.IOException

Creates a subdirectory in this directory. This method should be only called within write-action. See Application.runWriteAction(java.lang.Runnable).

Parameters:

requestor - any object to control who called this method. Note that it is considered to be an external change if requestor is null. See VirtualFileEvent.getRequestor()

name - directory name

Returns:

VirtualFile representing the created directory

Throws:

java.io.IOException - if directory failed to be created

createChildData

public VirtualFile createChildData(java.lang.Object requestor,
                                   java.lang.String name)
                            throws java.io.IOException

Creates a new file in this directory. This method should be only called within write-action. See Application.runWriteAction(java.lang.Runnable).

Parameters:

requestor - any object to control who called this method. Note that it is considered to be an external change if requestor is null. See VirtualFileEvent.getRequestor()

Returns:

VirtualFile representing the created file

Throws:

java.io.IOException - if file failed to be created

delete

public void delete(java.lang.Object requestor)
            throws java.io.IOException

Deletes this file. This method should be only called within write-action. See Application.runWriteAction(java.lang.Runnable).

Parameters:

requestor - any object to control who called this method. Note that it is considered to be an external change if requestor is null. See VirtualFileEvent.getRequestor()

Throws:

java.io.IOException - if file failed to be deleted

move

public void move(java.lang.Object requestor,
                 VirtualFile newParent)
          throws java.io.IOException

Moves this file to another directory. This method should be only called within write-action. See Application.runWriteAction(java.lang.Runnable).

Parameters:

requestor - any object to control who called this method. Note that it is considered to be an external change if requestor is null. See VirtualFileEvent.getRequestor()

newParent - the directory to move this file to

Throws:

java.io.IOException - if file failed to be moved

copy

public VirtualFile copy(java.lang.Object requestor,
                        VirtualFile newParent,
                        java.lang.String copyName)
                 throws java.io.IOException

Throws:

java.io.IOException

getCharset

public java.nio.charset.Charset getCharset()

Returns:

Retrieve the charset file has been loaded with (if loaded) and would be saved with (if would).

storeCharset

protected void storeCharset(java.nio.charset.Charset charset)

setCharset

public void setCharset(java.nio.charset.Charset charset)

setCharset

public void setCharset(java.nio.charset.Charset charset,
                       java.lang.Runnable whenChanged)

setCharset

public void setCharset(java.nio.charset.Charset charset,
                       java.lang.Runnable whenChanged,
                       boolean fireEventsWhenChanged)

isCharsetSet

public boolean isCharsetSet()

setBinaryContent

public final void setBinaryContent(byte [] content)
                            throws java.io.IOException

Throws:

java.io.IOException

setBinaryContent

public void setBinaryContent(byte [] content,
                             long newModificationStamp,
                             long newTimeStamp)
                      throws java.io.IOException

Throws:

java.io.IOException

setBinaryContent

public void setBinaryContent(byte [] content,
                             long newModificationStamp,
                             long newTimeStamp,
                             java.lang.Object requestor)
                      throws java.io.IOException

Throws:

java.io.IOException

getOutputStream

public final java.io.OutputStream getOutputStream(java.lang.Object requestor)
                                           throws java.io.IOException

Creates the OutputStream for this file. Writes BOM first, if there is any. See Unicode Byte Order Mark FAQ for an explanation.

Parameters:

requestor - any object to control who called this method. Note that it is considered to be an external change if requestor is null. See VirtualFileEvent.getRequestor() and SafeWriteRequestor.

Returns:

OutputStream

Throws:

java.io.IOException - if an I/O error occurs

getOutputStream

public abstract java.io.OutputStream getOutputStream(java.lang.Object requestor,
                                                     long newModificationStamp,
                                                     long newTimeStamp)
                                              throws java.io.IOException

Gets the OutputStream for this file and sets modification stamp and time stamp to the specified values after closing the stream.

Normally, you should not use this method.

Writes BOM first, if there is any. See Unicode Byte Order Mark FAQ for an explanation.

Parameters:

requestor - any object to control who called this method. Note that it is considered to be an external change if requestor is null. See VirtualFileEvent.getRequestor() and SafeWriteRequestor.

newModificationStamp - new modification stamp or -1 if no special value should be set

newTimeStamp - new time stamp or -1 if no special value should be set

Returns:

OutputStream

Throws:

java.io.IOException - if an I/O error occurs

See Also:

getModificationStamp()

contentsToByteArray

public abstract byte [] contentsToByteArray()
                                     throws java.io.IOException

Returns file content as an array of bytes. Has the same effect as contentsToByteArray(true).

Returns:

file content

Throws:

java.io.IOException - if an I/O error occurs

See Also:

contentsToByteArray(boolean), getInputStream()

contentsToByteArray

public byte [] contentsToByteArray(boolean cacheContent)
                            throws java.io.IOException

Returns file content as an array of bytes.

Parameters:

cacheContent - set true to

Returns:

file content

Throws:

java.io.IOException - if an I/O error occurs

See Also:

contentsToByteArray()

getModificationStamp

public long getModificationStamp()

Gets modification stamp value. Modification stamp is a value changed by any modification of the content of the file. Note that it is not related to the file modification time.

Returns:

modification stamp

See Also:

getTimeStamp()

getTimeStamp

public abstract long getTimeStamp()

Gets the timestamp for this file. Note that this value may be cached and may differ from the timestamp of the physical file.

Returns:

timestamp

See Also:

File.lastModified()

getLength

public abstract long getLength()

File length in bytes.

Returns:

the length of this file.

refresh

public void refresh(boolean asynchronous,
                    boolean recursive)

Refreshes the cached file information from the physical file system. If this file is not a directory the timestamp value is refreshed and contentsChanged event is fired if it is changed.

If this file is a directory the set of its children is refreshed. If recursive value is true all children are refreshed recursively.

When invoking synchronous refresh from a thread other than the event dispatch thread, the current thread must NOT be in a read action, otherwise a deadlock may occur.

Parameters:

asynchronous - if true, the method will return immediately and the refresh will be processed in the background. If false, the method will return only after the refresh is done and the VFS change events caused by the refresh have been fired and processed in the event dispatch thread. Instead of synchronous refreshes, it's recommended to use asynchronous refreshes with a postRunnable whenever possible.

recursive - whether to refresh all the files in this directory recursively

refresh

public abstract void refresh(boolean asynchronous,
                             boolean recursive,
                             java.lang.Runnable postRunnable)

The same as refresh(boolean, boolean) but also runs postRunnable after the operation is completed. The runnable is executed on event dispatch thread inside write action.

getPresentableName

public java.lang.String getPresentableName()

getModificationCount

public long getModificationCount()

Specified by:

getModificationCount in interface ModificationTracker

nameEquals

protected boolean nameEquals(java.lang.String name)

Returns:

whether file name equals to this name result depends on the filesystem specifics

getInputStream

public abstract java.io.InputStream getInputStream()
                                            throws java.io.IOException

Gets the InputStream for this file. Skips BOM if there is any. See Unicode Byte Order Mark FAQ for an explanation.

Returns:

InputStream

Throws:

java.io.IOException - if an I/O error occurs

See Also:

contentsToByteArray()

getBOM

public byte [] getBOM()

setBOM

public void setBOM(byte [] BOM)

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

exists

public boolean exists()

isInLocalFileSystem

public boolean isInLocalFileSystem()

isValidName

@Deprecated
public static boolean isValidName(java.lang.String name)

Deprecated. use VirtualFileSystem.isValidName(String)

getDetectedLineSeparator

public java.lang.String getDetectedLineSeparator()

Returns:

Line separator for this file. It is always null for directories and binaries, and possibly null if a separator isn't yet known.

See Also:

LineSeparator

setDetectedLineSeparator

public void setDetectedLineSeparator(java.lang.String separator)

setPreloadedContentHint

public void setPreloadedContentHint(byte[] preloadedContentHint)

isRecursiveOrCircularSymLink

public boolean isRecursiveOrCircularSymLink()

Returns true if this file is a symlink that is either recursive (i.e. points to this file' parent) or circular (i.e. its path has a form of "/.../linkX/.../linkX").