Class Elements


  • public class Elements
    extends java.lang.Object
    Provides static methods for generic access to IElements.

    Methods annotated as "handle-only" do not require underlying elements to exist. Methods that require underlying elements to exist throw a CoreException when the underlying element is missing.

    Note that, despite having a dependency on IResource and IFile, this class can safely be used even when org.eclipse.core.resources bundle is not available. This is based on the "outward impression" of late resolution of symbolic references a JVM must provide according to the JVMS. Since 1.3, there is also a similar dependency on IFileStore.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static Property<ISnapshot> BASE_SNAPSHOT
      Specifies a base snapshot.
      static Property<java.lang.Boolean> CREATE_BUFFER
      Indicates whether a new buffer should be created if none already exists.
      static IElement[] EMPTY_ARRAY
      A zero-length array of the runtime type IElement[].
      static Property<java.lang.Boolean> FORCE_RECONCILING
      Indicates whether reconciling has to be performed even if the working copy buffer has not been modified since the last time the working copy was reconciled.
      static ISourceElementInfo NO_SOURCE_ELEMENT_INFO
      A 'null object' indicating that no info is available for source element, e.g., because the element does not exist.
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static <T extends java.util.Collection<? super IElement>>
      T
      collectParentChain​(IElement element, T collection)
      Adds elements to the given collection starting from the given element (inclusive) and going up through the parent chain to the root element (inclusive).
      static <T extends java.util.Collection<? super IElement>>
      T
      collectParentChainUntil​(IElement element, T collection, java.util.function.Predicate<? super IElement> until)
      Adds elements to the given collection starting from the given element (inclusive) and going up through the parent chain to the ancestor matched by the given predicate (exclusive).
      static boolean ensureReconciled​(ISourceElement element, org.eclipse.core.runtime.IProgressMonitor monitor)
      Ensures that, if the given element is contained in a source file, the source file is reconciled.
      static boolean equalsAndSameParentChain​(IElement element, IElement other)
      Returns whether the elements are equal and belong to the same parent chain.
      static boolean exists​(IElement element)
      Returns whether the element exists in the model.
      static <T> T findAncestorOfType​(IElement element, java.lang.Class<T> type)
      Finds and returns the first element that has the given type starting from the given element (inclusive) and going up through the parent chain.
      static <T> T findAncestorOfTypeUntil​(IElement element, java.lang.Class<T> type, java.util.function.Predicate<? super IElement> until)
      Finds and returns the first element that has the given type starting from the given element (inclusive) and going up through the parent chain no further than the element matched by the given predicate (exclusive).
      static IElement findCommonAncestor​(java.lang.Iterable<? extends IElement> elements)
      Finds and returns the closest common ancestor of the given elements, viewing each element as its own ancestor.
      static IElement findCommonAncestor​(IElement element, IElement other)
      Finds and returns the closest common ancestor of the given elements, viewing each element as its own ancestor.
      static IElement findCommonAncestorUntil​(java.lang.Iterable<? extends IElement> elements, java.util.function.Predicate<? super IElement> until)
      Finds and returns the closest common ancestor of the given elements, viewing each element as its own ancestor and looking no further in each parent chain than the element matched by the given predicate (exclusive).
      static IElement findCommonAncestorUntil​(IElement element, IElement other, java.util.function.Predicate<? super IElement> until)
      Finds and returns the closest common ancestor of the given elements, viewing each element as its own ancestor and looking no further in each parent chain than the element matched by the given predicate (exclusive).
      static <T> T findLastAncestorOfType​(IElement element, java.lang.Class<T> type)
      Finds and returns the last element that has the given type starting from the given element (inclusive) and going up through the parent chain to the root element (inclusive).
      static <T> T findLastAncestorOfTypeUntil​(IElement element, java.lang.Class<T> type, java.util.function.Predicate<? super IElement> until)
      Finds and returns the last element that has the given type starting from the given element (inclusive) and going up through the parent chain to the element matched by the given predicate (exclusive).
      static IElement findLastMatchingAncestor​(IElement element, java.util.function.Predicate<? super IElement> filter)
      Finds and returns the last element that matches the given predicate starting from the given element (inclusive) and going up through the parent chain to the root element (inclusive).
      static IElement findLastMatchingAncestorUntil​(IElement element, java.util.function.Predicate<? super IElement> filter, java.util.function.Predicate<? super IElement> until)
      Finds and returns the last element that matches the given filter predicate starting from the given element (inclusive) and going up through the parent chain to the element matched by the given until predicate (exclusive).
      static IElement findMatchingAncestor​(IElement element, java.util.function.Predicate<? super IElement> filter)
      Finds and returns the first element that matches the given predicate starting from the given element (inclusive) and going up through the parent chain.
      static IElement findMatchingAncestorUntil​(IElement element, java.util.function.Predicate<? super IElement> filter, java.util.function.Predicate<? super IElement> until)
      Finds and returns the first element that matches the given filter predicate starting from the given element (inclusive) and going up through the parent chain no further than the element matched by the given until predicate (exclusive).
      static IBuffer getBuffer​(ISourceFile sourceFile)
      Returns a buffer opened for the source file.
      static IBuffer getBuffer​(ISourceFile sourceFile, IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)
      Returns a buffer opened for the source file.
      static IElement[] getChildren​(IElement element)
      Returns the immediate children of the element.
      static IElement[] getChildren​(IElement element, IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)
      Returns the immediate children of the element.
      static <T> T[] getChildrenOfType​(IElement element, java.lang.Class<T> type)
      Returns the immediate children of the element that have the given type.
      static <T> T[] getChildrenOfType​(IElement element, java.lang.Class<T> type, IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)
      Returns the immediate children of the element that have the given type.
      static org.eclipse.core.resources.IFile getFile​(ISourceFile sourceFile)
      Returns the underlying IFile, or null if the source file has no underlying file in the workspace.
      static org.eclipse.core.filesystem.IFileStore getFileStore​(ISourceFile sourceFile)
      Returns the corresponding IFileStore, or null if the source file has no corresponding file store.
      static java.lang.String getHandleMemento​(IElement element)
      Returns a string representation of the element handle that can be used to recreate the handle via the model's IElementHandleFactory.
      static java.net.URI getLocationUri​(IElement element)
      Returns a file system location for the element.
      static IModel getModel​(IElement element)
      Returns the model that owns the element.
      static int getModelApiLevel​(IElement element)
      Returns the Handly API level supported by the element's model; one of the level constants declared in ApiLevel.
      static IContext getModelContext​(IElement element)
      Returns a context which provides information and services pertaining to the element's model.
      static java.lang.String getName​(IElement element)
      Returns the name of the element, or null if the element has no name.
      static IElement getParent​(IElement element)
      Returns the immediate parent of the element, or null if the element has no parent.
      static java.lang.Iterable<IElement> getParentChain​(IElement element)
      Returns an Iterable that starts from the given element (inclusive) and goes up through the parent chain to the root element (inclusive).
      static java.lang.Iterable<IElement> getParentChainUntil​(IElement element, java.util.function.Predicate<? super IElement> until)
      Returns an Iterable that starts from the given element (inclusive) and goes up through the parent chain to the ancestor matched by the given predicate (exclusive).
      static org.eclipse.core.resources.IResource getResource​(IElement element)
      Returns the innermost resource enclosing the element, or null if the element is not enclosed in a workspace resource.
      static IElement getRoot​(IElement element)
      Returns the root element for the element.
      static ISourceElement getSourceElementAt​(ISourceElement element, int position, IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)
      Returns the smallest element that includes the given source position, or null if the given position is not within the source range of the given element.
      static ISourceElement getSourceElementAt​(ISourceElement element, int position, ISnapshot base)
      Returns the smallest element that includes the given source position, or null if the given position is not within the source range of the given element.
      static ISourceElement getSourceElementAt2​(ISourceElement element, int position, ISnapshot base)
      Returns the smallest element that includes the given position, or null if the given position is not within the source range of the given element, or if the given element does not exist or an exception occurs while accessing its corresponding resource, or if snapshot inconsistency is detected.
      static ISourceElementInfo getSourceElementInfo​(ISourceElement element)
      Returns an object holding cached structure and properties for the source element.
      static ISourceElementInfo getSourceElementInfo​(ISourceElement element, IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)
      Returns an object holding cached structure and properties for the source element.
      static ISourceElementInfo getSourceElementInfo2​(ISourceElement element)
      Returns an object holding cached structure and properties for the source element, or NO_SOURCE_ELEMENT_INFO if no such info is available.
      static ISourceFile getSourceFile​(IElement element)
      Returns the source file that contains the given element, or null if the given element is not contained in a source file.
      static boolean isAncestorOf​(IElement element, IElement other)
      Returns whether both elements belong to the same parent chain and the first element is equal to or is an ancestor of the other element.
      static boolean isOfModel​(IElement element, IModel model)
      Returns whether the element belongs to the given model.
      static boolean isWorkingCopy​(ISourceFile sourceFile)
      Returns whether the source file is a working copy.
      static boolean needsReconciling​(ISourceFile sourceFile)
      Returns whether the source file needs reconciling.
      static void reconcile​(ISourceFile sourceFile, org.eclipse.core.runtime.IProgressMonitor monitor)
      Reconciles the source file.
      static void reconcile​(ISourceFile sourceFile, IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)
      Reconciles the source file.
      static void removeDescendants​(java.util.Collection<? extends IElement> elements)
      Removes descendants from the given collection of elements; in other words, removes those elements for which an ancestor is also present in the given collection.
      static void splitIntoElementsAndResources​(java.lang.Iterable<?> objects, java.util.Collection<? super IElement> elements, IModel model, java.util.Collection<? super org.eclipse.core.resources.IResource> resources, IElementHandleFactory elementHandleFactory)
      Splits the given objects into a collection of IElements and a collection of IResources, ignoring objects that are neither elements nor resources.
      static java.util.stream.Stream<IElement> streamParentChain​(IElement element)
      Returns a sequential ordered stream that starts from the given element (inclusive) and goes up through the parent chain to the root element (inclusive).
      static java.util.stream.Stream<IElement> streamParentChainUntil​(IElement element, java.util.function.Predicate<? super IElement> until)
      Returns a sequential ordered stream that starts from the given element (inclusive) and goes up through the parent chain to the ancestor matched by the given predicate (exclusive).
      static java.lang.String toDisplayString​(IElement element, IContext context)
      Returns a string representation of the element in a form suitable for displaying to the user, e.g., in message dialogs.
      static java.lang.String toString​(IElement element, IContext context)
      Returns a string representation of the element in a form suitable for debugging purposes.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Method Detail

      • getName

        public static java.lang.String getName​(IElement element)
        Returns the name of the element, or null if the element has no name. This is a handle-only method.
        Parameters:
        element - not null
        Returns:
        the element name, or null if the element has no name
      • getParent

        public static IElement getParent​(IElement element)
        Returns the immediate parent of the element, or null if the element has no parent. This is a handle-only method.
        Parameters:
        element - not null
        Returns:
        the parent element, or null if the element has no parent
      • getRoot

        public static IElement getRoot​(IElement element)
        Returns the root element for the element. Returns the element itself if it has no parent. This is a handle-only method.
        Parameters:
        element - not null
        Returns:
        the root element (never null)
      • getParentChain

        public static java.lang.Iterable<IElement> getParentChain​(IElement element)
        Returns an Iterable that starts from the given element (inclusive) and goes up through the parent chain to the root element (inclusive). This is a handle-only method.

        This method is equivalent to getParentChainUntil(element, null).

        Parameters:
        element - may be null, in which case an empty iterable will be returned
        Returns:
        an iterable representing the specified parent chain (never null)
      • getParentChainUntil

        public static java.lang.Iterable<IElement> getParentChainUntil​(IElement element,
                                                                       java.util.function.Predicate<? super IElement> until)
        Returns an Iterable that starts from the given element (inclusive) and goes up through the parent chain to the ancestor matched by the given predicate (exclusive). If the predicate is not matched or is null, all ancestors will be included. If the predicate matches the given element, the returned iterable will be empty. This is a handle-only method.
        Parameters:
        element - may be null, in which case an empty iterable will be returned
        until - may be null
        Returns:
        an iterable representing the specified parent chain (never null)
      • streamParentChain

        public static java.util.stream.Stream<IElement> streamParentChain​(IElement element)
        Returns a sequential ordered stream that starts from the given element (inclusive) and goes up through the parent chain to the root element (inclusive). This is a handle-only method.

        This method is equivalent to streamParentChainUntil(element, null).

        Parameters:
        element - may be null, in which case an empty stream will be returned
        Returns:
        a stream representing the specified parent chain (never null)
      • streamParentChainUntil

        public static java.util.stream.Stream<IElement> streamParentChainUntil​(IElement element,
                                                                               java.util.function.Predicate<? super IElement> until)
        Returns a sequential ordered stream that starts from the given element (inclusive) and goes up through the parent chain to the ancestor matched by the given predicate (exclusive). If the predicate is not matched or is null, all ancestors will be included. If the predicate matches the given element, the returned stream will be empty. This is a handle-only method.
        Parameters:
        element - may be null, in which case an empty stream will be returned
        until - may be null
        Returns:
        a stream representing the specified parent chain (never null)
      • collectParentChain

        public static <T extends java.util.Collection<? super IElement>> T collectParentChain​(IElement element,
                                                                                              T collection)
        Adds elements to the given collection starting from the given element (inclusive) and going up through the parent chain to the root element (inclusive). This is a handle-only method.

        This method is equivalent to collectParentChainUntil(element, null).

        Parameters:
        element - may be null, in which case no elements will be added to the given collection
        collection - not null
        Returns:
        the given collection instance
      • collectParentChainUntil

        public static <T extends java.util.Collection<? super IElement>> T collectParentChainUntil​(IElement element,
                                                                                                   T collection,
                                                                                                   java.util.function.Predicate<? super IElement> until)
        Adds elements to the given collection starting from the given element (inclusive) and going up through the parent chain to the ancestor matched by the given predicate (exclusive). If the predicate is not matched or is null, all ancestors will be included. If the predicate matches the given element, no elements will be added to the collection. This is a handle-only method.
        Parameters:
        element - may be null, in which case no elements will be added to the given collection
        collection - not null
        until - may be null
        Returns:
        the given collection instance
      • findMatchingAncestor

        public static IElement findMatchingAncestor​(IElement element,
                                                    java.util.function.Predicate<? super IElement> filter)
        Finds and returns the first element that matches the given predicate starting from the given element (inclusive) and going up through the parent chain. Returns null if no such element can be found. This is a handle-only method.

        This method is equivalent to findMatchingAncestorUntil(element, filter, null).

        Parameters:
        element - may be null, in which case null will be returned
        filter - not null
        Returns:
        the matching element, or null if no such element can be found
      • findMatchingAncestorUntil

        public static IElement findMatchingAncestorUntil​(IElement element,
                                                         java.util.function.Predicate<? super IElement> filter,
                                                         java.util.function.Predicate<? super IElement> until)
        Finds and returns the first element that matches the given filter predicate starting from the given element (inclusive) and going up through the parent chain no further than the element matched by the given until predicate (exclusive). Returns null if no such element can be found. If the until predicate is not matched or is null, all ancestors will be included. If the until predicate matches the given element, null will be returned. This is a handle-only method.
        Parameters:
        element - may be null, in which case null will be returned
        filter - not null
        until - may be null
        Returns:
        the matching element, or null if no such element can be found
      • findAncestorOfType

        public static <T> T findAncestorOfType​(IElement element,
                                               java.lang.Class<T> type)
        Finds and returns the first element that has the given type starting from the given element (inclusive) and going up through the parent chain. Returns null if no such element can be found. This is a handle-only method.

        This method is equivalent to findAncestorOfTypeUntil(element, type, null).

        Parameters:
        element - may be null, in which case null will be returned
        type - not null
        Returns:
        the matching element, or null if no such element can be found
      • findAncestorOfTypeUntil

        public static <T> T findAncestorOfTypeUntil​(IElement element,
                                                    java.lang.Class<T> type,
                                                    java.util.function.Predicate<? super IElement> until)
        Finds and returns the first element that has the given type starting from the given element (inclusive) and going up through the parent chain no further than the element matched by the given predicate (exclusive). Returns null if no such element can be found. If the predicate is not matched or is null, all ancestors will be included. If the predicate matches the given element, null will be returned. This is a handle-only method.
        Parameters:
        element - may be null, in which case null will be returned
        type - not null
        until - may be null
        Returns:
        the matching element, or null if no such element can be found
      • findLastMatchingAncestor

        public static IElement findLastMatchingAncestor​(IElement element,
                                                        java.util.function.Predicate<? super IElement> filter)
        Finds and returns the last element that matches the given predicate starting from the given element (inclusive) and going up through the parent chain to the root element (inclusive). Returns null if no such element can be found. This is a handle-only method.

        This method is equivalent to findLastMatchingAncestorUntil(element, filter, null).

        Parameters:
        element - may be null, in which case null will be returned
        filter - not null
        Returns:
        the matching element, or null if no such element can be found
      • findLastMatchingAncestorUntil

        public static IElement findLastMatchingAncestorUntil​(IElement element,
                                                             java.util.function.Predicate<? super IElement> filter,
                                                             java.util.function.Predicate<? super IElement> until)
        Finds and returns the last element that matches the given filter predicate starting from the given element (inclusive) and going up through the parent chain to the element matched by the given until predicate (exclusive). Returns null if no such element can be found. If the until predicate is not matched or is null, all ancestors will be included. If the until predicate matches the given element, null will be returned. This is a handle-only method.
        Parameters:
        element - may be null, in which case null will be returned
        filter - not null
        until - may be null
        Returns:
        the matching element, or null if no such element can be found
      • findLastAncestorOfType

        public static <T> T findLastAncestorOfType​(IElement element,
                                                   java.lang.Class<T> type)
        Finds and returns the last element that has the given type starting from the given element (inclusive) and going up through the parent chain to the root element (inclusive). Returns null if no such element can be found. This is a handle-only method.

        This method is equivalent to findLastAncestorOfTypeUntil(element, type, null).

        Parameters:
        element - may be null, in which case null will be returned
        type - not null
        Returns:
        the matching element, or null if no such element can be found
      • findLastAncestorOfTypeUntil

        public static <T> T findLastAncestorOfTypeUntil​(IElement element,
                                                        java.lang.Class<T> type,
                                                        java.util.function.Predicate<? super IElement> until)
        Finds and returns the last element that has the given type starting from the given element (inclusive) and going up through the parent chain to the element matched by the given predicate (exclusive). Returns null if no such element can be found. If the predicate is not matched or is null, all ancestors will be included. If the predicate matches the given element, null will be returned. This is a handle-only method.
        Parameters:
        element - may be null, in which case null will be returned
        type - not null
        until - may be null
        Returns:
        the matching element, or null if no such element can be found
      • findCommonAncestor

        public static IElement findCommonAncestor​(IElement element,
                                                  IElement other)
        Finds and returns the closest common ancestor of the given elements, viewing each element as its own ancestor. Returns null if no such element can be found. This is a handle-only method.

        This method is equivalent to findCommonAncestorUntil(element, other, null).

        Parameters:
        element - may be null, in which case null will be returned
        other - may be null, in which case null will be returned
        Returns:
        the matching element, or null if no such element can be found
      • findCommonAncestorUntil

        public static IElement findCommonAncestorUntil​(IElement element,
                                                       IElement other,
                                                       java.util.function.Predicate<? super IElement> until)
        Finds and returns the closest common ancestor of the given elements, viewing each element as its own ancestor and looking no further in each parent chain than the element matched by the given predicate (exclusive). Returns null if no such element can be found. If the predicate is not matched or is null, all ancestors will be included. If the predicate matches any of the given elements, null will be returned. This is a handle-only method.
        Parameters:
        element - may be null, in which case null will be returned
        other - may be null, in which case null will be returned
        until - may be null
        Returns:
        the matching element, or null if no such element can be found
      • findCommonAncestor

        public static IElement findCommonAncestor​(java.lang.Iterable<? extends IElement> elements)
        Finds and returns the closest common ancestor of the given elements, viewing each element as its own ancestor. Returns null if no such element can be found. This is a handle-only method.

        This method is equivalent to findCommonAncestorUntil(elements, null).

        Parameters:
        elements - not null, may contain nulls
        Returns:
        the matching element, or null if no such element can be found
      • findCommonAncestorUntil

        public static IElement findCommonAncestorUntil​(java.lang.Iterable<? extends IElement> elements,
                                                       java.util.function.Predicate<? super IElement> until)
        Finds and returns the closest common ancestor of the given elements, viewing each element as its own ancestor and looking no further in each parent chain than the element matched by the given predicate (exclusive). Returns null if no such element can be found. If the predicate is not matched or is null, all ancestors will be included. If the predicate matches any of the given elements, null will be returned. This is a handle-only method.
        Parameters:
        elements - not null, may contain nulls
        until - may be null
        Returns:
        the matching element, or null if no such element can be found
      • isAncestorOf

        public static boolean isAncestorOf​(IElement element,
                                           IElement other)
        Returns whether both elements belong to the same parent chain and the first element is equal to or is an ancestor of the other element. This is a handle-only method.
        Parameters:
        element - not null
        other - may be null, in which case false will be returned
        Returns:
        true if both elements belong to the same parent chain and the first element is equal to or an ancestor of the other element, and false otherwise
      • removeDescendants

        public static void removeDescendants​(java.util.Collection<? extends IElement> elements)
        Removes descendants from the given collection of elements; in other words, removes those elements for which an ancestor is also present in the given collection. This is a handle-only method.
        Parameters:
        elements - not null, must not contain null elements
      • equalsAndSameParentChain

        public static boolean equalsAndSameParentChain​(IElement element,
                                                       IElement other)
        Returns whether the elements are equal and belong to the same parent chain. This is a handle-only method.

        In the most general case, equal elements may belong to different parent chains. For example, in JDT, equal JarPackageFragmentRoots may belong to different Java projects.

        Parameters:
        element - not null
        other - may be null
        Returns:
        true if the elements are equal and belong to the same parent chain, and false otherwise
      • getModel

        public static IModel getModel​(IElement element)
        Returns the model that owns the element. This is a handle-only method.
        Parameters:
        element - not null
        Returns:
        the element's model (never null)
      • isOfModel

        public static boolean isOfModel​(IElement element,
                                        IModel model)
        Returns whether the element belongs to the given model. More formally, returns true if, and only if, model.equals(getModel(element)). This is a handle-only method.
        Parameters:
        element - not null
        model - not null
        Returns:
        true if the element belongs to the given model, and false otherwise
      • getModelContext

        public static IContext getModelContext​(IElement element)
        Returns a context which provides information and services pertaining to the element's model. The context, as a set of bindings, is immutable. This is a handle-only method.
        Parameters:
        element - not null
        Returns:
        the model context for the element (never null)
      • getModelApiLevel

        public static int getModelApiLevel​(IElement element)
        Returns the Handly API level supported by the element's model; one of the level constants declared in ApiLevel. This is a handle-only method.
        Parameters:
        element - not null
        Returns:
        the Handly API level supported by the element's model
      • getHandleMemento

        public static java.lang.String getHandleMemento​(IElement element)
        Returns a string representation of the element handle that can be used to recreate the handle via the model's IElementHandleFactory. The format of the string is not specified, but the representation is stable across workbench sessions. This is a handle-only method.
        Parameters:
        element - not null
        Returns:
        the handle memento for the element, or null if the element is unable to provide a handle memento
      • getResource

        public static org.eclipse.core.resources.IResource getResource​(IElement element)
        Returns the innermost resource enclosing the element, or null if the element is not enclosed in a workspace resource. This is a handle-only method.

        Note that it is safe to call this method and test the return value for null even when org.eclipse.core.resources bundle is not available.

        Parameters:
        element - not null
        Returns:
        the innermost resource enclosing the element, or null if the element is not enclosed in a workspace resource
      • splitIntoElementsAndResources

        public static void splitIntoElementsAndResources​(java.lang.Iterable<?> objects,
                                                         java.util.Collection<? super IElement> elements,
                                                         IModel model,
                                                         java.util.Collection<? super org.eclipse.core.resources.IResource> resources,
                                                         IElementHandleFactory elementHandleFactory)
        Splits the given objects into a collection of IElements and a collection of IResources, ignoring objects that are neither elements nor resources. The given element handle factory is used to translate resources to elements; if a resource has a corresponding existing element, the element will be added instead of the resource. This is a handle-only method.
        Parameters:
        objects - not null, may contain null elements
        elements - not null
        model - may be null. If not null, only elements belonging to the model will be added to the elements collection
        resources - may be null. If null, no checks for instanceof IResource will be done
        elementHandleFactory - may be null. If null, resources will be added without first trying to translate them to elements
      • getLocationUri

        public static java.net.URI getLocationUri​(IElement element)
        Returns a file system location for the element. The resulting URI is suitable to passing to EFS.getStore(URI). Returns null if no location can be determined.
        Parameters:
        element - not null
        Returns:
        a file system location for the element, or null if no location can be determined
      • exists

        public static boolean exists​(IElement element)
        Returns whether the element exists in the model.

        Handles may or may not be backed by an actual element. Handles that are backed by an actual element are said to "exist".

        Parameters:
        element - not null
        Returns:
        true if the element exists in the model, and false if the element does not exist
      • getChildren

        public static IElement[] getChildren​(IElement element)
                                      throws org.eclipse.core.runtime.CoreException
        Returns the immediate children of the element. Unless otherwise specified by the parent element, the children are in no particular order.
        Parameters:
        element - not null
        Returns:
        the immediate children of the element (never null). Clients must not modify the returned array.
        Throws:
        org.eclipse.core.runtime.CoreException - if the element does not exist or if an exception occurs while accessing its corresponding resource
      • getChildren

        public static IElement[] getChildren​(IElement element,
                                             IContext context,
                                             org.eclipse.core.runtime.IProgressMonitor monitor)
                                      throws org.eclipse.core.runtime.CoreException
        Returns the immediate children of the element. Unless otherwise specified by the parent element, the children are in no particular order.
        Parameters:
        element - not null
        context - the operation context (not null)
        monitor - a progress monitor, or null if progress reporting is not desired. The caller must not rely on IProgressMonitor.done() having been called by the receiver
        Returns:
        the immediate children of the element (never null). Clients must not modify the returned array.
        Throws:
        org.eclipse.core.runtime.CoreException - if the element does not exist or if an exception occurs while accessing its corresponding resource
      • getChildrenOfType

        public static <T> T[] getChildrenOfType​(IElement element,
                                                java.lang.Class<T> type)
                                         throws org.eclipse.core.runtime.CoreException
        Returns the immediate children of the element that have the given type. Unless otherwise specified by the parent element, the children are in no particular order.
        Parameters:
        element - not null
        type - not null
        Returns:
        the immediate children of the element that have the given type (never null). Clients must not modify the returned array.
        Throws:
        org.eclipse.core.runtime.CoreException - if the element does not exist or if an exception occurs while accessing its corresponding resource
      • getChildrenOfType

        public static <T> T[] getChildrenOfType​(IElement element,
                                                java.lang.Class<T> type,
                                                IContext context,
                                                org.eclipse.core.runtime.IProgressMonitor monitor)
                                         throws org.eclipse.core.runtime.CoreException
        Returns the immediate children of the element that have the given type. Unless otherwise specified by the parent element, the children are in no particular order.
        Parameters:
        element - not null
        type - not null
        context - the operation context (not null)
        monitor - a progress monitor, or null if progress reporting is not desired. The caller must not rely on IProgressMonitor.done() having been called by the receiver
        Returns:
        the immediate children of the element that have the given type (never null). Clients must not modify the returned array.
        Throws:
        org.eclipse.core.runtime.CoreException - if the element does not exist or if an exception occurs while accessing its corresponding resource
      • toString

        public static java.lang.String toString​(IElement element,
                                                IContext context)
        Returns a string representation of the element in a form suitable for debugging purposes. Clients can influence the result with options specified in the given context; unrecognized options are ignored and an empty context is permitted.

        Model implementations are encouraged to support common options defined in ToStringOptions and interpret the FORMAT_STYLE as follows:

        • FULL - A full representation that lists ancestors and children.
        • LONG - A long representation that lists children but not ancestors.
        • MEDIUM - A compact representation that lists ancestors but not children.
        • SHORT - A minimal representation that does not list ancestors or children.
        Parameters:
        element - not null
        context - not null
        Returns:
        a string representation of the element (never null)
      • toDisplayString

        public static java.lang.String toDisplayString​(IElement element,
                                                       IContext context)
        Returns a string representation of the element in a form suitable for displaying to the user, e.g., in message dialogs. Clients can influence the result with options specified in the given context; unrecognized options are ignored and an empty context is permitted.

        Model implementations are encouraged to support common options defined in ToStringOptions and may interpret the FORMAT_STYLE as they see fit in a way that is specific to the model. No hard rules apply, but usually the string representation does not list the element's children regardless of the format style, and a FULL representation fully identifies the element within the model.

        Parameters:
        element - not null
        context - not null
        Returns:
        a string representation of the element (never null)
      • getSourceElementAt

        public static ISourceElement getSourceElementAt​(ISourceElement element,
                                                        int position,
                                                        ISnapshot base)
                                                 throws org.eclipse.core.runtime.CoreException
        Returns the smallest element that includes the given source position, or null if the given position is not within the source range of the given element. If no finer grained element is found at the position, the given element itself is returned.
        Parameters:
        element - a source element (not null)
        position - a source position (0-based)
        base - a snapshot on which the given position is based, or null if the snapshot is unknown or does not matter
        Returns:
        the innermost element enclosing the given source position, or null if none (including the given element itself)
        Throws:
        org.eclipse.core.runtime.CoreException - if the given element does not exist or if an exception occurs while accessing its corresponding resource
        StaleSnapshotException - if snapshot inconsistency is detected, i.e., the given element's current structure and properties are based on a different snapshot
      • getSourceElementAt

        public static ISourceElement getSourceElementAt​(ISourceElement element,
                                                        int position,
                                                        IContext context,
                                                        org.eclipse.core.runtime.IProgressMonitor monitor)
                                                 throws org.eclipse.core.runtime.CoreException
        Returns the smallest element that includes the given source position, or null if the given position is not within the source range of the given element. If no finer grained element is found at the position, the given element itself is returned.

        Model implementations are encouraged to support the following standard options, which may be specified in the given context:

        • BASE_SNAPSHOT - A snapshot on which the given position is based, or null if the snapshot is unknown or does not matter.
        Parameters:
        element - a source element (not null)
        position - a source position (0-based)
        context - the operation context (not null)
        monitor - a progress monitor, or null if progress reporting is not desired. The caller must not rely on IProgressMonitor.done() having been called by the receiver
        Returns:
        the innermost element enclosing the given source position, or null if none (including the given element itself)
        Throws:
        org.eclipse.core.runtime.CoreException - if the given element does not exist or if an exception occurs while accessing its corresponding resource
        StaleSnapshotException - if snapshot inconsistency is detected, i.e., the given element's current structure and properties are based on a different snapshot
      • getSourceElementAt2

        public static ISourceElement getSourceElementAt2​(ISourceElement element,
                                                         int position,
                                                         ISnapshot base)
        Returns the smallest element that includes the given position, or null if the given position is not within the source range of the given element, or if the given element does not exist or an exception occurs while accessing its corresponding resource, or if snapshot inconsistency is detected. If no finer grained element is found at the position, the given element itself is returned.
        Parameters:
        element - a source element (not null)
        position - a source position (0-based)
        base - a snapshot on which the given position is based, or null if the snapshot is unknown or does not matter
        Returns:
        the innermost element enclosing the given source position, or null if none (including the given element itself)
      • getSourceElementInfo

        public static ISourceElementInfo getSourceElementInfo​(ISourceElement element)
                                                       throws org.eclipse.core.runtime.CoreException
        Returns an object holding cached structure and properties for the source element.
        Parameters:
        element - not null
        Returns:
        an ISourceElementInfo for the element (never null)
        Throws:
        org.eclipse.core.runtime.CoreException - if the element does not exist or if an exception occurs while accessing its corresponding resource
      • getSourceElementInfo

        public static ISourceElementInfo getSourceElementInfo​(ISourceElement element,
                                                              IContext context,
                                                              org.eclipse.core.runtime.IProgressMonitor monitor)
                                                       throws org.eclipse.core.runtime.CoreException
        Returns an object holding cached structure and properties for the source element.
        Parameters:
        element - not null
        context - the operation context (not null)
        monitor - a progress monitor, or null if progress reporting is not desired. The caller must not rely on IProgressMonitor.done() having been called by the receiver
        Returns:
        an ISourceElementInfo for the element (never null)
        Throws:
        org.eclipse.core.runtime.CoreException - if the element does not exist or if an exception occurs while accessing its corresponding resource
      • getSourceFile

        public static ISourceFile getSourceFile​(IElement element)
        Returns the source file that contains the given element, or null if the given element is not contained in a source file. Returns the given element itself if it is a source file. This is a handle-only method.
        Parameters:
        element - may be null, in which case null will be returned
        Returns:
        the source file containing the given element, or null if none
      • ensureReconciled

        public static boolean ensureReconciled​(ISourceElement element,
                                               org.eclipse.core.runtime.IProgressMonitor monitor)
        Ensures that, if the given element is contained in a source file, the source file is reconciled. Note that the call may result in the change of existence status for the given element: if the element did not exist before, it may be brought into existence; conversely, if the element existed, it may cease to exist.
        Parameters:
        element - not null
        monitor - a progress monitor, or null if progress reporting is not desired. The caller must not rely on IProgressMonitor.done() having been called by the receiver
        Returns:
        true if the call completed successfully, and false in case of a failure
        Throws:
        org.eclipse.core.runtime.OperationCanceledException - if this method is canceled
      • getFile

        public static org.eclipse.core.resources.IFile getFile​(ISourceFile sourceFile)
        Returns the underlying IFile, or null if the source file has no underlying file in the workspace. This is a handle-only method.

        This method returns the same value as getResource(IElement), but saves a downcast.

        Parameters:
        sourceFile - not null
        Returns:
        the underlying IFile, or null if the source file has no underlying file in the workspace
      • getFileStore

        public static org.eclipse.core.filesystem.IFileStore getFileStore​(ISourceFile sourceFile)
        Returns the corresponding IFileStore, or null if the source file has no corresponding file store.
        Parameters:
        sourceFile - not null
        Returns:
        the corresponding IFileStore, or null if this source file has no corresponding file store
        Since:
        1.3
      • isWorkingCopy

        public static boolean isWorkingCopy​(ISourceFile sourceFile)
        Returns whether the source file is a working copy.
        Parameters:
        sourceFile - not null
        Returns:
        true if the source file is a working copy, and false otherwise
      • needsReconciling

        public static boolean needsReconciling​(ISourceFile sourceFile)
        Returns whether the source file needs reconciling. A source file needs reconciling if it is a working copy and its buffer has been modified since the last time it was reconciled.
        Parameters:
        sourceFile - not null
        Returns:
        true if the source file needs reconciling, and false otherwise
      • reconcile

        public static void reconcile​(ISourceFile sourceFile,
                                     org.eclipse.core.runtime.IProgressMonitor monitor)
                              throws org.eclipse.core.runtime.CoreException
        Reconciles the source file. Does nothing if the source file is not in working copy mode or if its buffer has not been modified since the last time it was reconciled.
        Parameters:
        sourceFile - not null
        monitor - a progress monitor, or null if progress reporting is not desired. The caller must not rely on IProgressMonitor.done() having been called by the receiver
        Throws:
        org.eclipse.core.runtime.CoreException - if the working copy could not be reconciled
        org.eclipse.core.runtime.OperationCanceledException - if this method is canceled
      • reconcile

        public static void reconcile​(ISourceFile sourceFile,
                                     IContext context,
                                     org.eclipse.core.runtime.IProgressMonitor monitor)
                              throws org.eclipse.core.runtime.CoreException
        Reconciles the source file. Does nothing if the source file is not in working copy mode.

        Model implementations are encouraged to support the following standard options, which may be specified in the given context:

        • FORCE_RECONCILING - Indicates whether reconciling has to be performed even if the working copy buffer has not been modified since the last time the working copy was reconciled.
        Parameters:
        sourceFile - not null
        context - the operation context (not null)
        monitor - a progress monitor, or null if progress reporting is not desired. The caller must not rely on IProgressMonitor.done() having been called by the receiver
        Throws:
        org.eclipse.core.runtime.CoreException - if the working copy could not be reconciled
        org.eclipse.core.runtime.OperationCanceledException - if this method is canceled
      • getBuffer

        public static IBuffer getBuffer​(ISourceFile sourceFile)
                                 throws org.eclipse.core.runtime.CoreException
        Returns a buffer opened for the source file. Note that buffers may be shared by multiple clients, so the returned buffer may have unsaved changes if it has been modified by another client.

        The client takes (potentially shared) ownership of the returned buffer and is responsible for releasing it when finished. The buffer will be disposed only after it is released by every owner. The buffer must not be accessed by clients which do not own it.

        A new object may be returned, even for the same underlying buffer, each time this method is invoked. For working copies, the relationship between the source file and the underlying working copy buffer does not change over the lifetime of a working copy.

        Parameters:
        sourceFile - not null
        Returns:
        a buffer opened for the source file (never null)
        Throws:
        org.eclipse.core.runtime.CoreException - if the source file does not exist or if an exception occurs while accessing its corresponding resource
      • getBuffer

        public static IBuffer getBuffer​(ISourceFile sourceFile,
                                        IContext context,
                                        org.eclipse.core.runtime.IProgressMonitor monitor)
                                 throws org.eclipse.core.runtime.CoreException
        Returns a buffer opened for the source file. Note that buffers may be shared by multiple clients, so the returned buffer may have unsaved changes if it has been modified by another client.

        The client takes (potentially shared) ownership of the returned buffer and is responsible for releasing it when finished. The buffer will be disposed only after it is released by every owner. The buffer must not be accessed by clients which do not own it.

        A new object may be returned, even for the same underlying buffer, each time this method is invoked. For working copies, the relationship between the source file and the underlying working copy buffer does not change over the lifetime of a working copy.

        Model implementations are encouraged to support the following standard options, which may be specified in the given context:

        • CREATE_BUFFER - Indicates whether a new buffer should be created if none already exists for the source file.
        Parameters:
        sourceFile - not null
        context - the operation context (not null)
        monitor - a progress monitor, or null if progress reporting is not desired. The caller must not rely on IProgressMonitor.done() having been called by the receiver
        Returns:
        a buffer opened for the source file. May return null if CREATE_BUFFER is false in the given context and there is no buffer currently opened for the source file
        Throws:
        org.eclipse.core.runtime.CoreException - if the source file does not exist or if an exception occurs while accessing its corresponding resource
        org.eclipse.core.runtime.OperationCanceledException - if this method is canceled