java/openapi/src/com/intellij/psi/PsiElementFinder.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.psi.search.GlobalSearchScope;
  19 import com.intellij.openapi.extensions.ExtensionPointName;
  20 import org.jetbrains.annotations.NotNull;
  21 import org.jetbrains.annotations.Nullable;
  22
  23 /**
  24  * Allows to extend the mechanism of locating classes and packages by full-qualified name.
  25  * Implementations of this interface need to be registered as extensions in order
  26  * to be picked up by {@link JavaPsiFacade}.
  27  */
  28 public abstract class PsiElementFinder {
  29   public static final ExtensionPointName<PsiElementFinder> EP_NAME = ExtensionPointName.create("com.intellij.java.elementFinder");
  30
  31   /**
  32    * Searches the specified scope within the project for a class with the specified full-qualified
  33    * name and returns one if it is found.
  34    *
  35    * @param qualifiedName the full-qualified name of the class to find.
  36    * @param scope the scope to search.
  37    * @return the PSI class, or null if no class with such name is found.
  38    * @see JavaPsiFacade#findClass(String, GlobalSearchScope)
  39    */
  40   @Nullable
  41   public abstract PsiClass findClass(@NotNull String qualifiedName, @NotNull GlobalSearchScope scope);
  42
  43   /**
  44    * Searches the specified scope within the project for classes with the specified full-qualified
  45    * name and returns all found classes.
  46    *
  47    * @param qualifiedName the full-qualified name of the class to find.
  48    * @param scope the scope to search.
  49    * @return the array of found classes, or an empty array if no classes are found.
  50    * @see JavaPsiFacade#findClasses(String, GlobalSearchScope)
  51    */
  52   @NotNull
  53   public abstract PsiClass[] findClasses(@NotNull String qualifiedName, @NotNull GlobalSearchScope scope);
  54
  55   /**
  56    * Searches the project for the package with the specified full-qualified name and returns one
  57    * if it is found.
  58    *
  59    * @param qualifiedName the full-qualified name of the package to find.
  60    * @return the PSI package, or null if no package with such name is found.
  61    * @see JavaPsiFacade#findPackage(String)
  62    */
  63   @Nullable
  64   public PsiPackage findPackage(@NotNull String qualifiedName) {
  65     return null;
  66   }
  67
  68   /**
  69    * Returns the list of subpackages of the specified package in the specified search scope.
  70    *
  71    * @param psiPackage the package to return the list of subpackages for.
  72    * @param scope the scope in which subpackages are searched.
  73    * @return the list of subpackages.
  74    * @see PsiPackage#getSubPackages(GlobalSearchScope)
  75    */
  76   @NotNull
  77   public PsiPackage[] getSubPackages(@NotNull PsiPackage psiPackage, @NotNull GlobalSearchScope scope) {
  78     return new PsiPackage[0];
  79   }
  80
  81   /**
  82    * Returns the list of classes in the specified package and in the specified search scope.
  83    *
  84    * @param psiPackage the package to return the list of classes in.
  85    * @param scope the scope in which classes are searched.
  86    * @return the list of classes.
  87    * @see PsiPackage#getClasses(GlobalSearchScope)
  88    */
  89   @NotNull
  90   public PsiClass[] getClasses(@NotNull PsiPackage psiPackage, @NotNull GlobalSearchScope scope) {
  91     return PsiClass.EMPTY_ARRAY;
  92   }
  93 }