Package com.intellij.extapi.psi

Class StubBasedPsiElementBase<T extends StubElement>

java.lang.Object

com.intellij.openapi.util.UserDataHolderBase

com.intellij.psi.impl.ElementBase

com.intellij.psi.impl.PsiElementBase

com.intellij.extapi.psi.ASTDelegatePsiElement

com.intellij.extapi.psi.StubBasedPsiElementBase<T>

All Implemented Interfaces:

NavigationItem, Iconable, UserDataHolder, UserDataHolderEx, Navigatable, NavigatablePsiElement, PsiElement, java.lang.Cloneable

Direct Known Subclasses:

GrStubElementBase, JavaStubPsiElement, MarkdownStubBasedPsiElementBase, PropertiesStubElementImpl, PyBaseElementImpl, PyDecoratorImpl, XmlStubBasedAttributeBase, XmlStubBasedTagBase

public class StubBasedPsiElementBase<T extends StubElement>
extends ASTDelegatePsiElement

A base class for PSI elements that support both stub and AST substrates. The purpose of stubs is to hold the most important information (like element names, access modifiers, function parameters etc), save it in the index and use it during code analysis instead of parsing the AST, which can be quite expensive. Ideally, only the files loaded in the editor should ever be parsed, all other information that's needed e.g. for resolving references in those files, should be taken from stub-based PSI.

