Represents a file in {@link VirtualFileSystem}. A particular file is represented by equal * {@code VirtualFile} instances for the entire lifetime of the IDE process, unless the file - * is deleted, in which case {@link #isValid()} will return {@code 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 {@code hashCode} and use shared storage for all related data, including user data (see {@link UserDataHolder}). - * - * If an in-memory implementation of VirtualFile is required, {@link LightVirtualFile} - * can be used. - * - * Please see Virtual File System - * for high-level overview. + * is deleted, in which case {@link #isValid()} will return {@code 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 {@code hashCode} and use shared storage for all related data, including user data + * (see {@link UserDataHolder}).
+ * + *If an in-memory implementation of VirtualFile is required, {@link LightVirtualFile} can be used.
+ * + *Please see Virtual File System + * for a high-level overview.
* * @see VirtualFileSystem * @see VirtualFileManager @@ -47,8 +47,7 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica public static final VirtualFile[] EMPTY_ARRAY = new VirtualFile[0]; /** - * Used as a property name in the {@link VirtualFilePropertyEvent} fired when the name of a - * {@link VirtualFile} changes. + * Used as a property name in the {@link VirtualFilePropertyEvent} fired when the name of a {@link VirtualFile} changes. * * @see VirtualFileListener#propertyChanged * @see VirtualFilePropertyEvent#getPropertyName @@ -56,8 +55,7 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica public static final String PROP_NAME = "name"; /** - * Used as a property name in the {@link VirtualFilePropertyEvent} fired when the encoding of a - * {@link VirtualFile} changes. + * Used as a property name in the {@link VirtualFilePropertyEvent} fired when the encoding of a {@link VirtualFile} changes. * * @see VirtualFileListener#propertyChanged * @see VirtualFilePropertyEvent#getPropertyName @@ -65,8 +63,7 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica public static final String PROP_ENCODING = "encoding"; /** - * Used as a property name in the {@link VirtualFilePropertyEvent} fired when the write permission of a - * {@link VirtualFile} changes. + * Used as a property name in the {@link VirtualFilePropertyEvent} fired when write permission of a {@link VirtualFile} changes. * * @see VirtualFileListener#propertyChanged * @see VirtualFilePropertyEvent#getPropertyName @@ -74,8 +71,7 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica public static final String PROP_WRITABLE = "writable"; /** - * Used as a property name in the {@link VirtualFilePropertyEvent} fired when a visibility of a - * {@link VirtualFile} changes. + * Used as a property name in the {@link VirtualFilePropertyEvent} fired when a visibility of a {@link VirtualFile} changes. * * @see VirtualFileListener#propertyChanged * @see VirtualFilePropertyEvent#getPropertyName @@ -83,8 +79,7 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica public static final String PROP_HIDDEN = "HIDDEN"; /** - * Used as a property name in the {@link VirtualFilePropertyEvent} fired when a symlink target of a - * {@link VirtualFile} changes. + * Used as a property name in the {@link VirtualFilePropertyEvent} fired when a symlink target of a {@link VirtualFile} changes. * * @see VirtualFileListener#propertyChanged * @see VirtualFilePropertyEvent#getPropertyName @@ -125,7 +120,7 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica public abstract VirtualFileSystem getFileSystem(); /** - * Gets the path of this file. Path is a string which uniquely identifies file within given + * Gets the path of this file. Path is a string that uniquely identifies a file within a given * {@link VirtualFileSystem}. Format of the path depends on the concrete file system. * For {@link LocalFileSystem} it is an absolute file path with file separator characters * ({@link File#separatorChar}) replaced to the forward slash ({@code '/'}). @@ -136,12 +131,12 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica public abstract String getPath(); /** - * Gets the URL of this file. The URL is a string which uniquely identifies file in all file systems. - * It has the following format: {@code- * File can be found by its URL using {@link VirtualFileManager#findFileByUrl} method. - *
- * Please note these URLs are intended for use withing VFS - meaning they are not necessarily RFC-compliant. + *
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: {@code
File can be found by its URL using {@link VirtualFileManager#findFileByUrl} method.
+ * + *Please note these URLs are intended for use withing VFS - meaning they are not necessarily RFC-compliant.
* * @return the URL consisting of protocol and path * @see VirtualFileManager#findFileByUrl @@ -178,11 +173,10 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica } /** - * Gets the file name without the extension. If file name contains '.' the substring till the last '.' is returned. - * Otherwise the same value as{@link #getName} method returns is returned.
+ * Gets the file name without the extension. If file name contains '.', the substring till the last '.' is returned.
+ * Otherwise, the value of {@link #getName} is returned.
*
* @return the name without extension
- * if there is no '.' in it
*/
@NotNull
public String getNameWithoutExtension() {
@@ -190,9 +184,9 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica
}
/**
- * Renames this file to the {@code newName}.- * This method should be only called within write-action. - * See {@link Application#runWriteAction(Runnable)}. + *
Renames this file to the {@code newName}.
+ * + *This method should only be called within {@link Application#runWriteAction(Runnable) write action}.
* * @param requestor any object to control who called this method. Note that * it is considered to be an external change if {@code requestor} is {@code null}. @@ -211,8 +205,8 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica } /** - * Checks whether this file has write permission. Note that this value may be cached and may differ from - * the write permission of the physical file. + * Checks whether this file could be modified. Note that this value may be cached and may differ from + * write permission of the physical file. * * @return {@code true} if this file is writable, {@code false} otherwise */ @@ -239,10 +233,10 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica } /** - * 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. + *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.
* * @return {@code getPath()} if there are no symbolic links in a file's path; * {@code getCanonicalFile().getPath()} if the link was successfully resolved; @@ -254,10 +248,10 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica } /** - * 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. + *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.
* * @return {@code this} if there are no symbolic links in a file's path; * instance of {@code VirtualFile} if the link was successfully resolved; @@ -568,12 +562,12 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica } /** - * Gets the {@code 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. + *
Gets the {@code 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.
* * @param requestor any object to control who called this method. Note that * it is considered to be an external change if {@code requestor} is {@code null}. @@ -641,13 +635,13 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica public abstract long getLength(); /** - * Refreshes the cached file information from the physical file system. If this file is not a directory + *Refreshes the cached file information from the physical file system. If this file is not a directory * the timestamp value is refreshed and {@code 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 {@code 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. + * 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.
* * @param asynchronous if {@code true}, the method will return immediately and the refresh will be processed * in the background. If {@code false}, the method will return only after the refresh @@ -662,7 +656,7 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica /** * The same as {@link #refresh(boolean, boolean)} but also runs {@code postRunnable} - * after the operation is completed. The runnable is executed on event dispatch thread inside a write action. + * after the operation is completed. The runnable is executed on event dispatch thread inside write action. */ public abstract void refresh(boolean asynchronous, boolean recursive, @Nullable Runnable postRunnable); @@ -741,9 +735,8 @@ public abstract class VirtualFile extends UserDataHolderBase implements Modifica public void setPreloadedContentHint(byte[] preloadedContentHint) { } /** - * @return true if this file is a symlink which is - * - recursive, i.e. points to this file' parent or - * - circular, i.e. has a loop. It means its path has a form of "/.../linkX/.../linkX" + * Returns {@code 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"). */ public boolean isRecursiveOrCircularSymLink() { if (!is(VFileProperty.SYMLINK)) return false; diff --git a/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java b/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java index 83d4046f0591..200682268bd5 100644 --- a/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java +++ b/platform/core-api/src/com/intellij/openapi/vfs/VirtualFileManager.java @@ -70,8 +70,7 @@ public abstract class VirtualFileManager implements ModificationTracker { public abstract void refreshWithoutFileWatcher(boolean asynchronous); /** - * Searches for the file specified by given URL. URL is a string which uniquely identifies file in all - * file systems. + * Searches for a file specified by the given {@link VirtualFile#getUrl() URL}. * * @param url the URL to find file by * @return{@link VirtualFile} if the file was found, {@code null} otherwise
@@ -83,13 +82,13 @@ public abstract class VirtualFileManager implements ModificationTracker {
public abstract VirtualFile findFileByUrl(@NonNls @NotNull String url);
/**
- * Refreshes only the part of the file system needed for searching the file by the given URL and finds file
- * by the given URL.{@link VirtualFile}
- * corresponding to it.- *
- * If this method is invoked not from Swing event dispatch thread, then it must not happen inside a read action. + *Refreshes only the part of the file system needed for searching the file by the given URL and finds file + * by the given URL.
+ * + *This method is useful when the file was created externally and you need to find {@link VirtualFile}
+ * corresponding to it.
If this method is invoked not from Swing event dispatch thread, then it must not happen inside a read action.
* * @param url the URL * @return{@link VirtualFile} if the file was found, {@code null} otherwise
@@ -123,12 +122,12 @@ public abstract class VirtualFileManager implements ModificationTracker {
public abstract void addAsyncFileListener(@NotNull AsyncFileListener listener, @NotNull Disposable parentDisposable);
/**
- * Constructs URL by specified protocol and path. URL is a string which uniquely identifies file in all
- * file systems.
+ * Constructs a {@link VirtualFile#getUrl() URL} by specified protocol and path.
*
* @param protocol the protocol
* @param path the path
* @return URL
+ * @see VirtualFile#getUrl
*/
@NotNull
public static String constructUrl(@NotNull String protocol, @NotNull String path) {
@@ -194,6 +193,7 @@ public abstract class VirtualFileManager implements ModificationTracker {
@ApiStatus.Internal
public abstract int storeName(@NotNull String name);
+
@ApiStatus.Internal
@NotNull
public abstract CharSequence getVFileName(int nameId);