org.eclipse.cdt.core.index

Interface IIndex

public interface IIndex

Interface for accessing the index for one or more projects.

Since:

4.0

Restriction:

This interface is not intended to be implemented by clients.

Restriction:

This interface is not intended to be extended by clients.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEPTH_INFINITE Constant to specify infinite depth.
static int	DEPTH_ZERO Constant to find direct includes, only.
static int	FIND_ALL_OCCURRENCES Constant to search for all occurrences of a binding.
static int	FIND_DECLARATIONS Constant to search for declarations.
static int	FIND_DECLARATIONS_DEFINITIONS Constant to search for all declarations including definitions.
static int	FIND_DEFINITIONS Constant to search for definitions.
static int	FIND_POTENTIAL_MATCHES Constant to include potential matches in the results of a search.
static int	FIND_REFERENCES Constant to search for references.
static int	SEARCH_ACROSS_LANGUAGE_BOUNDARIES Constant to search for occurrences across language boundaries.

Method Summary

Modifier and Type	Method and Description
void	acquireReadLock() Before making calls to an index you have to obtain a lock.
IIndexBinding	adaptBinding(IBinding binding) Returns an IIndexBinding for this index that is equivalent to the specified binding, or null if such a binding does not exist in this index.
IIndexFileSet	createFileSet() Creates a file-set that can be used with this index as long as the caller holds a read-lock.
IIndexBinding	findBinding(IName name) Searches for the binding of a name.
IIndexBinding[]	findBindings(char[][] names, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) Searches for all bindings in global scope with a given name.
IIndexBinding[]	findBindings(char[] name, boolean fileScopeOnly, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) Searches the global scope and optionally all other scopes for bindings with a given name.
IIndexBinding[]	findBindings(char[] name, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) Searches the global scope for all bindings with a given name.
IIndexBinding[]	findBindings(Pattern[] patterns, boolean isFullyQualified, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) Searches for all bindings with qualified names that seen as an array of simple names match the given array of patterns.
IIndexBinding[]	findBindings(Pattern pattern, boolean isFullyQualified, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) Searches for all bindings with simple names that match the given pattern.
IIndexBinding[]	findBindingsForContentAssist(char[] prefix, boolean fileScopeOnly, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor)
IIndexBinding[]	findBindingsForPrefix(char[] prefix, boolean fileScopeOnly, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) Searches for all bindings with names that start with the given prefix.
IIndexName[]	findDeclarations(IBinding binding) Searches for all declarations and definitions that resolve to the given binding.
IIndexName[]	findDefinitions(IBinding binding) Searches for all definitions that resolve to the given binding.
IIndexInclude[]	findIncludedBy(IIndexFile file) Looks for include relations pointing to the given file.
IIndexInclude[]	findIncludedBy(IIndexFile file, int depth) Looks recursively for include relations pointing to the given file.
IIndexInclude[]	findIncludes(IIndexFile file) Looks for include relations originated by the given file.
IIndexInclude[]	findIncludes(IIndexFile file, int depth) Looks recursively for include relations originated by the given file.
IIndexBinding[]	findMacroContainers(Pattern pattern, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) Searches for all macro containers (one for macros with the same name) with names that match the given pattern.
IIndexMacro[]	findMacros(char[] name, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) Searches for all macros with a given name.
IIndexMacro[]	findMacrosForPrefix(char[] prefix, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) Searches for all macros with names that start with the given prefix.
IIndexName[]	findNames(IBinding binding, int flags) Searches for all names that resolve to the given binding.
IIndexName[]	findReferences(IBinding binding) Searches for all references that resolve to the given binding.
IIndexFile[]	getAllFiles() Returns an array of all files that are part of this index.
IIndexFile[]	getDefectiveFiles() Returns an array of files that were indexed with I/O errors.
IIndexFile	getFile(int linkageID, IIndexFileLocation location) Deprecated. Use getFile(int, IIndexFileLocation, ISignificantMacros) or getFiles(int, IIndexFileLocation).
IIndexFile	getFile(int linkageID, IIndexFileLocation location, ISignificantMacros significantMacros) Returns the file for the given location, linkage, and significant macros May return null, if no such file exists.
IIndexFile[]	getFiles(IIndexFileLocation location) Returns the file objects for the given location in any linkage.
IIndexFile[]	getFiles(int linkageID, IIndexFileLocation location) Returns the file objects for the given location and linkage.
IIndexFile[]	getFilesWithUnresolvedIncludes() Returns an array of files containing unresolved includes.
IScope[]	getInlineNamespaces() Returns the global inline c++ namespaces.
long	getLastWriteAccess() Returns a timestamp of when the index was last written to.
boolean	hasWaitingReaders()
boolean	isFullyInitialized() Returns true if the index is fully initialized.
void	releaseReadLock() Any lock obtained by acquireReadLock() must be released.
IIndexFile	resolveInclude(IIndexInclude include) Resolves the file that is included by the given include directive.

