Interface ISourceFileImplSupport
- All Superinterfaces:
IElement
,IElementImpl
,IElementImplExtension
,IElementImplSupport
,IModelManager.Provider
,ISourceElement
,ISourceElementImpl
,ISourceElementImplSupport
,ISourceFile
,ISourceFileImpl
,ISourceFileImplExtension
- All Known Implementing Classes:
BaseSourceFile
,FsSourceFile
,SourceFile
,WorkspaceSourceFile
ISourceFileImplExtension
to minimize the effort required to implement
that interface. Clients may implement ("mix in") this interface directly or
extend a class in the SourceFile
hierarchy.
In general, the members first defined in this interface are not intended to be referenced outside the subtype hierarchy.
If a notification manager is registered in the model context,
this implementation will take advantage of it to send out working copy
notifications. See workingCopyModeChanged_()
and ISourceFileImplSupport.NotifyingReconcileOperation
.
- Restriction:
- This interface is not intended to be extended by clients.
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic class
Reconciles a working copy and sends out a delta notification indicating the nature of the change of the working copy since the last time it was reconciled.static class
Reconciles a working copy.Nested classes/interfaces inherited from interface org.eclipse.handly.model.impl.IElementImplExtension
IElementImplExtension.CloseHint
-
Field Summary
Modifier and TypeFieldDescriptionSpecifies the source AST.Specifies the source string.Specifies the source snapshot.Fields inherited from interface org.eclipse.handly.model.impl.IElementImplExtension
CLOSE_HINT, FORCE_OPEN
Fields inherited from interface org.eclipse.handly.model.impl.support.IElementImplSupport
NEW_ELEMENTS, NO_BODY
Fields inherited from interface org.eclipse.handly.model.impl.ISourceFileImplExtension
WORKING_COPY_BUFFER, WORKING_COPY_CALLBACK, WORKING_COPY_CONTEXT
-
Method Summary
Modifier and TypeMethodDescriptiondefault boolean
acquireExistingWorkingCopy_
(org.eclipse.core.runtime.IProgressMonitor monitor) If this source file is already in working copy mode, acquires a new independent ownership of the working copy by incrementing an internal counter.default boolean
becomeWorkingCopy_
(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) If this source file is not already in working copy mode, switches it into a working copy, associates it with a working copy buffer, and acquires an independent ownership of the working copy (and, hence, of the working copy buffer).void
buildSourceStructure_
(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) Creates and initializes bodies for this element and for each of its descendant elements according to options specified in the given context.default void
buildStructure_
(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) This implementation delegates tobuildSourceStructure_(IContext, IProgressMonitor)
with an appropriately augmented context.default void
Closes this element if, and only if, the current state of this element permits closing according to options specified in the given context.default boolean
defaultEquals_
(Object obj) A default implementation ofIElement.equals(Object)
cannot be provided in an interface, but clients can implementequals
by delegating to this default method.default int
A default implementation ofIElement.hashCode()
cannot be provided in an interface, but clients can implementhashCode
by delegating to this default method.default boolean
Returns whether the underlying file exists.default IBuffer
getBuffer_
(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) Returns a buffer opened for this source file.default IBuffer
getFileBuffer_
(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) Returns a buffer opened for the underlying file of this source file.default Object
Returns the underlying file object, if any.default ISnapshotProvider
Returns a snapshot provider for the underlying file's stored contents.Returns a reconcile operation for this source file.default IContext
Returns the context associated with the working copy, ornull
if this source file is not a working copy.default boolean
Returns whether this source file is a working copy.default boolean
Returns whether this source file needs reconciling.default IContext
newWorkingCopyContext_
(IContext context) Returns a context to be associated with a new working copy of this source file.default void
openParent_
(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) Opens the parent element if necessary.default void
reconcile_
(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) Reconciles this source file.default boolean
Relinquishes an independent ownership of the working copy by decrementing an internal counter.default void
toStringName_
(StringBuilder builder, IContext context) default void
validateExistence_
(IContext context) Validates that this element may be "opened", i.e., begin existence in the model.default void
Informs this source file about a working copy mode change: either the source file became a working copy or reverted back from the working copy mode.Methods inherited from interface org.eclipse.handly.model.impl.IElementImpl
equalsAndSameParentChain_, fetchChildren_, fetchChildrenOfType_, 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.IElementImplSupport
canEqual_, exists_, findBody_, getChildrenFromBody_, getElementManager_, getModel_, isOpenable_, newDoesNotExistException_, open_, peekAtBody_, remove_, removing_, toString_, toStringAncestors_, toStringBody_, toStringChildren_
Methods inherited from interface org.eclipse.handly.model.impl.support.IModelManager.Provider
getModelManager_
Methods inherited from interface org.eclipse.handly.model.impl.support.ISourceElementImplSupport
getSourceElementAt_, getSourceElementAt_, getSourceElementInfo_
Methods inherited from interface org.eclipse.handly.model.impl.ISourceFileImpl
getFile_, getFileStore_
-
Field Details
-
SOURCE_AST
Specifies the source AST. -
SOURCE_CONTENTS
Specifies the source string. -
SOURCE_SNAPSHOT
Specifies the source snapshot.
-
-
Method Details
-
defaultHashCode_
default int defaultHashCode_()Description copied from interface:IElementImplSupport
A default implementation ofIElement.hashCode()
cannot be provided in an interface, but clients can implementhashCode
by 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
ISourceConstructImplSupport
to include the element's occurrence count, and inISourceFileImplSupport
to 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 overridehashCode
directly.- Specified by:
defaultHashCode_
in interfaceIElementImplSupport
- Returns:
- a hash code value
-
defaultEquals_
Description copied from interface:IElementImplSupport
A default implementation ofIElement.equals(Object)
cannot be provided in an interface, but clients can implementequals
by delegating to this default method.By default, two elements that implement this interface are equal if they are identical or if they
can equal
each other and do have equal names and equal parents. This method is specialized inISourceConstructImplSupport
andISourceFileImplSupport
to also compare occurrence counts and underlying file objects respectively. This method is not intended to be replaced by clients; if necessary, clients should overrideequals
directly.- Specified by:
defaultEquals_
in interfaceIElementImplSupport
- Parameters:
obj
- the object with which to compare- Returns:
true
if this element is equal to the given object, andfalse
otherwise
-
getFileObject_
Returns the underlying file object, if any. The relationship between a source file and its underlying file object does not change.This implementation returns the underlying
IFile
, if any. If there is no underlyingIFile
, this implementation returns the correspondingIFileStore
(if any), on the assumption that the relationship between this source file and the file store does not change.- Returns:
- the underlying file object, or
null
if none - Since:
- 1.3
- See Also:
-
getBuffer_
default IBuffer getBuffer_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException Returns a buffer opened for this 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.
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 this source file.
This implementation delegates to
getFileBuffer_(IContext, IProgressMonitor)
if this source file is not a working copy; otherwise, it returns the working copy buffer.- Specified by:
getBuffer_
in interfaceISourceFileImpl
- Parameters:
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 this 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 this source file does not exist or if an exception occurs while accessing its corresponding resourceorg.eclipse.core.runtime.OperationCanceledException
- if this method is canceled
-
-
becomeWorkingCopy_
default boolean becomeWorkingCopy_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException Description copied from interface:ISourceFileImplExtension
If this source file is not already in working copy mode, switches it into a working copy, associates it with a working copy buffer, and acquires an independent ownership of the working copy (and, hence, of the working copy buffer). Performs atomically.In working copy mode, the source file's structure and properties shall no longer correspond to the underlying resource contents and must no longer be updated by a resource delta processor. Instead, the source file's structure and properties can be explicitly
reconciled
with the current contents of the working copy buffer.This method supports the following options, which may be specified in the given context:
-
ISourceFileImplExtension.WORKING_COPY_BUFFER
- Specifies the working copy buffer. If not set, a default buffer for this source file will be used for the working copy. -
ISourceFileImplExtension.WORKING_COPY_CALLBACK
- Specifies the working copy callback. If set, the given callback must be a new instance: callbacks may not be shared or reused between working copies. -
ISourceFileImplExtension.WORKING_COPY_CONTEXT
- Specifies the working copy context. If set, the given context will be associated with the working copy and can be accessed viaISourceFileImplExtension.getWorkingCopyContext_()
method.
If the source file was already in working copy mode, this method acquires a new independent ownership of the working copy by incrementing an internal counter; the given context is ignored.
Each call to this method that did not throw an exception must ultimately be followed by exactly one call to
ISourceFileImplExtension.releaseWorkingCopy_()
.- Specified by:
becomeWorkingCopy_
in interfaceISourceFileImplExtension
- Parameters:
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:
true
if this source file became a working copy, andfalse
if it was already in working copy mode- Throws:
org.eclipse.core.runtime.CoreException
- if the working copy could not be created- See Also:
-
-
acquireExistingWorkingCopy_
default boolean acquireExistingWorkingCopy_(org.eclipse.core.runtime.IProgressMonitor monitor) Description copied from interface:ISourceFileImplExtension
If this source file is already in working copy mode, acquires a new independent ownership of the working copy by incrementing an internal counter. Returnsfalse
if this source file is not a working copy. Performs atomically.Each successful call to this method that did not return
false
must ultimately be followed by exactly one call toISourceFileImplExtension.releaseWorkingCopy_()
.- Specified by:
acquireExistingWorkingCopy_
in interfaceISourceFileImplExtension
- Parameters:
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 an existing working copy was acquired, andfalse
if this source file is not a working copy- See Also:
-
releaseWorkingCopy_
default boolean releaseWorkingCopy_()Description copied from interface:ISourceFileImplExtension
Relinquishes an independent ownership of the working copy by decrementing an internal counter. If there are no remaining owners of the working copy, switches this source file from working copy mode back to its original mode and releases the working copy buffer. Performs atomically.Each independent ownership of the working copy must ultimately end with exactly one call to this method. Clients which do not own the working copy must not call this method.
- Specified by:
releaseWorkingCopy_
in interfaceISourceFileImplExtension
- Returns:
true
if this source file was switched from working copy mode back to its original mode, andfalse
otherwise
-
getWorkingCopyContext_
Description copied from interface:ISourceFileImplExtension
Returns the context associated with the working copy, ornull
if this source file is not a working copy. The context, as a set of bindings, and its association with the working copy do not change over the lifetime of the working copy.The returned context is composed of the context explicitly
specified
when creating the working copy and an intrinsic context of the working copy itself, in that order.- Specified by:
getWorkingCopyContext_
in interfaceISourceFileImplExtension
- Returns:
- the working copy context, or
null
if this source file is not a working copy
-
isWorkingCopy_
default boolean isWorkingCopy_()Description copied from interface:ISourceFileImpl
Returns whether this source file is a working copy.- Specified by:
isWorkingCopy_
in interfaceISourceFileImpl
- Returns:
true
if this source file is a working copy, andfalse
otherwise
-
needsReconciling_
default boolean needsReconciling_()Returns whether this 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.This implementation delegates to the namesake method of the working copy callback, provided that this source file is a working copy.
- Specified by:
needsReconciling_
in interfaceISourceFileImpl
- Returns:
true
if this source file needs reconciling, andfalse
otherwise- See Also:
-
reconcile_
default void reconcile_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException Reconciles this source file. Does nothing if the source file is not in working copy mode.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.
This implementation delegates to the namesake method of the working copy callback, provided that this source file is a working copy.
- Specified by:
reconcile_
in interfaceISourceFileImpl
- Parameters:
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- See Also:
-
-
getReconcileOperation_
Returns a reconcile operation for this source file.This method is called internally; it is not intended to be invoked by clients.
This implementation returns a new instance of
ISourceFileImplSupport.NotifyingReconcileOperation
if there is a notification manager registered in the model context; otherwise, a new instance ofISourceFileImplSupport.ReconcileOperation
is returned.- Returns:
- a reconcile operation for this source file
(never
null
)
-
newWorkingCopyContext_
Returns a context to be associated with a new working copy of this source file. The given operation context is propagated from thebecomeWorkingCopy_(IContext, IProgressMonitor)
method.The returned context is composed of the context explicitly
specified
when creating the working copy and an intrinsic context of the working copy itself, in that order.This method is called internally; it is not intended to be invoked by clients.
This implementation returns
context.getOrDefault(WORKING_COPY_CONTEXT)
.- Parameters:
context
- the operation context (nevernull
)- Returns:
- the working copy context (never
null
) - See Also:
-
workingCopyModeChanged_
default void workingCopyModeChanged_()Informs this source file about a working copy mode change: either the source file became a working copy or reverted back from the working copy mode.This method is called internally; it is not intended to be invoked by clients.
This implementation sends out a delta notification indicating the nature of the working copy mode change, provided that a notification manager is registered in the model context.
- See Also:
-
fileExists_
default boolean fileExists_()Returns whether the underlying file exists.If this source file has an underlying
IFile
, this implementation returnsgetFile_().exists()
. Otherwise, if this source file has a correspondingIFileStore
, this implementation returnsgetFileStore_().fetchInfo().exists()
. Otherwise, an assertion error is thrown.- Returns:
true
if the underlying file exists, andfalse
otherwise
-
getFileSnapshotProvider_
Returns a snapshot provider for the underlying file's stored contents.The client takes (potentially shared) ownership of the returned provider and is responsible for releasing it. The provider will be disposed only after it is released by every owner. The provider must not be accessed by clients which do not own it.
This implementation returns a snapshot provider for the stored contents of the underlying
IFile
or, if this source file has no underlying file in the workspace, of the correspondingIFileStore
(if any). If there is neither underlyingIFile
nor correspondingIFileStore
, an assertion error is thrown.- Returns:
- a snapshot provider for the underlying file's stored contents
(never
null
)
-
getFileBuffer_
default IBuffer getFileBuffer_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException Returns a buffer opened for the underlying file of this 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. 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.
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 underlying file.
This implementation returns a buffer opened for the underlying
IFile
or, if this source file has no underlying file in the workspace, for the correspondingIFileStore
(if any). If there is neither underlyingIFile
nor correspondingIFileStore
, an assertion error is thrown. IfCREATE_BUFFER
isfalse
in the given context and there is currently no buffer opened for the file,null
is returned.- Parameters:
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 underlying file of this source file,
or
null
ifCREATE_BUFFER
isfalse
in the given context and there is currently no buffer opened for that file - Throws:
org.eclipse.core.runtime.CoreException
- if the buffer could not be openedorg.eclipse.core.runtime.OperationCanceledException
- if this method is canceled
-
-
validateExistence_
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.
This implementation does nothing if this source file is a working copy; otherwise, it throws a
IElementImplSupport.newDoesNotExistException_()
if the underlying file does notexist
.- Specified by:
validateExistence_
in interfaceIElementImplSupport
- Parameters:
context
- the operation context (notnull
)- Throws:
org.eclipse.core.runtime.CoreException
- if this element shall not exist- See Also:
-
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 does nothing if this source file is a working copy; otherwise, it attempts to
open
the parent element if it supportsIElementImplExtension
and is not already open.- Specified by:
openParent_
in interfaceIElementImplSupport
- 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:
-
buildStructure_
default void buildStructure_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException This implementation delegates tobuildSourceStructure_(IContext, IProgressMonitor)
with an appropriately augmented context. In particular, if the given context contains neitherSOURCE_CONTENTS
norSOURCE_AST
, it is augmented withSOURCE_CONTENTS
and the correspondingSOURCE_SNAPSHOT
obtained from the underlying file'sstored contents
. Also, performs some post-processing of createdSourceElementBody
s to complete their initialization, such as setting the source snapshot on which they are based.- Specified by:
buildStructure_
in interfaceIElementImplSupport
- 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
-
buildSourceStructure_
void buildSourceStructure_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException Creates and initializes bodies for this element and for each of its descendant elements according to options specified in the given context. Uses theIElementImplSupport.NEW_ELEMENTS
map in the given context to associate the created bodies with their respective elements.The following context options, if simultaneously present, must be mutually consistent:
-
SOURCE_AST
- Specifies the AST to use when building the structure. The AST is safe to read in the dynamic context of this method call, but must not be modified. -
SOURCE_CONTENTS
- Specifies the source string to use when building the structure.
At least one of
SOURCE_AST
orSOURCE_CONTENTS
must have a non-null value in the given context.The given context may provide additional data that this method can use, including the following:
-
SOURCE_SNAPSHOT
- Specifies the source snapshot from whichSOURCE_AST
was created orSOURCE_CONTENTS
was obtained. The snapshot may expire.
- 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_
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
IElementImplSupport.remove_(IContext)
to actually close this element.Note that a working copy is never permitted to close.
- Specified by:
close_
in interfaceIElementImplExtension
- Specified by:
close_
in interfaceIElementImplSupport
- Parameters:
context
- the operation context (notnull
)
-
-
toStringName_
- Specified by:
toStringName_
in interfaceIElementImplSupport
-