Utilizar o motor de procura Java

O plug-in pode utilizar a API JDT para pesquisar em projectos Java na área de trabalho elementos Java, como referências de métodos, declarações de campos, implementadores de uma interface, etc.

O ponto de entrada para a pesquisa Java é a classe SearchEngine. Pode pesquisar padrões específicos dentro de um elemento Java limitar o âmbito da pesquisa a determinados elementos.   Os padrões de pesquisa podem ser criados com createPattern.  Pode definir o âmbito de um padrão com createJavaSearchScope.  Quando o padrão e o âmbito estão definidos, o método search é utilizado para recolher os resultados.

Os resultados da pesquisa são relatados a um SearchRequestor que terá de ser expandido para que possa aceder aos resultados.

Preparar uma pesquisa

Uma operação de pesquisa utiliza um padrão para descrever a natureza da pesquisa e um âmbito para limitar o intervalo de investigação.

Criar um padrão de pesquisa Java

O padrão de pesquisa define a forma como os resultados da pesquisa são encontrados. Pode criar um padrão de pesquisa a partir de um elemento Java ( consulte createPatternPattern(IJavaElement, int)) ou de uma cadeia (consulte createPattern(String, int, int, int).) Este último método suporta caracteres globais (ou seja, '*') e pode ser utilizado para alargar os resultados da pesquisa.

Por exemplo, a criação de um padrão de pesquisa para procurar referências a um determinado método é efectuada da seguinte forma:

    // Obter um método
    IMethod method = ...;
    
    // Criar um padrão de pesquisa
    SearchPattern pattern = SearchPattern.createPattern(method, IJavaSearchConstants.REFERENCES);

Ou criar um padrão de pesquisa para procurar declarações de todos os tipos que começar por "Obj":

    // Criar um padrão de pesquisa
    SearchPattern pattern = SearchPattern.createPattern("Obj*", IJavaSearchConstants.TYPE, IJavaSearchConstants.DECLARATIONS, SearchPattern.R_PATTERN_MATCH | SearchPattern.R_CASE_SENSITIVE);

São suportados os seguintes padrões de pesquisa

Criar um âmbito de pesquisa Java

Se o utilizador está interessado em obter resultados de pesquisas num dado projecto ou até num dado pacote, ou se tem conhecimento de que os resultados de pesquisas só podem ser encontrados na hierarquia de um determinado tipo, pode criar o âmbito de pesquisa adequado, utilizando createJavaSearchScope(IJavaElement[]) ou createHierarchyScope(IType).

Por exemplo, a criação de um padrão de pesquisa para procurar o âmbito de um determinado pacote é efectuada da seguinte forma:

    // Obter o pacote
    IPackageFragment pkg = ...;

    // Criar um âmbito de pesquisa
    IJavaSearchScope scope = SearchEngine.createJavaSearchScope(new IJavaElement[] {pkg});

Ou criar um âmbito de pesquisa na hierarquia de um determinado tipo é:

    // Obter um tipo
    IType type = ...;

    // Criar um âmbito de pesquisa
    IJavaSearchScope scope = SearchEngine.createHierarchyScope(type);

Finalmente, pode criar um âmbito de pesquisa que compreenda todo o espaço de trabalho, utilizando createWorkspaceScope:

    // Criar um âmbito de pesquisa
    IJavaSearchScope scope = SearchEngine.createWorkspaceScope();

Pesquisar

Depois de ter criado um padrão de pesquisa e um âmbito de pesquisa e de ter expandido o SearchRequestor, pode começar a consulta da pesquisa da seguinte forma:

    // Obter um padrão de pesquisa
    SearchPattern pattern = ...;

    // Obter um âmbito de pesquisa
    IJavaSearchScope scope = ...;

    // Obter um solicitador de pesquisa
    SearchRequestor requestor = ...;

    // Pesquisar
    SearchEngine searchEngine = new SearchEngine();
    searchEngine.search(pattern, new SearchParticipant[] {SearchEngine.getDefaultSearchParticipant()}, scope, requestor, null);

É enviada uma notificação de início de pesquisa para o solicitador de pesquisa com o método beginReporting.  Depois, cada resultado de pesquisa é relatado com o método acceptSearchMatch. Finalmente, o endReporting indica que a pesquisa terminou.

Recolher resultados de pesquisa

Os resultados da pesquisa são comunicados utilizando o método acceptSearchMatch(SearchMatch). Os parágrafos apresentados em baixo destacam algumas das funções do SearchMatch.

Recursos e elementos Java

O resultado de pesquisa pode corresponder a um elemento Java (por exemplo, uma declaração de tipo) ou pode conter um elemento Java (por exemplo, uma referência a um tipo dentro de um método). O motor de pesquisa tenta sempre encontrar o elemento Java mais interno que corresponde ou que contém o resultado de pesquisa. Por exemplo, a pesquisa de referências a um método pode encontra tal referência num operador de inicialização. O operador de inicialização que contém a referência a este método é o elemento da correspondência de pesquisa.

O motor de pesquisa também tenta encontrar o recurso que contém o elemento Java. Se o elemento Java estiver contido numa unidade de compilação ou ficheiro de classe, o recurso é o IFile correspondente. Se o elemento Java estiver contido num .ficheiro jar, o recurso devolvido corresponde a esse .ficheiro jar, caso esteja no espaço de trabalho, caso contrário, é nulo otherwise.

Posições de fonte

As posições de origem getOffset e getLength dependem da unidade de compilação que contém o resultado de pesquisa.Se um resultado de pesquisa estiver contido num ficheiro .jar, as posições de fonte dependem da fonte a que estão ligadas. São (-1, -1) se não houver fonte ligada ao ficheiro .jar.

Resultados de pesquisa precisos ou imprecisos

Na maioria dos casos, os resultados de pesquisa são precisos, o que significa que o motor de pesquisa pode determinar a correspondência que lhe foi pedida. No entanto, por vezes o motor de pesquisa não consegue fazê-lo, e nesse caso a correspondência é imprecisa. Razões possíveis para a correspondência ser imprecisa: