A reference in a PSI tree is an object that represents a link from a usage of a particular element in the code to the corresponding declaration. Resolving a reference means locating the declaration to which a specific usage refers.
The most common type of reference is defined by language semantics. For example, consider a simple Java method:
This simple code fragment contains five references. The references created by the identifiers
println can be resolved to the corresponding declarations in the JDK: the
System classes, the
out field, and the
println method. The reference created by the second occurrence of the
message identifier in
println(message) can be resolved to the
message parameter, declared by
String message in the method header.
String message is not a reference and cannot be resolved. Instead, it's a declaration. It does not refer to any name defined elsewhere; instead, it defines a name by itself.
A reference is an instance of a class implementing the
PsiReference interface. Note that references are distinct from PSI elements. References created by a PSI element are returned from
PsiElement.getReferences(), the underlying PSI element of a reference can be obtained from
To resolve the reference - to locate the declaration being referenced - call
PsiReference.resolve(). It's very important to understand the difference between
PsiReference.resolve(). The former method returns the source of a reference, while the latter returns its target. In the example above, for the
getElement() will return the
message identifier on the second line of the snippet, and
resolve() will return the
message identifier on the first line (inside the parameter list).
The process of resolving references is distinct from parsing and is not performed at the same time. Moreover, it is not always successful. If the code currently open in the IDE does not compile, or in other situations, it's normal for
PsiReference.resolve() to return
null - all code working with references must be prepared to handle that.
In addition to references defined by the semantics of the programming language, the IDE recognizes many references determined by the semantics of the APIs and frameworks used in code. Consider the following example:
Here, "foo.txt" has no special meaning from the point of view of the Java syntax - it's just a string literal. However, opening this example in IntelliJ IDEA and having a file called "foo.txt" in the same directory, one can Ctrl/Cmd+Click on "foo.txt" and navigate to the file. This works because the IDE recognizes the semantics of
new File(...) and contributes a reference into the string literal passed as a parameter to the method.
Typically, references can be contributed to elements that don't have their own references, such as string literals and comments. References are also often contributed to non-code files, such as XML or JSON.
Contributing references is one of the most common ways to extend an existing language. For example, your plugin can contribute references to Java code, even though the Java PSI is part of the platform and not defined in your plugin.
PsiReferenceContributor registered in extension point
com.intellij.psi.referenceContributor. The places to contribute references to are then specified using Element Patterns in calls to
See also Reference Contributor tutorial.
References with Optional or Multiple Resolve Results
In the simplest case, a reference resolves to a single element, and if resolving fails, the code is incorrect, and the IDE needs to highlight it as an error. However, there are cases when the situation is different.
The first case is soft references. Consider the
new File("foo.txt") example above. If the IDE can't find the file "foo.txt", it doesn't mean that an error needs to be highlighted - maybe the file is only available at runtime. Such references return
true from the
For resolving a
PsiPolyVariantReference, you call its
multiResolve() method. The call returns an array of
ResolveResult objects. Each of the objects identifies a PSI element and also specifies whether the result is valid. For example, suppose you have multiple Java method overloads and a call with arguments not matching any of the overloads. In that case, you will get back
ResolveResult objects for all of the overloads, and
false for all of them.
Searching for References
As you already know, resolving a reference means going from usage to the corresponding declaration. To perform the navigation in the opposite direction - from a declaration to its usages - perform a references search.
To perform a search using
ReferencesSearch, specify the element to search for, and optionally other parameters such as the scope in which the reference needs to be searched. The created
Query allows obtaining all results at once or iterating over the results one by one. The latter allows stopping processing as soon as the first (matching) result has been found.