Interface ISourceFileImplSupport

    • Method Detail

      • 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_​(java.lang.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 java.lang.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:
        ISourceFileImpl.getFile_(), ISourceFileImpl.getFileStore_()
      • 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:
        ISourceFileImplExtension.acquireExistingWorkingCopy_(IProgressMonitor)
      • 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:
        ISourceFileImplExtension.becomeWorkingCopy_(IContext, IProgressMonitor)
      • 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:
        IWorkingCopyCallback.needsReconciling()
      • 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:
        IWorkingCopyCallback.reconcile(IContext, IProgressMonitor)
      • 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:
        getWorkingCopyContext_()
      • 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:
        INotificationManager
      • 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:
        IElementImplSupport.newDoesNotExistException_()
      • 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:
        IElementImplSupport.open_(IContext, IProgressMonitor)
      • 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)