fix "IDEA-221944 Deadlock on opening second project" and support preloading for proje...
[idea/community.git] / platform / core-api / src / com / intellij / psi / PsiManager.java
1 // Copyright 2000-2019 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license that can be found in the LICENSE file.
2 package com.intellij.psi;
3
4 import com.intellij.openapi.Disposable;
5 import com.intellij.openapi.project.Project;
6 import com.intellij.openapi.util.UserDataHolderBase;
7 import com.intellij.openapi.vfs.VirtualFile;
8 import com.intellij.psi.util.PsiModificationTracker;
9 import org.jetbrains.annotations.NotNull;
10 import org.jetbrains.annotations.Nullable;
11
12 /**
13  * The main entry point for accessing the PSI services for a project.
14  */
15 public abstract class PsiManager extends UserDataHolderBase {
16   /**
17    * Returns the PSI manager instance for the specified project.
18    *
19    * @param project the project for which the PSI manager is requested.
20    * @return the PSI manager instance.
21    */
22   @NotNull
23   public static PsiManager getInstance(@NotNull Project project) {
24     return project.getService(PsiManager.class);
25   }
26
27   /**
28    * Returns the project with which the PSI manager is associated.
29    *
30    * @return the project instance.
31    */
32   @NotNull
33   public abstract Project getProject();
34
35   /**
36    * Returns the PSI file corresponding to the specified virtual file.
37    *
38    * @param file the file for which the PSI is requested.
39    * @return the PSI file, or {@code null} if {@code file} is a directory, an invalid virtual file,
40    * or the current project is a dummy or default project.
41    */
42   @Nullable
43   public abstract PsiFile findFile(@NotNull VirtualFile file);
44
45   @Nullable
46   public abstract FileViewProvider findViewProvider(@NotNull VirtualFile file);
47
48   /**
49    * Returns the PSI directory corresponding to the specified virtual file system directory.
50    *
51    * @param file the directory for which the PSI is requested.
52    * @return the PSI directory, or {@code null} if there is no PSI for the specified directory in this project.
53    */
54   @Nullable
55   public abstract PsiDirectory findDirectory(@NotNull VirtualFile file);
56
57   /**
58    * Checks if the specified two PSI elements (possibly invalid) represent the same source element
59    * or can are considered equivalent for resolve purposes.
60    * <p>
61    * Can be used to match two versions of the PSI tree with each other after a reparse.
62    * <p>
63    * For example, Java classes with the same fully-qualified name are equivalent, which is useful when working
64    * with both library source and class roots. Source and compiled classes are definitely different ({@code equals()} returns {@code false}),
65    * but for reference resolve or inheritance checks, they're equivalent.
66    *
67    * @param element1 the first element to check for equivalence
68    * @param element2 the second element to check for equivalence
69    * @return {@code true} if the elements are equivalent, {@code false} if the elements are different or
70    * it was not possible to determine the equivalence
71    */
72   public abstract boolean areElementsEquivalent(@Nullable PsiElement element1, @Nullable PsiElement element2);
73
74   /**
75    * Reloads the contents of the specified PSI file and its associated document (if any) from the disk.
76    *
77    * @param file the PSI file to reload.
78    */
79   public abstract void reloadFromDisk(@NotNull PsiFile file);   //todo: move to FileDocumentManager
80
81   /**
82    * Adds a listener for receiving notifications about all changes in the PSI tree of the project.
83    *
84    * @param listener the listener instance.
85    */
86   public abstract void addPsiTreeChangeListener(@NotNull PsiTreeChangeListener listener);
87
88   /**
89    * Adds a listener for receiving notifications about all changes in the PSI tree of the project.
90    *
91    * @param listener         the listener instance.
92    * @param parentDisposable object, after whose disposing the listener should be removed
93    */
94   public abstract void addPsiTreeChangeListener(@NotNull PsiTreeChangeListener listener, @NotNull Disposable parentDisposable);
95
96   /**
97    * Removes a listener for receiving notifications about all changes in the PSI tree of the project.
98    *
99    * @param listener the listener instance.
100    */
101   public abstract void removePsiTreeChangeListener(@NotNull PsiTreeChangeListener listener);
102
103   /**
104    * Returns the modification tracker for the project, which can be used to get the PSI
105    * modification count value.
106    *
107    * @return the modification tracker instance.
108    */
109   @NotNull
110   public abstract PsiModificationTracker getModificationTracker();
111
112   /**
113    * Notifies the PSI manager that a batch operation sequentially processing multiple files
114    * is starting. Memory occupied by cached PSI trees is released more eagerly during such a
115    * batch operation.
116    */
117   public abstract void startBatchFilesProcessingMode();
118
119   /**
120    * Notifies the PSI manager that a batch operation sequentially processing multiple files
121    * is finishing. Memory occupied by cached PSI trees is released more eagerly during such a
122    * batch operation.
123    */
124   public abstract void finishBatchFilesProcessingMode();
125
126   /**
127    * Checks if the PSI manager has been disposed and the PSI for this project can no
128    * longer be used.
129    *
130    * @return {@code true} if the PSI manager is disposed, {@code false} otherwise.
131    */
132   public abstract boolean isDisposed();
133
134   /**
135    * Clears the resolve caches of the PSI manager. Can be used to reduce memory consumption
136    * in batch operations sequentially processing multiple files. Can be invoked from any thread.
137    */
138   public abstract void dropResolveCaches();
139
140   /**
141    * Clears all {@link com.intellij.psi.util.CachedValue} depending on {@link PsiModificationTracker#MODIFICATION_COUNT} and resolve caches.
142    * Can be used to reduce memory consumption in batch operations sequentially processing multiple files. Should be invoked on Swing thread.
143    */
144   public abstract void dropPsiCaches();
145
146   /**
147    * Checks if the specified PSI element belongs to the sources of the project.
148    *
149    * @param element the element to check.
150    * @return {@code true} if the element belongs to the sources of the project, {@code false} otherwise.
151    */
152   public abstract boolean isInProject(@NotNull PsiElement element);
153 }