Field Detail

DEPTH_INFINITE

static final int DEPTH_INFINITE

Constant to specify infinite depth.

See Also:

findIncludedBy(IIndexFile, int), findIncludes(IIndexFile, int), Constant Field Values

DEPTH_ZERO

static final int DEPTH_ZERO

Constant to find direct includes, only.

See Also:

findIncludedBy(IIndexFile, int), findIncludes(IIndexFile, int), Constant Field Values

FIND_DECLARATIONS

static final int FIND_DECLARATIONS

Constant to search for declarations. This does not include definitions.

See Also:

Constant Field Values

FIND_DEFINITIONS

static final int FIND_DEFINITIONS

Constant to search for definitions. This does not include declarations.

See Also:

Constant Field Values

FIND_REFERENCES

static final int FIND_REFERENCES

Constant to search for references. This does not include declarations or definitions.

See Also:

Constant Field Values

SEARCH_ACROSS_LANGUAGE_BOUNDARIES

static final int SEARCH_ACROSS_LANGUAGE_BOUNDARIES

Constant to search for occurrences across language boundaries. Can be used to find the occurrences of a C++-function declared with 'extern "C"' within the c-linkage.

See Also:

Constant Field Values

FIND_POTENTIAL_MATCHES

static final int FIND_POTENTIAL_MATCHES

Constant to include potential matches in the results of a search. An example of a potential match might be a function definition that does match a declaration exactly in signature.

Since:

6.5

See Also:

Constant Field Values

FIND_DECLARATIONS_DEFINITIONS

static final int FIND_DECLARATIONS_DEFINITIONS

Constant to search for all declarations including definitions.

See Also:

Constant Field Values

FIND_ALL_OCCURRENCES

static final int FIND_ALL_OCCURRENCES

Constant to search for all occurrences of a binding. This includes declarations, definitions and references.

See Also:

Constant Field Values

Method Detail

acquireReadLock

void acquireReadLock()
              throws InterruptedException

Before making calls to an index you have to obtain a lock. The objects returned by an index become invalid as soon as the indexer writes to the index. You may obtain nested read locks. Make sure you release the lock.

Throws:

InterruptedException

See Also:

 index.acquireReadLock();
 try {
    ....
 } finally {
    index.releaseReadLock();
 }
 

releaseReadLock

void releaseReadLock()

Any lock obtained by acquireReadLock() must be released.

hasWaitingReaders

boolean hasWaitingReaders()

Returns:

true if there are threads waiting for read locks.

Since:

5.2

getLastWriteAccess

long getLastWriteAccess()

Returns a timestamp of when the index was last written to. This can be used to figure out whether information read from the index is still reliable or not.

 long timestamp;
 IBinding binding= null;
 index.acquireReadLock();
 try {
    timestamp= index.getLastWriteAccess();
    binding= index.findBinding(...);
 } finally {
    index.releaseReadLock();
 }
 ...
 index.acqureReadLock();
 try {
    if (index.getLastWriteAccess() != timestamp) {
       // don't use binding, it's not valid anymore
       binding= index.findBinding(...);
    }
    String name= binding.getName();
    ...
 } finally {
    index.releaseReadLock();
 }

getFile

@Deprecated
IIndexFile getFile(int linkageID,
                               IIndexFileLocation location)
                        throws org.eclipse.core.runtime.CoreException

Deprecated. Use getFile(int, IIndexFileLocation, ISignificantMacros) or getFiles(int, IIndexFileLocation).

Throws:

org.eclipse.core.runtime.CoreException

Restriction:

This method is not intended to be referenced by clients.

getFile

IIndexFile getFile(int linkageID,
                   IIndexFileLocation location,
                   ISignificantMacros significantMacros)
            throws org.eclipse.core.runtime.CoreException

Returns the file for the given location, linkage, and significant macros May return null, if no such file exists.

Parameters:

linkageID - the id of the linkage in which the file has been parsed.

location - the IIndexFileLocation representing the location of the file

significantMacros - The names and definitions of the macros used to disambiguate between variants of the file contents corresponding to different inclusion points.

Returns:

the file for the location, or null if the file is not present in the index

Throws:

org.eclipse.core.runtime.CoreException

Since:

5.4

