lang-api/src/com/intellij/psi/PsiManager.java

   1 /*
   2  * Copyright 2000-2007 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.Computable;
  21 import com.intellij.openapi.util.UserDataHolderBase;
  22 import com.intellij.openapi.vfs.VirtualFile;
  23 import com.intellij.psi.codeStyle.CodeStyleManager;
  24 import com.intellij.psi.search.PsiSearchHelper;
  25 import com.intellij.psi.util.CachedValuesManager;
  26 import com.intellij.psi.util.PsiModificationTracker;
  27 import com.intellij.util.IncorrectOperationException;
  28 import com.intellij.util.ThrowableRunnable;
  29 import org.jetbrains.annotations.NotNull;
  30 import org.jetbrains.annotations.Nullable;
  31
  32 /**
  33  * The main entry point for accessing the PSI services for a project.
  34  */
  35 public abstract class PsiManager extends UserDataHolderBase {
  36
  37   /**
  38    * Returns the PSI manager instance for the specified project.
  39    *
  40    * @param project the project for which the PSI manager is requested.
  41    * @return the PSI manager instance.
  42    */
  43   @NotNull
  44   public static PsiManager getInstance(@NotNull Project project) {
  45     return project.getComponent(PsiManager.class);
  46   }
  47
  48   /**
  49    * Returns the project with which the PSI manager is associated.
  50    *
  51    * @return the project instance.
  52    */
  53   @NotNull
  54   public abstract Project getProject();
  55
  56   /**
  57    * Returns the PSI file corresponding to the specified virtual file.
  58    *
  59    * @param file the file for which the PSI is requested.
  60    * @return the PSI file, or null if <code>file</code> is a directory, an invalid virtual file,
  61    * or the current project is a dummy or default project.
  62    */
  63   @Nullable
  64   public abstract PsiFile findFile(@NotNull VirtualFile file);
  65
  66   @Nullable
  67   public abstract FileViewProvider findViewProvider(@NotNull VirtualFile file);
  68
  69   /**
  70    * Returns the PSI directory corresponding to the specified virtual file system directory.
  71    *
  72    * @param file the directory for which the PSI is requested.
  73    * @return the PSI directory, or null if there is no PSI for the specified directory in this project.
  74    */
  75   @Nullable
  76   public abstract PsiDirectory findDirectory(@NotNull VirtualFile file);
  77
  78   /**
  79    * Checks if the specified two PSI elements (possibly invalid) represent the same source element
  80    * (for example, a class with the same full-qualified name). Can be used to match two versions of the
  81    * PSI tree with each other after a reparse.
  82    *
  83    * @param element1 the first element to check for equivalence
  84    * @param element2 the second element to check for equivalence
  85    * @return true if the elements are equivalent, false if the elements are different or
  86    * it was not possible to determine the equivalence
  87    */
  88   public abstract boolean areElementsEquivalent(@Nullable PsiElement element1, @Nullable PsiElement element2);
  89
  90   /**
  91    * Reloads the contents of the specified PSI file and its associated document (if any) from the disk.
  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, 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 code style manager for the project. The code style manager can be used
 120    * to reformat code fragments, get names for elements according to the user's code style
 121    * and work with import statements and full-qualified names.
 122    *
 123    * @return the code style manager instance.
 124    */
 125   @NotNull
 126   public abstract CodeStyleManager getCodeStyleManager();
 127
 128   /**
 129    * Returns the search helper for the project, which provides low-level search and
 130    * find usages functionality. It can be used to perform operations like finding references
 131    * to an element, finding overriding / inheriting elements, finding to do items and so on.
 132    *
 133    * @return the search helper instance.
 134    */
 135   @NotNull
 136   public abstract PsiSearchHelper getSearchHelper();
 137
 138   /**
 139    * Returns the modification tracker for the project, which can be used to get the PSI
 140    * modification count value.
 141    *
 142    * @return the modification tracker instance.
 143    */
 144   @NotNull
 145   public abstract PsiModificationTracker getModificationTracker();
 146
 147
 148   /**
 149    * Returns the cached values manager for the project, which can be used to create values
 150    * which are automatically recalculated based on changes of the elements on which they depend.
 151    *
 152    * @return the cached values manager instance.
 153    */
 154   @NotNull
 155   public abstract CachedValuesManager getCachedValuesManager();
 156
 157   /**
 158    * Moves the specified file to the specified directory.
 159    *
 160    * @param file         the file to move.
 161    * @param newParentDir the directory to move the file into.
 162    * @throws IncorrectOperationException if the modification is not supported or not possible for some reason.
 163    */
 164   public abstract void moveFile(@NotNull PsiFile file, @NotNull PsiDirectory newParentDir) throws IncorrectOperationException;
 165
 166   /**
 167    * Moves the specified directory to the specified parent directory.
 168    *
 169    * @param dir          the directory to move.
 170    * @param newParentDir the directory to move <code>dir</code> into.
 171    * @throws IncorrectOperationException if the modification is not supported or not possible for some reason.
 172    */
 173   public abstract void moveDirectory(@NotNull PsiDirectory dir, @NotNull PsiDirectory newParentDir) throws IncorrectOperationException;
 174
 175   /**
 176    * Checks if it is possible to move the specified PSI element under the specified container,
 177    * and throws an exception if the move is not possible. Does not actually modify anything.
 178    *
 179    * @param element      the element to check the move possibility.
 180    * @param newContainer the target container element to move into.
 181    * @throws IncorrectOperationException if the modification is not supported or not possible for some reason.
 182    */
 183   public abstract void checkMove(@NotNull PsiElement element, @NotNull PsiElement newContainer) throws IncorrectOperationException;
 184
 185   /**
 186    * Notifies the PSI manager that a batch operation sequentially processing multiple files
 187    * is starting. Memory occupied by cached PSI trees is released more eagerly during such a
 188    * batch operation.
 189    */
 190   public abstract void startBatchFilesProcessingMode();
 191
 192   /**
 193    * Notifies the PSI manager that a batch operation sequentially processing multiple files
 194    * is finishing. Memory occupied by cached PSI trees is released more eagerly during such a
 195    * batch operation.
 196    */
 197   public abstract void finishBatchFilesProcessingMode();
 198
 199   /**
 200    * Checks if the PSI manager has been disposed and the PSI for this project can no
 201    * longer be used.
 202    *
 203    * @return true if the PSI manager is disposed, false otherwise.
 204    */
 205   public abstract boolean isDisposed();
 206
 207   /**
 208    * Clears the resolve caches of the PSI manager. Can be used to reduce memory consumption
 209    * in batch operations sequentially processing multiple files.
 210    */
 211   public abstract void dropResolveCaches();
 212
 213   /**
 214    * Checks if the specified PSI element belongs to the sources of the project.
 215    *
 216    * @param element the element to check.
 217    * @return true if the element belongs to the sources of the project, false otherwise.
 218    */
 219   public abstract boolean isInProject(@NotNull PsiElement element);
 220
 221   /**
 222    * Disables automatic formatting of modified PSI elements, runs the specified operation
 223    * and re-enables the formatting. Can be used to improve performance of PSI write
 224    * operations.
 225    *
 226    * @param r the operation to run.
 227    */
 228   public abstract void performActionWithFormatterDisabled(Runnable r);
 229   public abstract <T extends Throwable> void performActionWithFormatterDisabled(ThrowableRunnable<T> r) throws
 230                                                                                                         T;
 231   public abstract <T> T performActionWithFormatterDisabled(Computable<T> r);
 232
 233   public abstract void postponeAutoFormattingInside(Runnable runnable);
 234
 235   public abstract void registerLanguageInjector(@NotNull LanguageInjector injector);
 236
 237   public abstract void registerLanguageInjector(@NotNull LanguageInjector injector, Disposable parentDisposable);
 238
 239   public abstract void unregisterLanguageInjector(@NotNull LanguageInjector injector);
 240
 241 }