2 * Copyright 2000-2014 JetBrains s.r.o.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
16 package com.intellij.psi.util;
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;
26 * An interface used to support tracking of common PSI modifications. It has three main usage patterns:
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()}
32 * <li/> Make a {@link com.intellij.psi.util.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 com.intellij.psi.util.CachedValueProvider.Result}
35 * See {@link #MODIFICATION_COUNT}, {@link #JAVA_STRUCTURE_MODIFICATION_COUNT}, {@link #OUT_OF_CODE_BLOCK_MODIFICATION_COUNT}
37 * <li/> Subscribe to any PSI change (for example, to drop caches in the listener manually).
38 * See {@link com.intellij.psi.util.PsiModificationTracker.Listener}
42 public interface PsiModificationTracker extends ModificationTracker {
45 * Provides a way to get the instance of {@link com.intellij.psi.util.PsiModificationTracker} corresponding to a given project.
46 * @see #getInstance(com.intellij.openapi.project.Project)
54 * @return The instance of {@link com.intellij.psi.util.PsiModificationTracker} corresponding to the given project.
56 public static PsiModificationTracker getInstance(Project project) {
57 return ServiceManager.getService(project, PsiModificationTracker.class);
62 * This key can be passed as a dependency in a {@link com.intellij.psi.util.CachedValueProvider}.
63 * The corresponding {@link com.intellij.psi.util.CachedValue} will then be flushed on every physical PSI change.
64 * @see #getModificationCount()
66 Key MODIFICATION_COUNT = Key.create("MODIFICATION_COUNT");
69 * This key can be passed as a dependency in a {@link com.intellij.psi.util.CachedValueProvider}.
70 * The corresponding {@link com.intellij.psi.util.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()
74 Key OUT_OF_CODE_BLOCK_MODIFICATION_COUNT = Key.create("OUT_OF_CODE_BLOCK_MODIFICATION_COUNT");
77 * This key can be passed as a dependency in a {@link com.intellij.psi.util.CachedValueProvider}.
78 * The corresponding {@link com.intellij.psi.util.CachedValue} will then be flushed on every physical PSI change that can affect Java structure and resolve.
79 * @see #getJavaStructureModificationCount()
81 Key JAVA_STRUCTURE_MODIFICATION_COUNT = Key.create("JAVA_STRUCTURE_MODIFICATION_COUNT");
84 * A topic to subscribe for all PSI modification count changes.
85 * @see com.intellij.util.messages.MessageBus
87 Topic<Listener> TOPIC = new Topic<Listener>("modification tracker", Listener.class, Topic.BroadcastDirection.TO_PARENT);
90 * Tracks any PSI modification.
91 * @return current counter value. Increased whenever any physical PSI is changed.
94 long getModificationCount();
97 * @return Same as {@link #getJavaStructureModificationCount()}, but also includes changes in non-Java files, e.g. XML. Rarely needed.
99 long getOutOfCodeBlockModificationCount();
102 * @return an object returning {@link #getOutOfCodeBlockModificationCount()}
105 ModificationTracker getOutOfCodeBlockModificationTracker();
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.
112 long getJavaStructureModificationCount();
115 * @return an object returning {@link #getJavaStructureModificationCount()}
118 ModificationTracker getJavaStructureModificationTracker();
121 * A listener to be notified on any PSI modification count change (which happens on any physical PSI change).
127 * A method invoked on Swing EventDispatchThread each time any physical PSI change is detected
129 void modificationCountChanged();