getFiles

IIndexFile[] getFiles(int linkageID,
                      IIndexFileLocation location)
               throws org.eclipse.core.runtime.CoreException

Returns the file objects for the given location and linkage. Multiple files are returned when a header file is stored in the index in multiple variants for different sets of macro definitions. This method may only return files that are actually managed by this fragment. This method returns files without content, also.

Parameters:

linkageID - the id of the linkage in which the file has been parsed.

location - the IIndexFileLocation representing the location of the file

Returns:

the files for the location and the linkage.

Throws:

org.eclipse.core.runtime.CoreException

Since:

5.4

getFiles

IIndexFile[] getFiles(IIndexFileLocation location)
               throws org.eclipse.core.runtime.CoreException

Returns the file objects for the given location in any linkage.

Parameters:

location - an IIndexFileLocation representing the location of the file

Returns:

an array of file-objects.

Throws:

org.eclipse.core.runtime.CoreException

findIncludes

IIndexInclude[] findIncludes(IIndexFile file)
                      throws org.eclipse.core.runtime.CoreException

Looks for include relations originated by the given file. This is the same as

 findIncludes(file, DEPTH_ZERO); 

Parameters:

file - the file containing the include directives

Returns:

an array of include relations

Throws:

org.eclipse.core.runtime.CoreException

findIncludedBy

IIndexInclude[] findIncludedBy(IIndexFile file)
                        throws org.eclipse.core.runtime.CoreException

Looks for include relations pointing to the given file. This is the same as

 findIncludedBy(file, DEPTH_ZERO); 

Parameters:

file - the file included by the directives to be found

Returns:

an array of include relations

Throws:

org.eclipse.core.runtime.CoreException

findIncludes

IIndexInclude[] findIncludes(IIndexFile file,
                             int depth)
                      throws org.eclipse.core.runtime.CoreException

Looks recursively for include relations originated by the given file.

Parameters:

file - the file containing the include directives

depth - depth to which includes are followed, should be one of DEPTH_ZERO or DEPTH_INFINITE

Returns:

an array of include relations

Throws:

org.eclipse.core.runtime.CoreException

findIncludedBy

IIndexInclude[] findIncludedBy(IIndexFile file,
                               int depth)
                        throws org.eclipse.core.runtime.CoreException

Looks recursively for include relations pointing to the given file.

Parameters:

file - the file the include directives point to

depth - depth to which includes are followed, should be one of DEPTH_ZERO or DEPTH_INFINITE

Returns:

an array of include relations

Throws:

org.eclipse.core.runtime.CoreException

resolveInclude

IIndexFile resolveInclude(IIndexInclude include)
                   throws org.eclipse.core.runtime.CoreException

Resolves the file that is included by the given include directive. May return null in case the file cannot be found. This is usually more efficient than using:

 getFiles(include.getIncludesLocation())
 

Parameters:

include -

Returns:

the file included or null.

Throws:

org.eclipse.core.runtime.CoreException

Since:

4.0

findMacros

IIndexMacro[] findMacros(char[] name,
                         IndexFilter filter,
                         org.eclipse.core.runtime.IProgressMonitor monitor)
                  throws org.eclipse.core.runtime.CoreException

Searches for all macros with a given name.

Parameters:

name - a name, that has to be matched by the macros.

filter - a filter that allows for skipping parts of the index

monitor - a monitor to report progress, may be null.

Returns:

an array of macros matching the name.

Throws:

org.eclipse.core.runtime.CoreException

Since:

4.0.2

findMacrosForPrefix

IIndexMacro[] findMacrosForPrefix(char[] prefix,
                                  IndexFilter filter,
                                  org.eclipse.core.runtime.IProgressMonitor monitor)
                           throws org.eclipse.core.runtime.CoreException

Searches for all macros with names that start with the given prefix.

Parameters:

prefix - the prefix with which all returned macros must start

filter - a filter that allows for skipping parts of the index

monitor - a monitor for progress reporting and cancellation, may be null

Returns:

an array of bindings with the prefix

Throws:

org.eclipse.core.runtime.CoreException

Since:

4.0.2

findBinding

IIndexBinding findBinding(IName name)
                   throws org.eclipse.core.runtime.CoreException

Searches for the binding of a name. The name may be originated by an AST or by a search in an index. May return null.

Parameters:

name - a name to find the binding for

Returns:

the binding or null

Throws:

org.eclipse.core.runtime.CoreException

findBindings

IIndexBinding[] findBindings(Pattern pattern,
                             boolean isFullyQualified,
                             IndexFilter filter,
                             org.eclipse.core.runtime.IProgressMonitor monitor)
                      throws org.eclipse.core.runtime.CoreException

