[vfs][cleanup] FileAttribute

+ clean up outdated code in FileAttribute, add some comments

GitOrigin-RevId: 0f9b5ff927770dab929b03ac59697890b83872c0

platform/analysis-api/src/com/intellij/openapi/vfs/newvfs/FileAttribute.java

@@ -3,7 +3,6 @@ package com.intellij.openapi.vfs.newvfs;
 
 import com.intellij.openapi.util.io.FileUtil;
 import com.intellij.openapi.vfs.VirtualFile;
-import org.jetbrains.annotations.ApiStatus;
 import org.jetbrains.annotations.NonNls;
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
@@ -14,21 +13,34 @@ import java.io.IOException;
 import java.util.Set;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * Identifies a file attribute in {@link ManagingFS}. Conceptually, every file in {@link ManagingFS} has a set of attributes,
+ * identified by {@link FileAttribute}.
+ * Attribute has a name and a version.
+ * Version is used to identify changes in attribute content's binary format: if attribute's version is different from the
+ * stored one, stored attribute content is treated as non-existent.
+ * <br/>
+ * This class ctor prohibit creation of >1 instances with the same id.
+ * In general, objects of this class should be created as static final constants -- i.e. it should be limited number of
+ * instances, and no chance of occasionally creating duplicates.
+ *
+ * @see ManagingFS#readAttribute(VirtualFile, FileAttribute)
+ * @see ManagingFS#writeAttribute(VirtualFile, FileAttribute)
+ */
 public class FileAttribute {
-  private static final Set<String> ourRegisteredIds = ConcurrentHashMap.newKeySet();
   private static final int UNDEFINED_VERSION = -1;
-  private final String myId;
-  private final int myVersion;
+
+  private static final Set<String> registeredAttributeIds = ConcurrentHashMap.newKeySet();
+
+  private final String id;
+  private final int version;
+
   /**
    * Indicates that attribute content ({@link #writeAttributeBytes(VirtualFile, byte[])}) are of fixed size.
    * This serves as a hint for storage allocation: for fixed-size attributes space could be allocated
    * without reserve for future extension.
    */
-  private final boolean myFixedSize;
-  /**
-   * Intended for enumeration of all binary data, but not used/implemented for today
-   */
-  private final boolean myShouldEnumerate;
+  private final boolean fixedSize;
 
   public FileAttribute(@NonNls @NotNull String id) {
     this(id, UNDEFINED_VERSION, false, false);
@@ -38,18 +50,21 @@ public class FileAttribute {
     this(id, version, fixedSize, false);
   }
 
-  public FileAttribute(@NonNls @NotNull String id, int version, boolean fixedSize, boolean shouldEnumerate) {
-    this(version, fixedSize, id, shouldEnumerate);
-    boolean added = ourRegisteredIds.add(id);
-    assert added : "Attribute id='" + id+ "' is not unique";
+  /** @deprecated use {@link FileAttribute#FileAttribute(String, int, boolean)} -- shouldEnumerate is ignored (was never implemented) */
+  @Deprecated
+  public FileAttribute(@NonNls @NotNull String id,
+                       int version,
+                       boolean fixedSize,
+                       @SuppressWarnings("unused") boolean shouldEnumerate) {
+    this(version, fixedSize, id);
+    boolean added = registeredAttributeIds.add(id);
+    assert added : "Attribute id='" + id + "' is not unique";
   }
 
-  private FileAttribute(int version, boolean fixedSize,@NotNull String id, boolean shouldEnumerate) {
-    myId = id;
-    myVersion = version;
-    myFixedSize = fixedSize;
-    // TODO enumerate all binary data if asked
-    myShouldEnumerate = shouldEnumerate;
+  private FileAttribute(int version, boolean fixedSize, @NotNull String id) {
+    this.id = id;
+    this.version = version;
+    this.fixedSize = fixedSize;
   }
 
   /**
@@ -96,41 +111,34 @@ public class FileAttribute {
   }
 
   public @NotNull String getId() {
-    return myId;
+    return id;
   }
 
   public boolean isFixedSize() {
-    return myFixedSize;
+    return fixedSize;
   }
 
   public @NotNull FileAttribute newVersion(int newVersion) {
-    return new FileAttribute(newVersion, myFixedSize, myId, myShouldEnumerate);
+    return new FileAttribute(newVersion, fixedSize, id);
   }
 
   public int getVersion() {
-    return myVersion;
+    return version;
   }
 
   public boolean isVersioned() {
-    return myVersion != UNDEFINED_VERSION;
+    return version != UNDEFINED_VERSION;
   }
 
   public static void resetRegisteredIds() {
-    ourRegisteredIds.clear();
-  }
-
-  @ApiStatus.Internal
-  public static FileAttribute instantiateForRecovery(@NonNls @NotNull String id, int version, boolean fixedSize) {
-    // shouldEnumerate is not used yet
-    return new FileAttribute(version, fixedSize, id, false); // do not register the instance
+    registeredAttributeIds.clear();
   }
 
   @Override
   public String toString() {
-    return "FileAttribute[" + myId + "]" +
-           "{version: " + myVersion +
-           ", fixedSize: " + myFixedSize +
-           ", shouldEnumerate: " + myShouldEnumerate +
+    return "FileAttribute[" + id + "]" +
+           "{version: " + version +
+           ", fixedSize: " + fixedSize +
            '}';
   }
 }