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