Searches for all bindings with simple names that match the given pattern. In case a binding exists in multiple projects, no duplicate bindings are returned. This is fully equivalent to

 findBindings(new Pattern[] {pattern}, isFullyQualified, filter, monitor);
 

Parameters:

pattern - the pattern the name of the binding has to match.

isFullyQualified - if true, binding must be in global scope

filter - a filter that allows for skipping parts of the index

monitor - a monitor to report progress, may be null.

Returns:

an array of bindings matching the pattern

Throws:

org.eclipse.core.runtime.CoreException

findBindings

IIndexBinding[] findBindings(Pattern[] patterns,
                             boolean isFullyQualified,
                             IndexFilter filter,
                             org.eclipse.core.runtime.IProgressMonitor monitor)
                      throws org.eclipse.core.runtime.CoreException

Searches for all bindings with qualified names that seen as an array of simple names match the given array of patterns. In case a binding exists in multiple projects, no duplicate bindings are returned. You can search with an array of patterns that specifies a partial qualification only.

Parameters:

patterns - an array of patterns the components of the qualified name of the bindings have to match.

isFullyQualified - if true, the array of pattern specifies the fully qualified name

filter - a filter that allows for skipping parts of the index

monitor - a monitor to report progress, may be null.

Returns:

an array of bindings matching the pattern

Throws:

org.eclipse.core.runtime.CoreException

findMacroContainers

IIndexBinding[] findMacroContainers(Pattern pattern,
                                    IndexFilter filter,
                                    org.eclipse.core.runtime.IProgressMonitor monitor)
                             throws org.eclipse.core.runtime.CoreException

Searches for all macro containers (one for macros with the same name) with names that match the given pattern. In case a binding exists in multiple projects, no duplicate bindings are returned.

Parameters:

pattern - a pattern the name of the bindings have to match.

filter - a filter that allows for skipping parts of the index

monitor - a monitor to report progress, may be null

Returns:

an array of bindings matching the pattern

Throws:

org.eclipse.core.runtime.CoreException

findBindings

IIndexBinding[] findBindings(char[][] names,
                             IndexFilter filter,
                             org.eclipse.core.runtime.IProgressMonitor monitor)
                      throws org.eclipse.core.runtime.CoreException

Searches for all bindings in global scope with a given name. In case a binding exists in multiple projects, no duplicate bindings are returned. This method makes use of the BTree and is faster than the methods using patterns.

Parameters:

names - an array of names, which has to be matched by the qualified name of the bindings.

filter - a filter that allows for skipping parts of the index

monitor - a monitor to report progress, may be null.

Returns:

an array of bindings matching the pattern

Throws:

org.eclipse.core.runtime.CoreException

findBindings

IIndexBinding[] findBindings(char[] name,
                             IndexFilter filter,
                             org.eclipse.core.runtime.IProgressMonitor monitor)
                      throws org.eclipse.core.runtime.CoreException

Searches the global scope for all bindings with a given name. In case a binding exists in multiple projects, no duplicate bindings are returned. This method makes use of the BTree and is faster than the methods using patterns. This is fully equivalent to

 findBindings(name, true, filter, monitor);
 

Parameters:

name - a name, which has to be matched by the qualified name of the bindings.

filter - a filter that allows for skipping parts of the index

monitor - a monitor to report progress, may be null.

Returns:

an array of bindings matching the pattern

Throws:

org.eclipse.core.runtime.CoreException

findBindings

IIndexBinding[] findBindings(char[] name,
                             boolean fileScopeOnly,
                             IndexFilter filter,
                             org.eclipse.core.runtime.IProgressMonitor monitor)
                      throws org.eclipse.core.runtime.CoreException

Searches the global scope and optionally all other scopes for bindings with a given name. In case a binding exists in multiple projects, no duplicate bindings are returned. This method makes use of the BTree and is faster than the methods using patterns.

Parameters:

name - a name, which has to be matched by the qualified name of the bindings.

fileScopeOnly - if true, only bindings at file scope are returned

filter - a filter that allows for skipping parts of the index

monitor - a monitor to report progress, may be null.

Returns:

an array of bindings matching the pattern

Throws:

org.eclipse.core.runtime.CoreException

findBindingsForPrefix

IIndexBinding[] findBindingsForPrefix(char[] prefix,
                                      boolean fileScopeOnly,
                                      IndexFilter filter,
                                      org.eclipse.core.runtime.IProgressMonitor monitor)
                               throws org.eclipse.core.runtime.CoreException

