Interface IElementImplSupport
-
- All Superinterfaces:
IElement,IElementImpl,IElementImplExtension,IModelManager.Provider
- All Known Subinterfaces:
ISourceConstructImplSupport,ISourceElementImplSupport,ISourceFileImplSupport
- All Known Implementing Classes:
BaseSourceFile,Element,FsSourceFile,SourceConstruct,SourceFile,WorkspaceSourceFile
public interface IElementImplSupport extends IElementImplExtension, IModelManager.Provider
A "trait-like" interface providing a skeletal implementation ofIElementImplExtensionto minimize the effort required to implement that interface. Clients may implement ("mix in") this interface directly or extendElement.In general, the members first defined in this interface are not intended to be referenced outside the subtype hierarchy.
- Restriction:
- This interface is not intended to be extended by clients.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface org.eclipse.handly.model.impl.IElementImplExtension
IElementImplExtension.CloseHint
-
-
Field Summary
Fields Modifier and Type Field Description static Property<java.util.Map<IElement,java.lang.Object>>NEW_ELEMENTSA map containing element handle/body relationships.static java.lang.ObjectNO_BODYSpecial-purpose value for thebodyargument of thetoStringBody_(StringBuilder, Object, IContext)method; indicates that information about the body is not relevant.-
Fields inherited from interface org.eclipse.handly.model.impl.IElementImplExtension
CLOSE_HINT, FORCE_OPEN
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description voidbuildStructure_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)Creates and initializes bodies for this element and for each non-openablechild element (and their non-openable children, recursively).default booleancanEqual_(java.lang.Object obj)Returns whether this element can equal the given object.default voidclose_(IContext context)Closes this element if, and only if, the current state of this element permits closing according to options specified in the given context.default booleandefaultEquals_(java.lang.Object obj)A default implementation ofIElement.equals(Object)cannot be provided in an interface, but clients can implementequalsby delegating to this default method.default intdefaultHashCode_()A default implementation ofIElement.hashCode()cannot be provided in an interface, but clients can implementhashCodeby delegating to this default method.default booleanexists_()Returns whether this element exists in the model.default java.lang.ObjectfindBody_()Returns the cached body for this element, ornullif none.default IElement[]getChildrenFromBody_(java.lang.Object body)Given a body for this element, returns the immediate children.default ElementManagergetElementManager_()Returns the element manager for this element.default IModelgetModel_()Returns the model that owns this element.default booleanisOpenable_()Returns whether this element is "openable".default org.eclipse.core.runtime.CoreExceptionnewDoesNotExistException_()Returns a new instance of generic "element does not exist" exception.default java.lang.Objectopen_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)Ensures that this element is open, i.e., it exists and is present in the body cache.default voidopenParent_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)Opens the parent element if necessary.default java.lang.ObjectpeekAtBody_()Returns the cached body for this element without disturbing cache ordering, ornullif none.default voidremove_(IContext context)Removes this element from the body cache according to options specified in the given context.default voidremoving_(java.lang.Object body)Informs this element that its body is going to be removed from the body cache.default java.lang.StringtoString_(IContext context)Returns a string representation of this element in a form suitable for debugging purposes.default voidtoStringAncestors_(java.lang.StringBuilder builder, IContext context)default voidtoStringBody_(java.lang.StringBuilder builder, java.lang.Object body, IContext context)default voidtoStringChildren_(java.lang.StringBuilder builder, java.lang.Object body, IContext context)default voidtoStringName_(java.lang.StringBuilder builder, IContext context)voidvalidateExistence_(IContext context)Validates that this element may be "opened", i.e., begin existence in the model.-
Methods inherited from interface org.eclipse.handly.model.impl.IElementImpl
equalsAndSameParentChain_, getChildrenOfType_, getHandleMemento_, getLocationUri_, getName_, getParent_, getResource_, getRoot_, toDisplayString_
-
Methods inherited from interface org.eclipse.handly.model.impl.IElementImplExtension
close_, getBody_, getBody_, getChildren_
-
Methods inherited from interface org.eclipse.handly.model.impl.support.IModelManager.Provider
getModelManager_
-
-
-
-
Field Detail
-
NEW_ELEMENTS
static final Property<java.util.Map<IElement,java.lang.Object>> NEW_ELEMENTS
A map containing element handle/body relationships.
-
NO_BODY
static final java.lang.Object NO_BODY
Special-purpose value for thebodyargument of thetoStringBody_(StringBuilder, Object, IContext)method; indicates that information about the body is not relevant.
-
-
Method Detail
-
defaultHashCode_
default int defaultHashCode_()
A default implementation ofIElement.hashCode()cannot be provided in an interface, but clients can implementhashCodeby delegating to this default method.By default, the hash code for an element is a combination of hash codes for its name and its parent element. This method is specialized in
ISourceConstructImplSupportto include the element's occurrence count, and inISourceFileImplSupportto return the hash code for the underlying file object, if there is one. This method is not intended to be replaced by clients; if necessary, clients should overridehashCodedirectly.- Returns:
- a hash code value
-
defaultEquals_
default boolean defaultEquals_(java.lang.Object obj)
A default implementation ofIElement.equals(Object)cannot be provided in an interface, but clients can implementequalsby delegating to this default method.By default, two elements that implement this interface are equal if they are identical or if they
can equaleach other and do have equal names and equal parents. This method is specialized inISourceConstructImplSupportandISourceFileImplSupportto also compare occurrence counts and underlying file objects respectively. This method is not intended to be replaced by clients; if necessary, clients should overrideequalsdirectly.- Parameters:
obj- the object with which to compare- Returns:
trueif this element is equal to the given object, andfalseotherwise
-
canEqual_
default boolean canEqual_(java.lang.Object obj)
Returns whether this element can equal the given object. If this method returnsfalse, theequalsmethod must also returnfalsefor the same argument object.This implementation compares run-time classes of the objects for equality; as such, it does not allow creating a subclass whose instances can equal superclass instances. Clients may provide their own implementation for this method and use a less discriminating technique such as
instanceofcheck.For details, see https://www.artima.com/pins1ed/object-equality.html#28.2, Pitfall #4.
- Parameters:
obj- notnull- Returns:
trueif this element can equal the given object, andfalseotherwise
-
getModel_
default IModel getModel_()
Returns the model that owns this element. This is a handle-only method.This implementation returns
getModelManager_().getModel().- Specified by:
getModel_in interfaceIElementImpl- Returns:
- the element's model (never
null)
-
getElementManager_
default ElementManager getElementManager_()
Returns the element manager for this element. The manager must be shared between all elements of a Handly-based model. Typical implementations would answer a model-specific singleton. This is a handle-only method.This implementation returns
getModelManager_().getElementManager().- Returns:
- the element manager for this element (never
null)
-
getChildrenFromBody_
default IElement[] getChildrenFromBody_(java.lang.Object body)
Given a body for this element, returns the immediate children.This implementation returns
((Body)body)..getChildren()- Specified by:
getChildrenFromBody_in interfaceIElementImplExtension- Parameters:
body- a body for this element (notnull)- Returns:
- the immediate children (never
null). Clients must not modify the returned array.
-
findBody_
default java.lang.Object findBody_()
Description copied from interface:IElementImplExtensionReturns the cached body for this element, ornullif none.- Specified by:
findBody_in interfaceIElementImplExtension- Returns:
- the cached body for this element, or
nullif none
-
peekAtBody_
default java.lang.Object peekAtBody_()
Description copied from interface:IElementImplExtensionReturns the cached body for this element without disturbing cache ordering, ornullif none.- Specified by:
peekAtBody_in interfaceIElementImplExtension- Returns:
- the cached body for this element, or
nullif none
-
exists_
default boolean exists_()
Returns whether this 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".
This implementation returns
trueif there is a cached body for this element, andfalseif this element has a parent and the parent does not exist; otherwise, it invokesvalidateExistence_to determine the result.- Specified by:
exists_in interfaceIElementImpl- Returns:
trueif this element exists in the model, andfalseif this element does not exist
-
validateExistence_
void validateExistence_(IContext context) throws org.eclipse.core.runtime.CoreException
Validates that this element may be "opened", i.e., begin existence in the model. For example, a necessary condition for element existence might be that the underlying resource exists.Note that ancestor elements may or may not exist; this method need not explicitly verify their existence.
- Parameters:
context- the operation context (notnull)- Throws:
org.eclipse.core.runtime.CoreException- if this element shall not exist- See Also:
newDoesNotExistException_()
-
newDoesNotExistException_
default org.eclipse.core.runtime.CoreException newDoesNotExistException_()
Returns a new instance of generic "element does not exist" exception. The exception's message identifies the non-existing element without giving any details about the reason for nonexistence.- Returns:
- a new "element does not exist" exception (never
null)
-
open_
default java.lang.Object open_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
Ensures that this element is open, i.e., it exists and is present in the body cache. Returns the cached body for this element.Implementations are encouraged to support the following standard options, which may be specified in the given context:
-
IElementImplExtension.FORCE_OPEN- Indicates whether to forcibly reopen this element if it is already open (i.e., already present in the body cache).
This implementation attempts to
openthe parent element first. Then, if this element isopenableand ispermittedto open, invokesbuildStructure_(IContext, IProgressMonitor)with an appropriately augmented context, acquires the element manager lock, updates the body cache with the built structure, and releases the lock. When this element is already open, the update may involve closing existing children or do nothing at all, depending on the value ofFORCE_OPEN. If this element is not openable and the openable parent did not create a body for this element, this implementation throws anewDoesNotExistException_().- Specified by:
open_in interfaceIElementImplExtension- Parameters:
context- the operation context (notnull)monitor- a progress monitor, ornullif progress reporting is not desired. The caller must not rely onIProgressMonitor.done()having been called by the receiver- Returns:
- the cached body for this element (never
null) - Throws:
org.eclipse.core.runtime.CoreException- if this element does not exist or if an exception occurs while accessing its corresponding resource
-
-
openParent_
default void openParent_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
Opens the parent element if necessary.This method is called internally; it is not intended to be invoked by clients.
This implementation attempts to
openthe parent element if it supportsIElementImplExtensionand is not already open.- Parameters:
context- the operation context (nevernull)monitor- a progress monitor (nevernull). The caller must not rely onIProgressMonitor.done()having been called by the receiver- Throws:
org.eclipse.core.runtime.CoreException- if an exception occurs while opening this element's parentorg.eclipse.core.runtime.OperationCanceledException- if this method is canceled- See Also:
open_(IContext, IProgressMonitor)
-
isOpenable_
default boolean isOpenable_()
Returns whether this element is "openable". Openable elements know how tobuildtheir structure and can beopenedone by one. In particular, there is no need to open an openable child when opening its parent. Non-openable elements rely on the openable parent to build their structure. Opening of a parent element opens all non-openable children at once.This implementation returns
true. Non-openable elements must override this method and returnfalse.- Returns:
trueif this element is openable, andfalseotherwise
-
buildStructure_
void buildStructure_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
Creates and initializes bodies for this element and for each non-openablechild element (and their non-openable children, recursively). Uses theNEW_ELEMENTSmap in the given context to associate the created bodies with their respective elements.Note that this method does not make sense and must not be called for non-openable elements -- they rely on the openable parent to build their structure.
- Parameters:
context- the operation context (notnull)monitor- a progress monitor (notnull). The caller must not rely onIProgressMonitor.done()having been called by the receiver- Throws:
org.eclipse.core.runtime.CoreException- if the structure could not be determinedorg.eclipse.core.runtime.OperationCanceledException- if this method is canceled
-
close_
default void close_(IContext context)
Closes this element if, and only if, the current state of this element permits closing according to options specified in the given context.Closing of an element removes its body from the body cache. In general, closing of a parent element also closes its children. If the current state of an open child element does not permit closing, the child element remains open, which generally does not prevent its parent from closing. Closing of an element which is not open has no effect.
Implementations are encouraged to support the following standard options, which may be specified in the given context:
-
IElementImplExtension.CLOSE_HINT- Closing hint.
After checking that the current state of this element permits closing, this implementation invokes
remove_(IContext)to actually close this element.- Specified by:
close_in interfaceIElementImplExtension- Parameters:
context- the operation context (notnull)
-
-
remove_
default void remove_(IContext context)
Removes this element from the body cache according to options specified in the given context. In general, not only removes the cached body for this element but also attempts to close this element's children. Does nothing if the cache contained no body for this element.This is a low-level operation, which removes this element's body and thus closes this element even if the current state of this element does not permit closing. Consider using a higher-level
close_(IContext)method.If there is a cached body for this element, this implementation invokes
removing_(Object)method to notify this element of the upcoming removal of its body, callsclose_(of(CLOSE_HINT, PARENT_CLOSING))for each of this element's children, then removes the cached body for this element, all while holding the element manager lock.- Parameters:
context- the operation context (notnull)
-
removing_
default void removing_(java.lang.Object body)
Informs this element that its body is going to be removed from the body cache. This method is called under the element manager lock.This method is called internally; it is not intended to be invoked by clients.
- Parameters:
body- the cached body for this element (nevernull)
-
toString_
default java.lang.String toString_(IContext context)
Description copied from interface:IElementImplReturns a string representation of this element in a form suitable for debugging purposes. Clients can influence the result with format options specified in the given context; unrecognized options are ignored and an empty context is permitted.Implementations are encouraged to support common options defined in
ToStringOptionsand interpret theFORMAT_STYLEas follows:- Specified by:
toString_in interfaceIElementImpl- Parameters:
context- notnull- Returns:
- a string representation of this element (never
null)
-
toStringAncestors_
default void toStringAncestors_(java.lang.StringBuilder builder, IContext context)
-
toStringChildren_
default void toStringChildren_(java.lang.StringBuilder builder, java.lang.Object body, IContext context)
-
toStringBody_
default void toStringBody_(java.lang.StringBuilder builder, java.lang.Object body, IContext context)
-
toStringName_
default void toStringName_(java.lang.StringBuilder builder, IContext context)
-
-