javadocs: remove unnecessary qualifiers in references
[idea/community.git] / platform / core-api / src / com / intellij / psi / util / PsiModificationTracker.java
1 /*
2  * Copyright 2000-2014 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.util;
17
18 import com.intellij.openapi.components.ServiceManager;
19 import com.intellij.openapi.project.Project;
20 import com.intellij.openapi.util.Key;
21 import com.intellij.openapi.util.ModificationTracker;
22 import com.intellij.util.messages.Topic;
23 import org.jetbrains.annotations.NotNull;
24
25 /**
26  * An interface used to support tracking of common PSI modifications. It has three main usage patterns:
27  * <ol>
28  *   <li/> Get a stamp of current PSI state. This stamp is increased when PSI is modified, allowing other subsystems
29  *   to check if PSI has changed since they accessed it last time. This can be used to flush and rebuild various internal caches.
30  *   See {@link #getModificationCount()}, {@link #getJavaStructureModificationCount()}, {@link #getOutOfCodeBlockModificationCount()}
31  *
32  *   <li/> Make a {@link CachedValue} instance dependent on a specific PSI modification tracker.
33  *   To achieve that, one should can one of the constants in this interface as {@link CachedValueProvider.Result}
34  *   dependencies.
35  *   See {@link #MODIFICATION_COUNT}, {@link #JAVA_STRUCTURE_MODIFICATION_COUNT}, {@link #OUT_OF_CODE_BLOCK_MODIFICATION_COUNT}
36  *
37  *   <li/> Subscribe to any PSI change (for example, to drop caches in the listener manually).
38  *   See {@link PsiModificationTracker.Listener}
39  *
40  * </ol>
41  */
42 public interface PsiModificationTracker extends ModificationTracker {
43
44   /**
45    * Provides a way to get the instance of {@link PsiModificationTracker} corresponding to a given project.
46    * @see #getInstance(Project)
47    */
48   class SERVICE {
49     private SERVICE() {
50     }
51
52     /**
53      * @param project
54      * @return The instance of {@link PsiModificationTracker} corresponding to the given project.
55      */
56     public static PsiModificationTracker getInstance(Project project) {
57       return ServiceManager.getService(project, PsiModificationTracker.class);
58     }
59   }
60   
61   /**
62    * This key can be passed as a dependency in a {@link CachedValueProvider}.
63    * The corresponding {@link CachedValue} will then be flushed on every physical PSI change.
64    * @see #getModificationCount()
65    */
66   Key MODIFICATION_COUNT = Key.create("MODIFICATION_COUNT");
67
68   /**
69    * This key can be passed as a dependency in a {@link CachedValueProvider}.
70    * The corresponding {@link CachedValue} will then be flushed on every physical PSI change that doesn't happen inside a Java code block.
71    * This can include changes on Java class or file level, or changes in non-Java files, e.g. XML. Rarely needed.
72    * @see #getOutOfCodeBlockModificationCount()
73    */
74   Key OUT_OF_CODE_BLOCK_MODIFICATION_COUNT = Key.create("OUT_OF_CODE_BLOCK_MODIFICATION_COUNT");
75
76   /**
77    * This key can be passed as a dependency in a {@link CachedValueProvider}.
78    * The corresponding {@link CachedValue} will then be flushed on every physical PSI change that can affect Java structure and resolve.
79    * @see #getJavaStructureModificationCount()
80    */
81   Key JAVA_STRUCTURE_MODIFICATION_COUNT = Key.create("JAVA_STRUCTURE_MODIFICATION_COUNT");
82
83   /**
84    * A topic to subscribe for all PSI modification count changes.
85    * @see com.intellij.util.messages.MessageBus
86    */
87   Topic<Listener> TOPIC = new Topic<Listener>("modification tracker", Listener.class, Topic.BroadcastDirection.TO_PARENT);
88
89   /**
90    * Tracks any PSI modification.
91    * @return current counter value. Increased whenever any physical PSI is changed.
92    */
93   @Override
94   long getModificationCount();
95
96   /**
97    * @return Same as {@link #getJavaStructureModificationCount()}, but also includes changes in non-Java files, e.g. XML. Rarely needed.
98    */
99   long getOutOfCodeBlockModificationCount();
100
101   /**
102    * @return an object returning {@link #getOutOfCodeBlockModificationCount()}
103    */
104   @NotNull
105   ModificationTracker getOutOfCodeBlockModificationTracker();
106
107   /**
108    * Tracks structural Java modifications, i.e. the ones on class/method/field/file level. Modifications inside method bodies are not tracked.
109    * Useful to work with resolve caches that only depend on Java structure, and not the method code.
110    * @return current counter value. Increased whenever any physical PSI in Java structure is changed.
111    */
112   long getJavaStructureModificationCount();
113
114   /**
115    * @return an object returning {@link #getJavaStructureModificationCount()}
116    */
117   @NotNull
118   ModificationTracker getJavaStructureModificationTracker();
119
120   /**
121    * A listener to be notified on any PSI modification count change (which happens on any physical PSI change).
122    * @see #TOPIC
123    */
124   interface Listener {
125
126     /**
127      * A method invoked on Swing EventDispatchThread each time any physical PSI change is detected
128      */
129     void modificationCountChanged();
130   }
131 }