mirror of
https://gitflic.ru/project/openide/openide.git
synced 2026-09-27 10:03:11 +07:00
Cleanup (javadoc; IDEA-222411)
GitOrigin-RevId: 3e1b39aebef53767ce5cf6559ccb71121c90499d
This commit is contained in:
Roman Shevchenko
committed by
intellij-monorepo-bot
intellij-monorepo-bot
parent
4424756876
commit
8172db759b
@@ -26,18 +26,18 @@ import java.io.OutputStream;
|
||||
import java.nio.charset.Charset;
|
||||
|
||||
/**
|
||||
* Represents a file in {@link VirtualFileSystem}. A particular file is represented by equal
|
||||
* <p>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}.
|
||||
* <p/>
|
||||
* 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}).
|
||||
* <p/>
|
||||
* If an in-memory implementation of VirtualFile is required, {@link LightVirtualFile}
|
||||
* can be used.
|
||||
* <p/>
|
||||
* Please see <a href="http://www.jetbrains.org/intellij/sdk/docs/basics/virtual_file_system.html">Virtual File System</a>
|
||||
* for high-level overview.
|
||||
* is deleted, in which case {@link #isValid()} will return {@code false}.</p>
|
||||
*
|
||||
* <p>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}).</p>
|
||||
*
|
||||
* <p>If an in-memory implementation of VirtualFile is required, {@link LightVirtualFile} can be used.</p>
|
||||
*
|
||||
* <p>Please see <a href="http://www.jetbrains.org/intellij/sdk/docs/basics/virtual_file_system.html">Virtual File System</a>
|
||||
* for a high-level overview.</p>
|
||||
*
|
||||
* @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 <protocol>://<path>}.
|
||||
* <p>
|
||||
* File can be found by its URL using {@link VirtualFileManager#findFileByUrl} method.
|
||||
* <p>
|
||||
* Please note these URLs are intended for use withing VFS - meaning they are not necessarily RFC-compliant.
|
||||
* <p>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 <protocol>://<path>}.</p>
|
||||
*
|
||||
* <p>File can be found by its URL using {@link VirtualFileManager#findFileByUrl} method.</p>
|
||||
*
|
||||
* <p>Please note these URLs are intended for use withing VFS - meaning they are not necessarily RFC-compliant.</p>
|
||||
*
|
||||
* @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 <code>{@link #getName}</code> 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}.<p>
|
||||
* This method should be only called within write-action.
|
||||
* See {@link Application#runWriteAction(Runnable)}.
|
||||
* <p>Renames this file to the {@code newName}.</p>
|
||||
*
|
||||
* <p>This method should only be called within {@link Application#runWriteAction(Runnable) write action}.</p>
|
||||
*
|
||||
* @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).
|
||||
* <p/>
|
||||
* <b>Note</b>: 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.
|
||||
* <p>Resolves all symbolic links containing in a path to this file and returns a path to a link target (in platform-independent format).</p>
|
||||
*
|
||||
* <p><b>Note</b>: 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.</p>
|
||||
*
|
||||
* @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.
|
||||
* <p/>
|
||||
* <b>Note</b>: 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.
|
||||
* <p>Resolves all symbolic links containing in a path to this file and returns a link target.</p>
|
||||
*
|
||||
* <p><b>Note</b>: 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.</p>
|
||||
*
|
||||
* @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.<p>
|
||||
* <p/>
|
||||
* Normally you should not use this method.
|
||||
* <p>
|
||||
* Writes BOM first, if there is any. See <a href=http://unicode.org/faq/utf_bom.html>Unicode Byte Order Mark FAQ</a> for an explanation.
|
||||
* <p>Gets the {@code OutputStream} for this file and sets modification stamp and time stamp to the specified values
|
||||
* after closing the stream.</p>
|
||||
*
|
||||
* <p>Normally, you should not use this method.</p>
|
||||
*
|
||||
* <p>Writes BOM first, if there is any. See <a href=http://unicode.org/faq/utf_bom.html>Unicode Byte Order Mark FAQ</a> for an explanation.</p>
|
||||
*
|
||||
* @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
|
||||
* <p>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.<p>
|
||||
* If this file is a directory the set of its children is refreshed. If recursive value is {@code true} all
|
||||
* children are refreshed recursively.
|
||||
* <p/>
|
||||
* 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.</p>
|
||||
*
|
||||
* <p>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.</p>
|
||||
*
|
||||
* @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 <i>recursive</i> (i.e. points to this file' parent) or
|
||||
* <i>circular</i> (i.e. its path has a form of "/.../linkX/.../linkX").
|
||||
*/
|
||||
public boolean isRecursiveOrCircularSymLink() {
|
||||
if (!is(VFileProperty.SYMLINK)) return false;
|
||||
|
||||
@@ -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 <code>{@link VirtualFile}</code> 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.<br>
|
||||
* <p/>
|
||||
* This method is useful when the file was created externally and you need to find <code>{@link VirtualFile}</code>
|
||||
* corresponding to it.<p>
|
||||
* <p/>
|
||||
* If this method is invoked not from Swing event dispatch thread, then it must not happen inside a read action.
|
||||
* <p>Refreshes only the part of the file system needed for searching the file by the given URL and finds file
|
||||
* by the given URL.</p>
|
||||
*
|
||||
* <p>This method is useful when the file was created externally and you need to find <code>{@link VirtualFile}</code>
|
||||
* corresponding to it.</p>
|
||||
*
|
||||
* <p>If this method is invoked not from Swing event dispatch thread, then it must not happen inside a read action.</p>
|
||||
*
|
||||
* @param url the URL
|
||||
* @return <code>{@link VirtualFile}</code> 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);
|
||||
|
||||
Reference in New Issue
Block a user