lang-api/src/com/intellij/psi/PsiDocumentManager.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.editor.Document;
  19 import com.intellij.openapi.project.Project;
  20 import com.intellij.openapi.util.Computable;
  21 import org.jetbrains.annotations.NotNull;
  22 import org.jetbrains.annotations.Nullable;
  23
  24 import java.util.EventListener;
  25
  26 /**
  27  * Manages the relationship between documents and PSI trees.
  28  */
  29 public abstract class PsiDocumentManager {
  30   /**
  31    * Returns the document manager instance for the specified project.
  32    *
  33    * @param project the project for which the document manager is requested.
  34    * @return the document manager instance.
  35    */
  36   public static PsiDocumentManager getInstance(@NotNull Project project) {
  37     return project.getComponent(PsiDocumentManager.class);
  38   }
  39
  40   /**
  41    * Returns the PSI file for the specified document.
  42    *
  43    * @param document the document for which the PSI file is requested.
  44    * @return the PSI file instance.
  45    */
  46   @Nullable
  47   public abstract PsiFile getPsiFile(@NotNull Document document);
  48
  49   /**
  50    * Returns the cached PSI file for the specified document.
  51    *
  52    * @param document the document for which the PSI file is requested.
  53    * @return the PSI file instance, or null if there is currently no cached PSI tree for the file.
  54    */
  55   @Nullable
  56   public abstract PsiFile getCachedPsiFile(@NotNull Document document);
  57
  58   /**
  59    * Returns the document for the specified PSI file.
  60    *
  61    * @param file the file for which the document is requested.
  62    * @return the document instance, or null if the file is binary or has no associated document.
  63    */
  64   @Nullable
  65   public abstract Document getDocument(@NotNull PsiFile file);
  66
  67   /**
  68    * Returns the cached document for the specified PSI file.
  69    *
  70    * @param file the file for which the document is requested.
  71    * @return the document instance, or null if there is currently no cached document for the file.
  72    */
  73   @Nullable
  74   public abstract Document getCachedDocument(@NotNull PsiFile file);
  75
  76   /**
  77    * Commits (updates the PSI tree for) all modified but not committed documents.
  78    * Before a modified document is committed, accessing its PSI may return elements
  79    * corresponding to original (unmodified) state of the document.
  80    */
  81   public abstract void commitAllDocuments();
  82
  83   /**
  84    * If the document is committed, runs action synchronously, otherwise schedules to execute it right after it has been committed.
  85    * @param document
  86    * @param action
  87    */
  88   public abstract void performForCommittedDocument(@NotNull Document document, @NotNull Runnable action);
  89
  90   /**
  91    * Updates the PSI tree for the specified document.
  92    * Before a modified document is committed, accessing its PSI may return elements
  93    * corresponding to original (unmodified) state of the document.
  94    *
  95    * @param document the document to commit.
  96    */
  97   public abstract void commitDocument(Document document);
  98
  99   /**
 100    * Returns the list of documents which have been modified but not committed.
 101    *
 102    * @return the list of uncommitted documents.
 103    * @see #commitDocument(com.intellij.openapi.editor.Document)
 104    */
 105   public abstract Document[] getUncommittedDocuments();
 106
 107   /**
 108    * Checks if the specified document has been committed.
 109    *
 110    * @param document the document to check.
 111    * @return true if the document was modified but not committed, false otherwise
 112    * @see #commitDocument(com.intellij.openapi.editor.Document)
 113    */
 114   public abstract boolean isUncommited(Document document);
 115
 116   /**
 117    * Checks if any modified documents have not been committed.
 118    *
 119    * @return true if there are uncommitted documents, false otherwise
 120    */
 121   public abstract boolean hasUncommitedDocuments();
 122
 123   /**
 124    * Commits the documents and runs the specified operation, which does not return a value, in a read action.
 125    * Can be called from a thread other than the Swing dispatch thread.
 126    *
 127    * @param runnable the operation to execute.
 128    */
 129   public abstract void commitAndRunReadAction(@NotNull Runnable runnable);
 130
 131   /**
 132    * Commits the documents and runs the specified operation, which returns a value, in a read action.
 133    * Can be called from a thread other than the Swing dispatch thread.
 134    *
 135    * @param computation the operation to execute.
 136    * @return the value returned by the operation.
 137    */
 138   public abstract <T> T commitAndRunReadAction(@NotNull Computable<T> computation);
 139
 140   /**
 141    * Listener for receiving notifications about creation of {@link Document} and {@link PsiFile} instances.
 142    */
 143   public interface Listener extends EventListener {
 144     /**
 145      * Called when a document instance is created for a file.
 146      *
 147      * @param document the created document instance.
 148      * @param psiFile the file for which the document was created.
 149      * @see PsiDocumentManager#getDocument(PsiFile)
 150      */
 151     void documentCreated(Document document, PsiFile psiFile);
 152
 153     /**
 154      * Called when a file instance is created for a document.
 155      *
 156      * @param file the created file instance.
 157      * @param document the document for which the file was created.
 158      * @see PsiDocumentManager#getDocument(PsiFile)
 159      */
 160     void fileCreated(PsiFile file, Document document);
 161   }
 162
 163   /**
 164    * Adds a listener for receiving notifications about creation of {@link Document} and {@link PsiFile} instances.
 165    *
 166    * @param listener the listener to add.
 167    */
 168   public abstract void addListener(@NotNull Listener listener);
 169
 170   /**
 171    * Removes a listener for receiving notifications about creation of {@link Document} and {@link PsiFile} instances.
 172    *
 173    * @param listener the listener to add.
 174    */
 175   public abstract void removeListener(@NotNull Listener listener);
 176
 177   public abstract boolean isDocumentBlockedByPsi(@NotNull Document doc);
 178
 179   public abstract void doPostponedOperationsAndUnblockDocument(@NotNull Document doc);
 180 }