Difference between revisions of "DLTK Search Architecture"

Latest revision as of 15:35, 8 May 2013

Let's start with a few words about how DLTK search operates:

DLTK is separated into two phases:

Indexing

In this phase, the IDE will fill the disk index with all searchable items. The default implementation fills the index using structure parser results.

First, we need to be sure all items are added to the index by checking calls to IElementRequestor or ISourceElementRequestor classes from ISourceElementParser.

Methods enterField, enterMethod, enterType and appropriate "exit*" methods should be called for declaration items IFieldDeclaration, IMethodDeclaration and ITypeDeclaration implementations, respectively. Be sure to call the appropriate exit methods for structure to be correct. Methods acceptMethodReference, acceptTypeReference and acceptFieldReference should be called for references.

We can check indexing results from JUnit. To query index, the following code could be used:

import org.eclipse.dltk.core.search.indexing.*;
import org.eclipse.dltk.core.*;
import org.eclipse.dltk.core.search.*;

IProject prj = ... ;
 
IndexManager im = ModelManager.getModelManager().getIndexManager();
Index idx = im.getIndex(prj.getFullPath()); // This is the index file for project root
// And then check using
idx.queryDocumentNames(null);// To check all documents in this index
// or
char[][] category = {IIndexConstants.TYPE_DECL};
idx.query(category, new char[]{'*'}, SearchPattern.R_PATTERN_MATCH);

Before going deep. we need to check indexes produced by your parser are correct.

Search. Find matches -> Provide search results.

There is two ways to implement search. First is to use DLTK default implementation if you are using DLTK AST, it would be OK if your model fit well to:

• Module
  • Type
    
    • SubType
      
      • Method
        
      • Field
        
    • Method
      
    • Field

And second is to provide custom IMatchLocator based implementation.

So begin search:

Search for matches
On every search DLTK will query index for all possible matches and then use only required ones.
a) Using standard MatchLocator

1. Collect possible matches by using IMatchLocatorParser parser interface to process ModuleDeclaration into match'et nodes. Please look into org.eclipse.dltk.core.search.matching.MatchLocatorParser.parseBodies(ModuleDeclaration) method. It uses visitor pattern to visit ModuleDeclaration. From visitor it calls for org.eclipse.dltk.core.search.matching.PatternLocator.match(*) methods to match AST node. Please refer to FieldLocator, MethodLocator, TypeDeclarationLocator classes for appropriate match methods (not all methods are implemented).
   
   After matches are collected we use structure to match some of them to model elements, for easy navigation.
   
2. Associate matched node to structure model items. To work correctly following methods should return correct results: ModuleDeclaration: - getTypes() - list of top level types in module - getFunctions() - list of methods in module - getVariables() - list of variables in module And TypeDeclaration - getTypes() - list of subtypes - getMethods() - list of methods - getVariables() - list of variables By default this methods are using ASTUtil.getTypes(), ASTUtil.getMethods(), ASTUtil.getVariables() methods. So if your ModuleDeclaration hold custom items you need to override provided methods to match nodes to correct structure model items.

b) Using custom IMatchLocator
     Provide your results into org.eclipse.dltk.core.search.SearchRequestor.acceptSearchMatch(*) method from your IMatchLocator.locateMatches() method.