During indexing, this element is created from text (using StubBasedPsiElementBase(ASTNode)), then a stub with relevant information is built from it (IStubElementType.createStub(PsiElement, StubElement)), and this stub is saved in the index. Then a StubIndex query returns an instance of this element based on a stub (created with StubBasedPsiElementBase(StubElement, IStubElementType) constructor. To the clients, such element looks exactly like the one created from AST, all the methods should work the same way.

Code analysis clients should be careful not to invoke methods on this class that can't be implemented using only the information from stubs. Such case is supported: getNode() will switch the implementation from stub to AST substrate and get this information, but this is slow performance-wise. So stubs should be designed so that they hold all the information that's relevant for reference resolution and other code analysis.

The subclasses should be careful not to switch to AST prematurely. For example, getParentByStub() should be used as much as possible in overridden getParent(), and getStubOrPsiChildren methods should be preferred over ASTDelegatePsiElement.getChildren().

After switching to AST, getStub() will return null, but getGreenStub() can still be used to retrieve stub objects if they're needed. The AST itself is not held on a strong reference and can be garbage-collected. This makes it possible to hold many stub-based PSI elements in the memory at once, but results in occasionally expensive getNode() calls that have to load and parse the AST anew.

See Also:

IStubElementType, PsiFileWithStubSupport

Nested Class Summary

Nested classes/interfaces inherited from interface com.intellij.openapi.util.Iconable

Iconable.IconFlags, Iconable.LastComputedIcon

Field Summary

Fields

Modifier and Type	Field and Description
static Key<java.lang.String>	CREATION_TRACE
static boolean	ourTraceStubAstBinding

Fields inherited from class com.intellij.psi.impl.ElementBase

FLAGS_LOCKED, ICON_PLACEHOLDER

Fields inherited from interface com.intellij.psi.NavigatablePsiElement

EMPTY_NAVIGATABLE_ELEMENT_ARRAY

Fields inherited from interface com.intellij.psi.PsiElement

ARRAY_FACTORY, EMPTY_ARRAY

Fields inherited from interface com.intellij.openapi.util.Iconable

ICON_FLAG_IGNORE_MASK, ICON_FLAG_OPEN, ICON_FLAG_READ_STATUS, ICON_FLAG_VISIBILITY

Fields inherited from interface com.intellij.navigation.NavigationItem

EMPTY_NAVIGATION_ITEM_ARRAY

Constructor Summary

Constructors

Constructor and Description
StubBasedPsiElementBase(ASTNode node)
StubBasedPsiElementBase(T stub, IElementType nodeType, ASTNode node) This constructor is created to allow inheriting from this class in JVM languages which doesn't support multiple constructors (e.g.
StubBasedPsiElementBase(T stub, IStubElementType nodeType)

Method Summary

Modifier and Type	Method and Description
protected java.lang.Object	clone()
PsiFile	getContainingFile() Returns the file containing the PSI element.
PsiElement	getContext() Returns the element which should be used as the parent of this element in a tree up walk during a resolve operation.
IStubElementType	getElementType()
T	getGreenStub() Like getStub(), but can return a non-null value after the element has been switched to AST.
Language	getLanguage() Returns the language of the PSI element.
PsiManagerEx	getManager() Returns the PSI manager for the project to which the PSI element belongs.
ASTNode	getNode() Ensures this element is AST-based.
PsiElement	getParent() Returns the parent of the PSI element.
protected PsiElement	getParentByStub() Please consider using getParent() instead, because this method can return different results before and after AST is loaded.
protected PsiElement	getParentByTree() Deprecated. use getParent() instead
Project	getProject() Returns the project to which the PSI element belongs.
<S extends StubElement,Psi extends PsiElement> Psi	getRequiredStubOrPsiChild(IStubElementType<S,Psi> elementType)
T	getStub() Note: for most clients (where the logic doesn't crucially differ for stub and AST cases), getGreenStub() should be preferred.
<Psi extends PsiElement> Psi	getStubOrPsiChild(IStubElementType<? extends StubElement,Psi> elementType)
<S extends StubElement,Psi extends PsiElement> Psi []	getStubOrPsiChildren(IStubElementType<S,? extends Psi> elementType, ArrayFactory<? extends Psi> f)
<S extends StubElement,Psi extends PsiElement> Psi []	getStubOrPsiChildren(IStubElementType<S,? extends Psi> elementType, Psi [] array)
<Psi extends PsiElement> Psi []	getStubOrPsiChildren(TokenSet filter, ArrayFactory<? extends Psi> f)
<Psi extends PsiElement> Psi []	getStubOrPsiChildren(TokenSet filter, Psi [] array)
protected <E extends PsiElement> E	getStubOrPsiParentOfType(java.lang.Class<E> parentClass)
boolean	isPhysical() Checks if an actual source or class file corresponds to the element.
boolean	isValid() Checks if this PSI element is valid.
boolean	isWritable() Checks if the contents of the element can be modified (if it belongs to a non-read-only source file.)
void	setNode(ASTNode node) Don't invoke this method, it's public for implementation reasons.
void	setSubstrateRef(SubstrateRef substrateRef) Don't invoke this method, it's public for implementation reasons.

Methods inherited from class com.intellij.extapi.psi.ASTDelegatePsiElement

add, addAfter, addBefore, addInternal, addRange, addRangeAfter, addRangeBefore, checkAdd, checkDelete, copy, delete, deleteChildInternal, deleteChildRange, findChildByFilter, findChildByType, findChildByType, findChildrenByType, findChildrenByType, findChildrenByType, findChildrenByType, findElementAt, findLastChildByType, findNotNullChildByType, findNotNullChildByType, getChildren, getCopyableUserData, getFirstChild, getLastChild, getNextSibling, getPrevSibling, getStartOffsetInParent, getText, getTextLength, getTextOffset, getTextRange, putCopyableUserData, replace, replaceChildInternal, subtreeChanged, textContains, textMatches, textToCharArray

Methods inherited from class com.intellij.psi.impl.PsiElementBase

accept, acceptChildren, canNavigate, canNavigateToSource, findChildByClass, findChildrenByClass, findNotNullChildByClass, findReferenceAt, getName, getNavigationElement, getOriginalElement, getPresentation, getReference, getReferences, getResolveScope, getUseScope, isEquivalentTo, navigate, notNullChild, processDeclarations, textMatches

Methods inherited from class com.intellij.psi.impl.ElementBase

buildRowIcon, computeBaseIcon, createLayeredIcon, getAdjustedBaseIcon, getBaseIcon, getElementIcon, getIcon, iconWithVisibilityIfNeeded, isNativeFileType, isVisibilitySupported, overlayIcons, registerIconLayer, transformFlags

Methods inherited from class com.intellij.openapi.util.UserDataHolderBase

changeUserMap, clearUserData, copyCopyableDataTo, copyUserDataTo, getUserData, getUserDataString, getUserMap, isUserDataEmpty, putUserData, putUserDataIfAbsent, replace, setUserMap

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.intellij.psi.PsiElement

getOwnReferences, getTextRangeInParent, toString

Methods inherited from interface com.intellij.openapi.util.UserDataHolder

getUserData, putUserData

Methods inherited from interface com.intellij.openapi.util.Iconable

getIcon

Field Detail

CREATION_TRACE

public static final Key<java.lang.String> CREATION_TRACE

ourTraceStubAstBinding

public static final boolean ourTraceStubAstBinding

Constructor Detail

StubBasedPsiElementBase

public StubBasedPsiElementBase(T stub,
                               IStubElementType nodeType)

StubBasedPsiElementBase

public StubBasedPsiElementBase(ASTNode node)

StubBasedPsiElementBase

public StubBasedPsiElementBase(T stub,
                               IElementType nodeType,
                               ASTNode node)

This constructor is created to allow inheriting from this class in JVM languages which doesn't support multiple constructors (e.g. Scala). If your language does support multiple constructors use StubBasedPsiElementBase(StubElement, IStubElementType) and StubBasedPsiElementBase(ASTNode) instead.

Method Detail

getNode

public ASTNode getNode()

Ensures this element is AST-based. This is an expensive operation that might take significant time and allocate lots of objects, so it should be to be avoided if possible.

Specified by:

getNode in interface PsiElement

Specified by:

getNode in class ASTDelegatePsiElement

Returns:

an AST node corresponding to this element. If the element is currently operating via stubs, this causes AST to be loaded for the whole file and all stub-based PSI elements in this file (including the current one) to be switched from stub to AST. So, after this call getStub() will return null.

setNode

public final void setNode(ASTNode node)

Don't invoke this method, it's public for implementation reasons.

setSubstrateRef

public final void setSubstrateRef(SubstrateRef substrateRef)

Don't invoke this method, it's public for implementation reasons.

getLanguage

public Language getLanguage()

Description copied from interface: PsiElement

Returns the language of the PSI element.

Specified by:

getLanguage in interface PsiElement

Overrides:

getLanguage in class ASTDelegatePsiElement

Returns:

the language instance.

getContainingFile

public PsiFile getContainingFile()

Description copied from interface: PsiElement

Returns the file containing the PSI element.

Note: this method might need to traverse the whole AST up, which can be slow in deep trees, so invoking this method should be avoided if possible.

Specified by:

getContainingFile in interface PsiElement

Overrides:

getContainingFile in class ASTDelegatePsiElement

Returns:

the file instance, or null if the PSI element is not contained in a file (for example, the element represents a package or directory).

isWritable

public boolean isWritable()

Description copied from interface: PsiElement

Checks if the contents of the element can be modified (if it belongs to a non-read-only source file.)

Specified by:

isWritable in interface PsiElement

Overrides:

isWritable in class PsiElementBase

Returns:

true if the element can be modified, false otherwise.

isValid

public boolean isValid()

Description copied from interface: PsiElement

Checks if this PSI element is valid. Valid elements and their hierarchy members can be accessed for reading and writing. Valid elements can still correspond to underlying documents whose text is different, when those documents have been changed and not yet committed (PsiDocumentManager.commitDocument(com.intellij.openapi.editor.Document)). (In this case an attempt to change PSI will result in an exception). Any access to invalid elements results in PsiInvalidElementAccessException. Once invalid, elements can't become valid again. Elements become invalid in following cases:

• They have been deleted via PSI operation (PsiElement.delete())
• They have been deleted as a result of an incremental reparse (document commit)
• Their containing file has been changed externally, or renamed so that its PSI had to be rebuilt from scratch

Specified by:

isValid in interface PsiElement

Overrides:

isValid in class PsiElementBase

Returns:

true if the element is valid, false otherwise.

See Also:

PsiUtilCore.ensureValid(PsiElement)

getManager

public PsiManagerEx getManager()

Description copied from interface: PsiElement

Returns the PSI manager for the project to which the PSI element belongs.

Specified by:

getManager in interface PsiElement

Overrides:

getManager in class ASTDelegatePsiElement

Returns:

the PSI manager instance.

getProject

public Project getProject()

Description copied from interface: PsiElement

Returns the project to which the PSI element belongs.

Specified by:

getProject in interface PsiElement

Overrides:

getProject in class PsiElementBase

Returns:

the project instance.

isPhysical

public boolean isPhysical()

Description copied from interface: PsiElement

Checks if an actual source or class file corresponds to the element. Non-physical elements include, for example, PSI elements created for the watch expressions in the debugger. Non-physical elements do not generate tree change events. Also, PsiDocumentManager.getDocument(PsiFile) returns null for non-physical elements. Not to be confused with FileViewProvider.isPhysical().

Specified by:

isPhysical in interface PsiElement

Overrides:

isPhysical in class PsiElementBase

Returns:

true if the element is physical, false otherwise.

getContext

public PsiElement getContext()

Description copied from interface: PsiElement

Returns the element which should be used as the parent of this element in a tree up walk during a resolve operation. For most elements, this returns getParent(), but the context can be overridden for some elements like code fragments (see JavaCodeFragmentFactory.createCodeBlockCodeFragment(String, PsiElement, boolean)).

Specified by:

getContext in interface PsiElement

Overrides:

getContext in class PsiElementBase

Returns:

the resolve context element.

getParentByStub

protected final PsiElement getParentByStub()

Please consider using getParent() instead, because this method can return different results before and after AST is loaded.

Returns:

a PSI element taken from parent stub (if present) or parent AST node.

getParentByTree

@Deprecated
protected final PsiElement getParentByTree()

Deprecated. use getParent() instead

getParent

public PsiElement getParent()

Description copied from interface: PsiElement

Returns the parent of the PSI element.

Returns:

the parent of this element. Uses stub hierarchy if possible, but might cause an expensive switch to AST if the parent stub doesn't correspond to the parent AST node.

getElementType

public IStubElementType getElementType()

getStub

public T getStub()

Note: for most clients (where the logic doesn't crucially differ for stub and AST cases), getGreenStub() should be preferred.

Returns:

the stub that this element is built upon, or null if the element is currently AST-based. The latter can happen if the file text was loaded from the very beginning, or if it was loaded via getNode() on this or any other element in the containing file.

getGreenStub

public final T getGreenStub()

Like getStub(), but can return a non-null value after the element has been switched to AST. Can be used to retrieve the information which is cheaper to get from a stub than by tree traversal.

See Also:

PsiFileImpl#getGreenStub()

getStubOrPsiChild

public <Psi extends PsiElement> Psi getStubOrPsiChild(IStubElementType<? extends StubElement,Psi> elementType)

Returns:

a child of specified type, taken from stubs (if this element is currently stub-based) or AST (otherwise).

getRequiredStubOrPsiChild

public <S extends StubElement,Psi extends PsiElement> Psi getRequiredStubOrPsiChild(IStubElementType<S,Psi> elementType)

Returns:

a not-null child of specified type, taken from stubs (if this element is currently stub-based) or AST (otherwise).

getStubOrPsiChildren

public <S extends StubElement,Psi extends PsiElement> Psi [] getStubOrPsiChildren(IStubElementType<S,? extends Psi> elementType,
                                                                                  Psi [] array)

Returns:

children of specified type, taken from stubs (if this element is currently stub-based) or AST (otherwise).

getStubOrPsiChildren

public <S extends StubElement,Psi extends PsiElement> Psi [] getStubOrPsiChildren(IStubElementType<S,? extends Psi> elementType,
                                                                                  ArrayFactory<? extends Psi> f)

Returns:

children of specified type, taken from stubs (if this element is currently stub-based) or AST (otherwise).

getStubOrPsiChildren

public <Psi extends PsiElement> Psi [] getStubOrPsiChildren(TokenSet filter,
                                                            Psi [] array)

Returns:

children of specified type, taken from stubs (if this element is currently stub-based) or AST (otherwise).

getStubOrPsiChildren

public <Psi extends PsiElement> Psi [] getStubOrPsiChildren(TokenSet filter,
                                                            ArrayFactory<? extends Psi> f)

Returns:

children of specified type, taken from stubs (if this element is currently stub-based) or AST (otherwise).

getStubOrPsiParentOfType

protected <E extends PsiElement> E getStubOrPsiParentOfType(java.lang.Class<E> parentClass)

Returns:

a first ancestor of specified type, in stub hierarchy (if this element is currently stub-based) or AST hierarchy (otherwise).

clone

protected java.lang.Object clone()

Overrides:

clone in class UserDataHolderBase