Votre plug-in peut utiliser l'API du JDT pour rechercher des éléments Java dans les projets Java de l'espace de travail, tels que des références de méthodes, des déclarations de zones, des implémenteurs d'interface, etc.
Le point d'entrée de la recherche Java est la classe SearchEngine. Vous pouvez rechercher des masques particuliers dans un élément Java et faire porter la recherche sur des éléments spécifiques. les masques de recherche peuvent être créés à l'aide de createSearchPattern. La portée d'un masque est définie à l'aide de createJavaSearchScope.Une fois le masque et la portée définis, la méthode de recherche est utilisée pour collecter les résultats.
Les résultats de la recherche sont signalés à un IJavaSearchResultCollector que vous devez implémenter pour accéder aux résultats.
Une opération de recherche utilise à la fois un modèle décrivant la nature de la recherche et une portée permettant de restreindre l'étendue de l'interrogation.
Un modèle de recherche définit la façon dont les résultats de la recherche sont trouvés. Vous pouvez créer un modèle de recherche à partir d'un élément Java (voir createSearchPattern(IJavaElement, int)) ou à partir d'une chaîne (voir createSearchPattern(String, int, int, boolean).) La dernière méthode prend en charge les caractères génériques (comme *) et peut être utilisée pour étendre les résultats de la recherche.
Vous trouverez ci-dessous un exemple de modèle de recherche de références à une méthode donnée.
// Obtention de la méthode IMethod method = ...; // Création du modèle de recherche ISearchPattern pattern = SearchEngine.createSearchPattern(method, IJavaSearchConstants.REFERENCES);
ou de création d'un modèle de recherche de déclarations de tous les types commençant par "Obj" :
// Création du modèle de recherche ISearchPattern pattern = SearchEngine.createSearchPattern("Obj*", IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, true);
Les modèles de recherche suivants sont pris en charge :
Si vous êtes intéressés par les résultats de la recherche d'un projet donné, voire d'un package donné, ou si vous savez que les résultats ne peuvent se trouver que dans la hiérarchie d'un type donné, vous pouvez créer la portée de la recherche appropriée à l'aide de createJavaSearchScope(IJavaElement[]) ou de createHierarchyScope(IType).
Vous trouverez ci-dessous un exemple de création de portée de recherche sur un package donné.
// Obtention du package IPackageFragment pkg = ...; // Création de la portée de recherche IJavaSearchScope scope = SearchEngine.createJavaSearchScope(new IJavaElement[] {pkg});
ou de création de la portée de recherche sur la hiérarchie d'un type donné :
// Obtention du type IType type = ...; // Création de la portée de recherche IJavaSearchScope scope = SearchEngine.createHierarchyScope(type);
Enfin, vous pouvez créer une portée de recherche pour l'espace de travail entier :
// Création de la portée de recherche IJavaSearchScope scope = SearchEngine.createWorkspaceScope();
Une fois que vous avez créé un modèle et une portée de recherche et que vous avez implémenté IJavaSearchResultCollector, vous pouvez lancer une recherche de la façon suivante :
// Obtention du modèle de recherche ISearchPattern pattern = ...; // Obtention de la portée de recherche IJavaSearchScope scope = ...; // Obtention du collecteur des résultats de la recherche IJavaSearchResultCollector collector = ...; // Recherche SearchEngine searchEngine = new SearchEngine(); searchEngine.search(ResourcesPlugin.getWorkspace(), pattern, scope, collector);
Une notification indiquant que la recherche est lancée est envoyée à votre collecteur de résultats de la recherche à l'aide de la méthode aboutToStart. Ensuite, chaque résultat de la recherche est signalé à l'aide de la méthode accept. Enfin, done indique que la recherche est terminée.
Les résultats de la recherche sont signalés à l'aide de la méthode accept. Les paragraphes ci-après détaillent chaque argument de la méthode.
Un résultat de recherche peut correspondre à un élément Java (comme une déclaration de type) ou peut se trouver dans un élément Java (comme une référence à un type dans une méthode). Le moteur de recherche tente toujours de trouver l'élément Java le plus central correspondant au résultat de la recherche ou le contenant. Par exemple, la recherche de déclarations de types par nom peut permettre de trouver une déclaration de type local. Etant donné que le modèle Java ne représente pas les types locaux, la méthode contenant cette déclaration de type local est signalée au collecteur de résultats.
Le moteur de recherche tente également de signaler la ressource contenant l'élément Java au collecteur de résultats. Ainsi, si l'élément Java est une méthode dans une unité de compilation, la ressource est l'élément IFile correspondant. Si l'élément se situe dans un fichier .jar, la ressource est le fichier .jar si ce dernier se trouve dans l'espace de travail. S'il s'agit d'un fichier .jar externe, la ressource est nulle.
Les emplacements source sont indiqués par rapport à l'unité de compilation contenant le résultat de la recherche. Si le résultat de la recherche se trouve dans un fichier .jar, les emplacements des éléments source sont relatifs à la source connectée. Le résultat est (-1, -1) si aucune source n'est liée au fichier .jar.
Dans la plupart des cas, les résultats de la recherche sont précis, ce qui signifie que le moteur de recherche a pu déterminer que l'occurrence en question était l'élément souhaité. Toutefois, il arrive qu'il échoue et l'occurrence est imprécise. Il se peut qu'une occurrence soit imprécise pour les raisons ci-dessous.