lang-api/src/com/intellij/psi/PsiReference.java

   1 /*
   2  * Copyright 2000-2009 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.util.TextRange;
  19 import com.intellij.util.IncorrectOperationException;
  20 import com.intellij.codeInsight.lookup.LookupElement;
  21 import org.jetbrains.annotations.NotNull;
  22 import org.jetbrains.annotations.Nullable;
  23
  24 /**
  25  * A reference to a PSI element. For example, the variable name used in an expression.
  26  * The "Go to Declaration" action can be used to go from a reference to the element it references.
  27  *
  28  * @see PsiElement#getReference()
  29  * @see PsiElement#getReferences()
  30  */
  31
  32 public interface PsiReference {
  33   /**
  34    * The empty array of PSI references which can be reused to avoid unnecessary allocations.
  35    */
  36   PsiReference[] EMPTY_ARRAY = new PsiReference[0];
  37
  38   /**
  39    * Returns the underlying (referencing) element of the reference.
  40    *
  41    * @return the underlying element of the reference.
  42    */
  43   PsiElement getElement();
  44
  45   /**
  46    * Returns the part of the underlying element which serves as a reference, or the complete
  47    * text range of the element if the entire element is a reference.
  48    *
  49    * @return Relative range in element
  50    */
  51   TextRange getRangeInElement();
  52
  53   /**
  54    * Returns the element which is the target of the reference.
  55    *
  56    * @return the target element, or null if it was not possible to resolve the reference to a valid target.
  57    */
  58   @Nullable PsiElement resolve();
  59
  60   /**
  61    * Returns the name of the reference target element which does not depend on import statements
  62    * and other context (for example, the full-qualified name of the class if the reference targets
  63    * a Java class).
  64    *
  65    * @return the canonical text of the reference.
  66    */
  67   String getCanonicalText();
  68
  69   /**
  70    * Called when the reference target element has been renamed, in order to change the reference
  71    * text according to the new name.
  72    *
  73    * @param newElementName the new name of the target element.
  74    * @return the new underlying element of the reference.
  75    * @throws IncorrectOperationException if the rename cannot be handled for some reason.
  76    */
  77   PsiElement handleElementRename(String newElementName) throws IncorrectOperationException;
  78
  79   /**
  80    * Changes the reference so that it starts to point to the specified element. This is called,
  81    * for example, by the "Create Class from New" quickfix, to bind the (invalid) reference on
  82    * which the quickfix was called to the newly created class.
  83    *
  84    * @param element the element which should become the target of the reference.
  85    * @return the new underlying element of the reference.
  86    * @throws IncorrectOperationException if the rebind cannot be handled for some reason.
  87    */
  88   PsiElement bindToElement(@NotNull PsiElement element) throws IncorrectOperationException;
  89
  90   /**
  91    * Checks if the reference targets the specified element.
  92    *
  93    * @param element the element to check target for.
  94    * @return true if the reference targets that element, false otherwise.
  95    */
  96   boolean isReferenceTo(PsiElement element);
  97
  98   /**
  99    * Returns the array of String, {@link PsiElement} and/or {@link LookupElement}
 100    * instances representing all identifiers that are visible at the location of the reference. The contents
 101    * of the returned array is used to build the lookup list for basic code completion. (The list
 102    * of visible identifiers may not be filtered by the completion prefix string - the
 103    * filtering is performed later by IDEA core.)
 104    *
 105    * @return the array of available identifiers.
 106    */
 107   Object[] getVariants();
 108
 109   /**
 110    * Returns false if the underlying element is guaranteed to be a reference, or true
 111    * if the underlying element is a possible reference which should not be reported as
 112    * an error if it fails to resolve. For example, a text in an XML file which looks
 113    * like a full-qualified Java class name is a soft reference.
 114    *
 115    * @return true if the reference is soft, false otherwise.
 116    */
 117   boolean isSoft();
 118 }