org.eclipse.handly.model.impl

## Interface ISourceFileImplExtension

- All Superinterfaces:
    IElement, IElementImpl, ISourceElement, ISourceElementImpl, ISourceFile, ISourceFileImpl
  All Known Subinterfaces:
    ISourceFileImplSupport
  All Known Implementing Classes:
    BaseSourceFile, FsSourceFile, SourceFile, WorkspaceSourceFile

      public interface ISourceFileImplExtension
      extends ISourceFileImpl

  Extension of `ISourceFileImpl` that introduces the notion of working copy. `ISourceFile`s may implement this interface.
  Restriction:
    This interface is not intended to be extended by clients.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Property<IBuffer>` | `WORKING_COPY_BUFFER` Specifies the working copy buffer.
    `static Property<IWorkingCopyCallback>` | `WORKING_COPY_CALLBACK` Specifies the working copy callback.
    `static Property<IContext>` | `WORKING_COPY_CONTEXT` Specifies the working copy context.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `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.
    `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).
    `IContext` | `getWorkingCopyContext_()` Returns the context associated with the working copy, or `null` if this source file is not a working copy.
    `boolean` | `releaseWorkingCopy_()` Relinquishes an independent ownership of the working copy by decrementing an internal counter.

    - ### Methods inherited from interface org.eclipse.handly.model.impl.ISourceFileImpl

      `getBuffer_, getFile_, getFileStore_, isWorkingCopy_, needsReconciling_, reconcile_`

    - ### Methods inherited from interface org.eclipse.handly.model.impl.ISourceElementImpl

      `getSourceElementAt_, getSourceElementInfo_`

    - ### Methods inherited from interface org.eclipse.handly.model.impl.IElementImpl

      `equalsAndSameParentChain_, exists_, getChildren_, getChildrenOfType_, getHandleMemento_, getLocationUri_, getModel_, getName_, getParent_, getResource_, getRoot_, toDisplayString_, toString_`

    - ### Methods inherited from interface org.eclipse.handly.model.IElement

      `equals, hashCode`

- - ### Field Detail

    - #### WORKING_COPY_BUFFER

          static final Property<IBuffer> WORKING_COPY_BUFFER

      Specifies the working copy buffer.
      See Also:
        `becomeWorkingCopy_(IContext, IProgressMonitor)`

    - #### WORKING_COPY_CALLBACK

          static final Property<IWorkingCopyCallback> WORKING_COPY_CALLBACK

      Specifies the working copy callback.
      See Also:
        `becomeWorkingCopy_(IContext, IProgressMonitor)`

    - #### WORKING_COPY_CONTEXT

          static final Property<IContext> WORKING_COPY_CONTEXT

      Specifies the working copy context. Default value: `EMPTY_CONTEXT`.
      See Also:
        `becomeWorkingCopy_(IContext, IProgressMonitor)`

  - ### Method Detail

    - #### becomeWorkingCopy_

          boolean becomeWorkingCopy_(IContext context,
                                     org.eclipse.core.runtime.IProgressMonitor monitor)
                              throws org.eclipse.core.runtime.CoreException

      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:

      - `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.
      - `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.
      - `WORKING_COPY_CONTEXT` - Specifies the working copy context. If set, the given context will be associated with the working copy and can be accessed via `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 `releaseWorkingCopy_()`.

      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
        `org.eclipse.core.runtime.OperationCanceledException` - if this method is canceled
      See Also:
        `acquireExistingWorkingCopy_(IProgressMonitor)`

    - #### acquireExistingWorkingCopy_

          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. 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 `releaseWorkingCopy_()`.

      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
      Throws:
        `org.eclipse.core.runtime.OperationCanceledException` - if this method is canceled
      See Also:
        `becomeWorkingCopy_(IContext, IProgressMonitor)`

    - #### releaseWorkingCopy_

          boolean releaseWorkingCopy_()

      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.

      Returns:
        `true` if this source file was switched from working copy mode back to its original mode, and `false` otherwise

    - #### getWorkingCopyContext_

          IContext getWorkingCopyContext_()

      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.

      Returns:
        the working copy context, or `null` if this source file is not a working copy

Copyright (c) 2014, 2020 1C-Soft LLC and others. Made available under the Eclipse Public License 2.0