Searches for all bindings with names that start with the given prefix.

Parameters:

prefix - the prefix with which all returned bindings must start

fileScopeOnly - if true, only bindings at file scope are returned

filter - a filter that allows for skipping parts of the index

monitor - a monitor for progress reporting and cancellation, may be null

Returns:

an array of bindings with the prefix

Throws:

org.eclipse.core.runtime.CoreException

findBindingsForContentAssist

IIndexBinding[] findBindingsForContentAssist(char[] prefix,
                                             boolean fileScopeOnly,
                                             IndexFilter filter,
                                             org.eclipse.core.runtime.IProgressMonitor monitor)
                                      throws org.eclipse.core.runtime.CoreException

Throws:

org.eclipse.core.runtime.CoreException

Restriction:

This method is not intended to be referenced by clients.

findNames

IIndexName[] findNames(IBinding binding,
                       int flags)
                throws org.eclipse.core.runtime.CoreException

Searches for all names that resolve to the given binding. The search can be limited to references, declarations or definitions, or a combination of those.

Parameters:

binding - a binding for which names are searched for

flags - a combination of FIND_DECLARATIONS, FIND_DEFINITIONS, FIND_REFERENCES, SEARCH_ACROSS_LANGUAGE_BOUNDARIES, and FIND_POTENTIAL_MATCHES.

Returns:

an array of names

Throws:

org.eclipse.core.runtime.CoreException

findReferences

IIndexName[] findReferences(IBinding binding)
                     throws org.eclipse.core.runtime.CoreException

Searches for all references that resolve to the given binding. This is fully equivalent to

 findNames(binding, IIndex.FIND_REFERENCES);
 

Parameters:

binding - a binding for which references are searched for

Returns:

an array of names

Throws:

org.eclipse.core.runtime.CoreException

findDeclarations

IIndexName[] findDeclarations(IBinding binding)
                       throws org.eclipse.core.runtime.CoreException

Searches for all declarations and definitions that resolve to the given binding. This is fully equivalent to

 findNames(binding, IIndex.FIND_DECLARATIONS_DEFINITIONS);
 

Parameters:

binding - a binding for which declarations are searched for

Returns:

an array of names

Throws:

org.eclipse.core.runtime.CoreException

findDefinitions

IIndexName[] findDefinitions(IBinding binding)
                      throws org.eclipse.core.runtime.CoreException

Searches for all definitions that resolve to the given binding. This is fully equivalent to

 findNames(binding, IIndex.FIND_DEFINITIONS);
 

Parameters:

binding - a binding for which declarations are searched for

Returns:

an array of names

Throws:

org.eclipse.core.runtime.CoreException

adaptBinding

IIndexBinding adaptBinding(IBinding binding)

Returns an IIndexBinding for this index that is equivalent to the specified binding, or null if such a binding does not exist in this index. This is useful for adapting bindings obtained from IIndex objects that might have been created for a different scope or for IBinding objects obtained directly from the AST.

Parameters:

binding - an AST or an index binding

Returns:

an IIndexBinding for this index that is equivalent to the specified binding

createFileSet

IIndexFileSet createFileSet()

Creates a file-set that can be used with this index as long as the caller holds a read-lock.

getAllFiles

IIndexFile[] getAllFiles()
                  throws org.eclipse.core.runtime.CoreException

Returns an array of all files that are part of this index. If a file is parsed in two linkages or in multiple fragments, only one of the files will be returned.

Throws:

org.eclipse.core.runtime.CoreException

getDefectiveFiles

IIndexFile[] getDefectiveFiles()
                        throws org.eclipse.core.runtime.CoreException

Returns an array of files that were indexed with I/O errors.

Throws:

org.eclipse.core.runtime.CoreException

Since:

5.4

Restriction:

This method is not intended to be referenced by clients.

getFilesWithUnresolvedIncludes

IIndexFile[] getFilesWithUnresolvedIncludes()
                                     throws org.eclipse.core.runtime.CoreException

Returns an array of files containing unresolved includes.

Throws:

org.eclipse.core.runtime.CoreException

Since:

5.4

Restriction:

This method is not intended to be referenced by clients.

getInlineNamespaces

IScope[] getInlineNamespaces()
                      throws org.eclipse.core.runtime.CoreException

Returns the global inline c++ namespaces.

Throws:

org.eclipse.core.runtime.CoreException

Since:

5.3

isFullyInitialized

boolean isFullyInitialized()

Returns true if the index is fully initialized. An index may not be fully initialized during Eclipse startup, or soon after adding a new project to the workspace.

Since:

5.4