Class Elements
IElement
s.
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
Modifier and TypeFieldDescriptionSpecifies a base snapshot.Indicates whether a new buffer should be created if none already exists.static final IElement[]
A zero-length array of the runtime typeIElement[]
.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 final ISourceElementInfo
A 'null object' indicating that no info is available for source element, e.g., because the element does not exist. -
Method Summary
Modifier and TypeMethodDescriptionstatic <T extends Collection<? super IElement>>
TcollectParentChain
(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 Collection<? super IElement>>
TcollectParentChainUntil
(IElement element, T collection, 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
Returns whether the element exists in the model.static void
fetchChildren
(IElement element, IContext context, ICollector<? super IElement> collector, org.eclipse.core.runtime.IProgressMonitor monitor) Adds the immediate children of the element to the given collector.static <T> void
fetchChildrenOfType
(IElement element, Class<T> type, IContext context, ICollector<? super T> collector, org.eclipse.core.runtime.IProgressMonitor monitor) Adds the immediate children of the element that have the given type to the given collector.static <T> T
findAncestorOfType
(IElement element, 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, Class<T> type, 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
(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
(Iterable<? extends IElement> elements, 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, 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, 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, Class<T> type, 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, 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, Predicate<? super IElement> filter, Predicate<? super IElement> until) Finds and returns the last element that matches the givenfilter
predicate starting from the given element (inclusive) and going up through the parent chain to the element matched by the givenuntil
predicate (exclusive).static IElement
findMatchingAncestor
(IElement element, 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, Predicate<? super IElement> filter, Predicate<? super IElement> until) Finds and returns the first element that matches the givenfilter
predicate starting from the given element (inclusive) and going up through the parent chain no further than the element matched by the givenuntil
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, Class<T> type) Returns the immediate children of the element that have the given type.static <T> T[]
getChildrenOfType
(IElement element, 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 underlyingIFile
, ornull
if the source file has no underlying file in the workspace.static org.eclipse.core.filesystem.IFileStore
getFileStore
(ISourceFile sourceFile) Returns the correspondingIFileStore
, ornull
if the source file has no corresponding file store.static String
getHandleMemento
(IElement element) Returns a string representation of the element handle that can be used to recreate the handle via the model'sIElementHandleFactory
.static URI
getLocationUri
(IElement element) Returns a file system location for the element.static IModel
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 inApiLevel
.static IContext
getModelContext
(IElement element) Returns a context which provides information and services pertaining to the element's model.static String
Returns the name of the element, ornull
if the element has no name.static IElement
Returns the immediate parent of the element, ornull
if the element has no parent.getParentChain
(IElement element) Returns anIterable
that starts from the given element (inclusive) and goes up through the parent chain to the root element (inclusive).getParentChainUntil
(IElement element, Predicate<? super IElement> until) Returns anIterable
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, ornull
if the element is not enclosed in a workspace resource.static IElement
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, ornull
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, ornull
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, ornull
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, orNO_SOURCE_ELEMENT_INFO
if no such info is available.static ISourceFile
getSourceFile
(IElement element) Returns the source file that contains the given element, ornull
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
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
(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
(Iterable<?> objects, Collection<? super IElement> elements, IModel model, Collection<? super org.eclipse.core.resources.IResource> resources, IElementHandleFactory elementHandleFactory) Splits the given objects into a collection ofIElement
s and a collection ofIResource
s, ignoring objects that are neither elements nor resources.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).streamParentChainUntil
(IElement element, 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 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 String
Returns a string representation of the element in a form suitable for debugging purposes.
-
Field Details
-
EMPTY_ARRAY
A zero-length array of the runtime typeIElement[]
. -
BASE_SNAPSHOT
Specifies a base snapshot. -
NO_SOURCE_ELEMENT_INFO
A 'null object' indicating that no info is available for source element, e.g., because the element does not exist.The instance methods return either
null
(if allowed by method contract) or an appropriate 'null object' (such as a zero-length array).- See Also:
-
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. Default value:false
. -
CREATE_BUFFER
Indicates whether a new buffer should be created if none already exists. Default value:true
.
-
-
Method Details
-
getName
Returns the name of the element, ornull
if the element has no name. This is a handle-only method.- Parameters:
element
- notnull
- Returns:
- the element name, or
null
if the element has no name
-
getParent
Returns the immediate parent of the element, ornull
if the element has no parent. This is a handle-only method.- Parameters:
element
- notnull
- Returns:
- the parent element, or
null
if the element has no parent
-
getRoot
Returns the root element for the element. Returns the element itself if it has no parent. This is a handle-only method.- Parameters:
element
- notnull
- Returns:
- the root element (never
null
)
-
getParentChain
Returns anIterable
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 benull
, in which case an empty iterable will be returned- Returns:
- an iterable representing the specified parent chain
(never
null
)
-
getParentChainUntil
public static Iterable<IElement> getParentChainUntil(IElement element, Predicate<? super IElement> until) Returns anIterable
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 isnull
, 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 benull
, in which case an empty iterable will be returneduntil
- may benull
- Returns:
- an iterable representing the specified parent chain
(never
null
)
-
streamParentChain
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 benull
, in which case an empty stream will be returned- Returns:
- a stream representing the specified parent chain
(never
null
)
-
streamParentChainUntil
public static Stream<IElement> streamParentChainUntil(IElement element, 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 isnull
, 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 benull
, in which case an empty stream will be returneduntil
- may benull
- Returns:
- a stream representing the specified parent chain
(never
null
)
-
collectParentChain
public static <T extends 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 benull
, in which case no elements will be added to the given collectioncollection
- notnull
- Returns:
- the given
collection
instance
-
collectParentChainUntil
public static <T extends Collection<? super IElement>> T collectParentChainUntil(IElement element, T collection, 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 isnull
, 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 benull
, in which case no elements will be added to the given collectioncollection
- notnull
until
- may benull
- Returns:
- the given
collection
instance
-
findMatchingAncestor
Finds and returns the first element that matches the given predicate starting from the given element (inclusive) and going up through the parent chain. Returnsnull
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 benull
, in which casenull
will be returnedfilter
- notnull
- Returns:
- the matching element, or
null
if no such element can be found
-
findMatchingAncestorUntil
public static IElement findMatchingAncestorUntil(IElement element, Predicate<? super IElement> filter, Predicate<? super IElement> until) Finds and returns the first element that matches the givenfilter
predicate starting from the given element (inclusive) and going up through the parent chain no further than the element matched by the givenuntil
predicate (exclusive). Returnsnull
if no such element can be found. If theuntil
predicate is not matched or isnull
, all ancestors will be included. If theuntil
predicate matches the given element,null
will be returned. This is a handle-only method.- Parameters:
element
- may benull
, in which casenull
will be returnedfilter
- notnull
until
- may benull
- Returns:
- the matching element, or
null
if no such element can be found
-
findAncestorOfType
Finds and returns the first element that has the given type starting from the given element (inclusive) and going up through the parent chain. Returnsnull
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 benull
, in which casenull
will be returnedtype
- notnull
- Returns:
- the matching element, or
null
if no such element can be found
-
findAncestorOfTypeUntil
public static <T> T findAncestorOfTypeUntil(IElement element, Class<T> type, 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). Returnsnull
if no such element can be found. If the predicate is not matched or isnull
, 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 benull
, in which casenull
will be returnedtype
- notnull
until
- may benull
- Returns:
- the matching element, or
null
if no such element can be found
-
findLastMatchingAncestor
public static IElement findLastMatchingAncestor(IElement element, 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). Returnsnull
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 benull
, in which casenull
will be returnedfilter
- notnull
- Returns:
- the matching element, or
null
if no such element can be found
-
findLastMatchingAncestorUntil
public static IElement findLastMatchingAncestorUntil(IElement element, Predicate<? super IElement> filter, Predicate<? super IElement> until) Finds and returns the last element that matches the givenfilter
predicate starting from the given element (inclusive) and going up through the parent chain to the element matched by the givenuntil
predicate (exclusive). Returnsnull
if no such element can be found. If theuntil
predicate is not matched or isnull
, all ancestors will be included. If theuntil
predicate matches the given element,null
will be returned. This is a handle-only method.- Parameters:
element
- may benull
, in which casenull
will be returnedfilter
- notnull
until
- may benull
- Returns:
- the matching element, or
null
if no such element can be found
-
findLastAncestorOfType
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). Returnsnull
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 benull
, in which casenull
will be returnedtype
- notnull
- Returns:
- the matching element, or
null
if no such element can be found
-
findLastAncestorOfTypeUntil
public static <T> T findLastAncestorOfTypeUntil(IElement element, Class<T> type, 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). Returnsnull
if no such element can be found. If the predicate is not matched or isnull
, 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 benull
, in which casenull
will be returnedtype
- notnull
until
- may benull
- Returns:
- the matching element, or
null
if no such element can be found
-
findCommonAncestor
Finds and returns the closest common ancestor of the given elements, viewing each element as its own ancestor. Returnsnull
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 benull
, in which casenull
will be returnedother
- may benull
, in which casenull
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, 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). Returnsnull
if no such element can be found. If the predicate is not matched or isnull
, 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 benull
, in which casenull
will be returnedother
- may benull
, in which casenull
will be returneduntil
- may benull
- Returns:
- the matching element, or
null
if no such element can be found
-
findCommonAncestor
Finds and returns the closest common ancestor of the given elements, viewing each element as its own ancestor. Returnsnull
if no such element can be found. This is a handle-only method.This method is equivalent to
findCommonAncestorUntil(elements, null)
.- Parameters:
elements
- notnull
, may contain nulls- Returns:
- the matching element, or
null
if no such element can be found
-
findCommonAncestorUntil
public static IElement findCommonAncestorUntil(Iterable<? extends IElement> elements, 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). Returnsnull
if no such element can be found. If the predicate is not matched or isnull
, 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
- notnull
, may contain nullsuntil
- may benull
- Returns:
- the matching element, or
null
if no such element can be found
-
isAncestorOf
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
- notnull
other
- may benull
, in which casefalse
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, andfalse
otherwise
-
removeDescendants
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
- notnull
, must not containnull
elements
-
equalsAndSameParentChain
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
- notnull
other
- may benull
- Returns:
true
if the elements are equal and belong to the same parent chain, andfalse
otherwise
-
getModel
Returns the model that owns the element. This is a handle-only method.- Parameters:
element
- notnull
- Returns:
- the element's model (never
null
)
-
isOfModel
Returns whether the element belongs to the given model. More formally, returnstrue
if, and only if,model.equals(getModel(element))
. This is a handle-only method.- Parameters:
element
- notnull
model
- notnull
- Returns:
true
if the element belongs to the given model, andfalse
otherwise
-
getModelContext
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
- notnull
- Returns:
- the model context for the element (never
null
)
-
getModelApiLevel
Returns the Handly API level supported by the element's model; one of the level constants declared inApiLevel
. This is a handle-only method.- Parameters:
element
- notnull
- Returns:
- the Handly API level supported by the element's model
-
getHandleMemento
Returns a string representation of the element handle that can be used to recreate the handle via the model'sIElementHandleFactory
. The format of the string is not specified, but the representation is stable across workbench sessions. This is a handle-only method.- Parameters:
element
- notnull
- Returns:
- the handle memento for the element, or
null
if the element is unable to provide a handle memento
-
getResource
Returns the innermost resource enclosing the element, ornull
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 whenorg.eclipse.core.resources
bundle is not available.- Parameters:
element
- notnull
- Returns:
- the innermost resource enclosing the element, or
null
if the element is not enclosed in a workspace resource
-
splitIntoElementsAndResources
public static void splitIntoElementsAndResources(Iterable<?> objects, Collection<? super IElement> elements, IModel model, Collection<? super org.eclipse.core.resources.IResource> resources, IElementHandleFactory elementHandleFactory) Splits the given objects into a collection ofIElement
s and a collection ofIResource
s, 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
- notnull
, may containnull
elementselements
- notnull
model
- may benull
. If notnull
, only elements belonging to the model will be added to theelements
collectionresources
- may benull
. Ifnull
, no checks forinstanceof IResource
will be doneelementHandleFactory
- may benull
. Ifnull
, resources will be added without first trying to translate them to elements
-
getLocationUri
Returns a file system location for the element. The resulting URI is suitable to passing toEFS.getStore(URI)
. Returnsnull
if no location can be determined.- Parameters:
element
- notnull
- Returns:
- a file system location for the element,
or
null
if no location can be determined
-
exists
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
- notnull
- Returns:
true
if the element exists in the model, andfalse
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
- notnull
- 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
- notnull
context
- the operation context (notnull
)monitor
- a progress monitor, ornull
if progress reporting is not desired. The caller must not rely onIProgressMonitor.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, 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
- notnull
type
- notnull
- 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, 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
- notnull
type
- notnull
context
- the operation context (notnull
)monitor
- a progress monitor, ornull
if progress reporting is not desired. The caller must not rely onIProgressMonitor.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
-
fetchChildren
public static void fetchChildren(IElement element, IContext context, ICollector<? super IElement> collector, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException Adds the immediate children of the element to the given collector. Unless otherwise specified by the parent element, the children are added in no particular order.- Parameters:
element
- notnull
context
- the operation context (notnull
)collector
- the element collector (notnull
)monitor
- a progress monitor, ornull
if progress reporting is not desired. The caller must not rely onIProgressMonitor.done()
having been called by the receiver- Throws:
org.eclipse.core.runtime.CoreException
- if the element does not exist or if an exception occurs while accessing its corresponding resourceorg.eclipse.core.runtime.OperationCanceledException
- if this method is canceled- Since:
- 1.5
-
fetchChildrenOfType
public static <T> void fetchChildrenOfType(IElement element, Class<T> type, IContext context, ICollector<? super T> collector, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException Adds the immediate children of the element that have the given type to the given collector. Unless otherwise specified by the parent element, the children are added in no particular order.- Parameters:
element
- notnull
type
- notnull
context
- the operation context (notnull
)collector
- the element collector (notnull
)monitor
- a progress monitor, ornull
if progress reporting is not desired. The caller must not rely onIProgressMonitor.done()
having been called by the receiver- Throws:
org.eclipse.core.runtime.CoreException
- if the element does not exist or if an exception occurs while accessing its corresponding resourceorg.eclipse.core.runtime.OperationCanceledException
- if this method is canceled- Since:
- 1.5
-
toString
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 theFORMAT_STYLE
as follows:- Parameters:
element
- notnull
context
- notnull
- Returns:
- a string representation of the element (never
null
)
-
toDisplayString
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 theFORMAT_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 aFULL
representation fully identifies the element within the model.- Parameters:
element
- notnull
context
- notnull
- 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, ornull
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 (notnull
)position
- a source position (0-based)base
- a snapshot on which the given position is based, ornull
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 resourceStaleSnapshotException
- 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, ornull
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, ornull
if the snapshot is unknown or does not matter.
- Parameters:
element
- a source element (notnull
)position
- a source position (0-based)context
- the operation context (notnull
)monitor
- a progress monitor, ornull
if progress reporting is not desired. The caller must not rely onIProgressMonitor.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 resourceStaleSnapshotException
- 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, ornull
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 (notnull
)position
- a source position (0-based)base
- a snapshot on which the given position is based, ornull
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
- notnull
- Returns:
- an
ISourceElementInfo
for the element (nevernull
) - 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
- notnull
context
- the operation context (notnull
)monitor
- a progress monitor, ornull
if progress reporting is not desired. The caller must not rely onIProgressMonitor.done()
having been called by the receiver- Returns:
- an
ISourceElementInfo
for the element (nevernull
) - Throws:
org.eclipse.core.runtime.CoreException
- if the element does not exist or if an exception occurs while accessing its corresponding resource
-
getSourceElementInfo2
Returns an object holding cached structure and properties for the source element, orNO_SOURCE_ELEMENT_INFO
if no such info is available.- Parameters:
element
- notnull
- Returns:
- an
ISourceElementInfo
for the element (nevernull
)
-
getSourceFile
Returns the source file that contains the given element, ornull
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 benull
, in which casenull
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
- notnull
monitor
- a progress monitor, ornull
if progress reporting is not desired. The caller must not rely onIProgressMonitor.done()
having been called by the receiver- Returns:
true
if the call completed successfully, andfalse
in case of a failure- Throws:
org.eclipse.core.runtime.OperationCanceledException
- if this method is canceled
-
getFile
Returns the underlyingIFile
, ornull
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
- notnull
- Returns:
- the underlying
IFile
, ornull
if the source file has no underlying file in the workspace
-
getFileStore
Returns the correspondingIFileStore
, ornull
if the source file has no corresponding file store.- Parameters:
sourceFile
- notnull
- Returns:
- the corresponding
IFileStore
, ornull
if this source file has no corresponding file store - Since:
- 1.3
-
isWorkingCopy
Returns whether the source file is a working copy.- Parameters:
sourceFile
- notnull
- Returns:
true
if the source file is a working copy, andfalse
otherwise
-
needsReconciling
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
- notnull
- Returns:
true
if the source file needs reconciling, andfalse
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
- notnull
monitor
- a progress monitor, ornull
if progress reporting is not desired. The caller must not rely onIProgressMonitor.done()
having been called by the receiver- Throws:
org.eclipse.core.runtime.CoreException
- if the working copy could not be reconciledorg.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
- notnull
context
- the operation context (notnull
)monitor
- a progress monitor, ornull
if progress reporting is not desired. The caller must not rely onIProgressMonitor.done()
having been called by the receiver- Throws:
org.eclipse.core.runtime.CoreException
- if the working copy could not be reconciledorg.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
- notnull
- 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
- notnull
context
- the operation context (notnull
)monitor
- a progress monitor, ornull
if progress reporting is not desired. The caller must not rely onIProgressMonitor.done()
having been called by the receiver- Returns:
- a buffer opened for the source file. May return
null
ifCREATE_BUFFER
isfalse
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 resourceorg.eclipse.core.runtime.OperationCanceledException
- if this method is canceled
-
-