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.Vous pouvez créer des masques de recherche à l'aide de createPattern.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 search permet de collecter les résultats.
Les résultats de la recherche sont signalés à un SearchRequestor que vous devez étendre 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 masque de recherche à partir d'un élément Java (voir createPatternPattern(IJavaElement, int)) ou à partir d'une chaîne (voir createPattern(String, int, int, int)). 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 SearchPattern pattern = SearchPattern.createPattern(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 SearchPattern pattern = SearchPattern.createPattern("Obj*", IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, SearchPattern.R_PATTERN_MATCH | SearchPattern.R_CASE_SENSITIVE);
Les modèles de recherche suivants sont pris en charge :
Si vous êtes intéressé 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 masque et une portée de recherche et que vous avez étendu SearchRequestor, vous pouvez démarrer une recherche de la manière suivante :
// Obtention du modèle de recherche SearchPattern pattern = ...; // Obtention de la portée de recherche IJavaSearchScope scope = ...; // Obtention du demandeur de recherche SearchRequestor requestor = ...; // Recherche SearchEngine searchEngine = new SearchEngine(); searchEngine.search(pattern, new SearchParticipant[] {SearchEngine.getDefaultSearchParticipant()}, scope, requestor, null);
Une notification indiquant que la recherche est lancée est envoyée à votre demandeur de recherche à l'aide de la méthode beginReporting. Ensuite, chaque résultat de la recherche est signalé à l'aide de la méthode acceptSearchMatch. Enfin, endReporting indique que la recherche est terminée.
Les résultats de la recherche sont signalés à l'aide de la méthode acceptSearchMatch. Les paragraphes ci-après détaillent les résultats de la recherche.
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 références à une méthode peut trouver une telle référence dans un initialiseur. L'initialiseur qui contient la référence de méthode est l'élément du résultat de la recherche.
Le moteur de recherche tente également de trouver la ressource qui contient l'élément Java. 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.