Package 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
  Description
  `static final Property<IBuffer>`
  `WORKING_COPY_BUFFER`
  Specifies the working copy buffer.
  `static final Property<IWorkingCopyCallback>`
  `WORKING_COPY_CALLBACK`
  Specifies the working copy callback.
  `static final Property<IContext>`
  `WORKING_COPY_CONTEXT`
  Specifies the working copy context.

- ## Method Summary

  Modifier and Type
  Method
  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.IElement

  `equals, hashCode`

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

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

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

  `getSourceElementAt_, getSourceElementInfo_`

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

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

- ## Field Details

  - ### 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 Details

  - ### 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