Package org.eclipse.handly.model.impl.support

Interface ISourceFileImplSupport

All Superinterfaces:
IElement, IElementImpl, IElementImplExtension, IElementImplSupport, IModelManager.Provider, ISourceElement, ISourceElementImpl, ISourceElementImplSupport, ISourceFile, ISourceFileImpl, ISourceFileImplExtension
All Known Implementing Classes:
BaseSourceFile, FsSourceFile, SourceFile, WorkspaceSourceFile
public interface ISourceFileImplSupport extends ISourceElementImplSupport, ISourceFileImplExtension
A "trait-like" interface providing a skeletal implementation of 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.

  • Field Details

  • Method Details

    • defaultHashCode_

      default int defaultHashCode_()
      Description copied from interface: IElementImplSupport
      A default implementation of IElement.hashCode() cannot be provided in an interface, but clients can implement hashCode 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 in ISourceFileImplSupport 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 override hashCode directly.

      Specified by:
      defaultHashCode_ in interface IElementImplSupport
      Returns:
      a hash code value

    • defaultEquals_

      default boolean defaultEquals_(Object obj)
      Description copied from interface: IElementImplSupport
      A default implementation of IElement.equals(Object) cannot be provided in an interface, but clients can implement equals 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 in ISourceConstructImplSupport and ISourceFileImplSupport to also compare occurrence counts and underlying file objects respectively. This method is not intended to be replaced by clients; if necessary, clients should override equals directly.

      Specified by:
      defaultEquals_ in interface IElementImplSupport
      Parameters:
      obj - the object with which to compare
      Returns:
      true if this element is equal to the given object, and false otherwise

    • getFileObject_

      default Object 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 underlying IFile, this implementation returns the corresponding IFileStore (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 interface ISourceFileImpl
      Parameters:
      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 this 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 this 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

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

      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 interface ISourceFileImplExtension
      Parameters:
      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:
      true if this source file became a working copy, and false 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. Returns false 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 to ISourceFileImplExtension.releaseWorkingCopy_().

      Specified by:
      acquireExistingWorkingCopy_ in interface ISourceFileImplExtension
      Parameters:
      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 an existing working copy was acquired, and false 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 interface ISourceFileImplExtension
      Returns:
      true if this source file was switched from working copy mode back to its original mode, and false otherwise

    • getWorkingCopyContext_

      default IContext getWorkingCopyContext_()
      Description copied from interface: ISourceFileImplExtension
      Returns the context associated with the working copy, or null 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 interface ISourceFileImplExtension
      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 interface ISourceFileImpl
      Returns:
      true if this source file is a working copy, and false 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 interface ISourceFileImpl
      Returns:
      true if this source file needs reconciling, and false 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 interface ISourceFileImpl
      Parameters:
      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
      See Also:

    • getReconcileOperation_

      default ISourceFileImplSupport.ReconcileOperation 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 of ISourceFileImplSupport.ReconcileOperation is returned.

      Returns:
      a reconcile operation for this source file (never null)

    • newWorkingCopyContext_

      default IContext newWorkingCopyContext_(IContext context)
      Returns a context to be associated with a new working copy of this source file. The given operation context is propagated from the becomeWorkingCopy_(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 (never null)
      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 returns getFile_().exists(). Otherwise, if this source file has a corresponding IFileStore, this implementation returns getFileStore_().fetchInfo().exists(). Otherwise, an assertion error is thrown.

      Returns:
      true if the underlying file exists, and false otherwise

    • getFileSnapshotProvider_

      default ISnapshotProvider 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 corresponding IFileStore (if any). If there is neither underlying IFile nor corresponding IFileStore, 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 corresponding IFileStore (if any). If there is neither underlying IFile nor corresponding IFileStore, an assertion error is thrown. If CREATE_BUFFER is false in the given context and there is currently no buffer opened for the file, null is returned.

      Parameters:
      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 underlying file of this source file, or null if CREATE_BUFFER is false 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 opened
      org.eclipse.core.runtime.OperationCanceledException - if this method is canceled

    • validateExistence_

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

      This implementation does nothing if this source file is a working copy; otherwise, it throws a IElementImplSupport.newDoesNotExistException_() if the underlying file does not exist.

      Specified by:
      validateExistence_ in interface IElementImplSupport
      Parameters:
      context - the operation context (not null)
      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 supports IElementImplExtension and is not already open.

      Specified by:
      openParent_ in interface IElementImplSupport
      Parameters:
      context - the operation context (never null)
      monitor - a progress monitor (never null). The caller must not rely on IProgressMonitor.done() having been called by the receiver
      Throws:
      org.eclipse.core.runtime.CoreException - if an exception occurs while opening this element's parent
      org.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 to buildSourceStructure_(IContext, IProgressMonitor) with an appropriately augmented context. In particular, if the given context contains neither SOURCE_CONTENTS nor SOURCE_AST, it is augmented with SOURCE_CONTENTS and the corresponding SOURCE_SNAPSHOT obtained from the underlying file's stored contents. Also, performs some post-processing of created SourceElementBodys to complete their initialization, such as setting the source snapshot on which they are based.
      Specified by:
      buildStructure_ in interface IElementImplSupport
      Parameters:
      context - the operation context (not null)
      monitor - a progress monitor (not null). The caller must not rely on IProgressMonitor.done() having been called by the receiver
      Throws:
      org.eclipse.core.runtime.CoreException - if the structure could not be determined
      org.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 the IElementImplSupport.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 or SOURCE_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 which SOURCE_AST was created or SOURCE_CONTENTS was obtained. The snapshot may expire.
      Parameters:
      context - the operation context (not null)
      monitor - a progress monitor (not null). The caller must not rely on IProgressMonitor.done() having been called by the receiver
      Throws:
      org.eclipse.core.runtime.CoreException - if the structure could not be determined
      org.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:

      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 interface IElementImplExtension
      Specified by:
      close_ in interface IElementImplSupport
      Parameters:
      context - the operation context (not null)

    • toStringName_

      default void toStringName_(StringBuilder builder, IContext context)
      Specified by:
      toStringName_ in interface IElementImplSupport