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 Detail

      • 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

      • 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

        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.
      • 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