Utilisation du moteur de recherche Java

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.

Préparation de la recherche

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.

Création d'un modèle de recherche Java

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 :

Création d'une portée de recherche Java

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();

Recherche

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.

Collection des résultats de la recherche

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.

Ressources et éléments Java

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.

Emplacement des éléments source

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.

Résultats de recherche précis et imprécis

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.

Copyright IBM Corporation and others 2000, 2003. All Rights Reserved.