Package org.eclipse.handly.ui.texteditor

## Class DeferredSourceFileDocumentProvider

- java.lang.Object
- - org.eclipse.ui.editors.text.TextFileDocumentProvider
  - - org.eclipse.handly.ui.texteditor.DeferredSourceFileDocumentProvider

- All Implemented Interfaces:
    `org.eclipse.ui.editors.text.IStorageDocumentProvider`, `org.eclipse.ui.texteditor.IDocumentProvider`, `org.eclipse.ui.texteditor.IDocumentProviderExtension`, `org.eclipse.ui.texteditor.IDocumentProviderExtension2`, `org.eclipse.ui.texteditor.IDocumentProviderExtension3`, `org.eclipse.ui.texteditor.IDocumentProviderExtension4`, `org.eclipse.ui.texteditor.IDocumentProviderExtension5`

      public abstract class DeferredSourceFileDocumentProvider
      extends org.eclipse.ui.editors.text.TextFileDocumentProvider

  In contrast to `SourceFileDocumentProvider`, which acquires a working copy in the calling thread, this class defers working copy acquisition to a worker thread.
  Since:
    1.5

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected static class` | `DeferredSourceFileDocumentProvider.SourceFileInfo` | Subclass of `FileInfo` that can retain a reference to a source file.

    - ### Nested classes/interfaces inherited from class org.eclipse.ui.editors.text.TextFileDocumentProvider

      `org.eclipse.ui.editors.text.TextFileDocumentProvider.DocumentProviderOperation, org.eclipse.ui.editors.text.TextFileDocumentProvider.FileBufferListener, org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo, org.eclipse.ui.editors.text.TextFileDocumentProvider.NullProvider`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DeferredSourceFileDocumentProvider()` | Creates a new source file document provider with no parent.
    `DeferredSourceFileDocumentProvider​(org.eclipse.ui.texteditor.IDocumentProvider parent)` | Creates a new source file document provider with the given parent.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `protected boolean` | `acquireWorkingCopy​(ISourceFile sourceFile, java.lang.Object element, org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo info, org.eclipse.core.runtime.IProgressMonitor monitor)` | Attempts to acquire a working copy for the given source file.
    `protected org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo` | `createEmptyFileInfo()`
    `protected org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo` | `createFileInfo​(java.lang.Object element)`
    `protected void` | `disposeFileInfo​(java.lang.Object element, org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo info)`
    `ISourceFile` | `getConnectedSourceFile​(java.lang.Object element)` | Returns the source file managed for the given element, or `null` if this provider does not currently manage a source file for the element.
    `ISourceFile` | `getConnectedSourceFile​(org.eclipse.jface.text.IDocument document)` | Returns the source file managed for the given document, or `null` if this provider does not currently manage a source file for the document.
    `ISourceFile[]` | `getConnectedSourceFiles()` | Returns all source files that are currently managed by this provider.
    `protected abstract ISourceFile` | `getSourceFile​(java.lang.Object element)` | Returns the source file that corresponds to the given element.
    `protected void` | `releaseWorkingCopy​(ISourceFile workingCopy, java.lang.Object element, org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo info)` | Releases the given working copy that was acquired via a call to `acquireWorkingCopy`.

    - ### Methods inherited from class org.eclipse.ui.editors.text.TextFileDocumentProvider

      `aboutToChange, addElementStateListener, canSaveDocument, changed, commitFileBuffer, computeSchedulingRule, connect, createAnnotationModel, createFileFromDocument, createSaveOperation, disconnect, executeOperation, fireElementStateChangeFailed, fireElementStateChanging, getAnnotationModel, getConnectedElementsIterator, getContentType, getDefaultEncoding, getDocument, getElements, getEncoding, getFileInfo, getFileInfosIterator, getFileStore, getModificationStamp, getOperationRunner, getParentProvider, getProgressMonitor, getStatus, getSynchronizationStamp, getSystemFile, handleCoreException, isDeleted, isModifiable, isNotSynchronizedException, isReadOnly, isStateValidated, isSynchronized, isSystemFileReadOnly, mustSaveDocument, removeElementStateListener, resetDocument, saveDocument, setCanSaveDocument, setEncoding, setParentDocumentProvider, setProgressMonitor, setUpSynchronization, synchronize, updateStateCache, validateState`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DeferredSourceFileDocumentProvider

          public DeferredSourceFileDocumentProvider()

      Creates a new source file document provider with no parent.

    - #### DeferredSourceFileDocumentProvider

          public DeferredSourceFileDocumentProvider​(org.eclipse.ui.texteditor.IDocumentProvider parent)

      Creates a new source file document provider with the given parent.
      Parameters:
        `parent` - the parent document provider

  - ### Method Detail

    - #### getConnectedSourceFile

          public ISourceFile getConnectedSourceFile​(java.lang.Object element)

      Returns the source file managed for the given element, or `null` if this provider does not currently manage a source file for the element.

      This implementation returns the source file retained by the file info for the given element. The file info is obtained via `TextFileDocumentProvider.getFileInfo(Object)`.

      Parameters:
        `element` - the element for which to find the source file, or `null`
      Returns:
        the source file managed for the given element, or `null` if none

    - #### getConnectedSourceFile

          public ISourceFile getConnectedSourceFile​(org.eclipse.jface.text.IDocument document)

      Returns the source file managed for the given document, or `null` if this provider does not currently manage a source file for the document.

      Note: An implementation of this method may go through the list of source files and test whether the source file buffer's document equals the given document. Therefore, this method should not be used in performance critical code.

      This implementation returns the source file retained by the file info for the given document. The file info is found by iterating over this provider's file info objects via `TextFileDocumentProvider.getFileInfosIterator()` and testing whether the document of the file info's text file buffer equals the given document.

      Parameters:
        `document` - the document for which to find the source file, or `null`
      Returns:
        the source file managed for the given document, or `null` if none

    - #### getConnectedSourceFiles

          public ISourceFile[] getConnectedSourceFiles()

      Returns all source files that are currently managed by this provider.

      This implementation iterates over this provider's file info objects via `TextFileDocumentProvider.getFileInfosIterator()` and collects the source files they retain.

      Returns:
        the source files currently managed by this provider (never `null`)

    - #### getSourceFile

          protected abstract ISourceFile getSourceFile​(java.lang.Object element)

      Returns the source file that corresponds to the given element.
      Parameters:
        `element` - the element
      Returns:
        the source file that corresponds to the given element, or `null` if none

    - #### createEmptyFileInfo

          protected org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo createEmptyFileInfo()

      This implementation returns a new instance of `SourceFileInfo`.

      Overrides:
        `createEmptyFileInfo` in class `org.eclipse.ui.editors.text.TextFileDocumentProvider`

    - #### createFileInfo

          protected org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo createFileInfo​(java.lang.Object element)
                                                                                          throws org.eclipse.core.runtime.CoreException

      This implementation invokes the superclass implementation to create the file info object. If the created object is an instance of `SourceFileInfo`, it stores a reference to the corresponding `source file` in the created file info, and then attempts to `acquire` a working copy for the source file asynchronously.

      Overrides:
        `createFileInfo` in class `org.eclipse.ui.editors.text.TextFileDocumentProvider`
      Throws:
        `org.eclipse.core.runtime.CoreException`

    - #### disposeFileInfo

          protected void disposeFileInfo​(java.lang.Object element,
                                         org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo info)

      This implementation invokes the superclass implementation after trying to `release` the working copy retained by the given file info object.

      Overrides:
        `disposeFileInfo` in class `org.eclipse.ui.editors.text.TextFileDocumentProvider`

    - #### acquireWorkingCopy

          protected boolean acquireWorkingCopy​(ISourceFile sourceFile,
                                               java.lang.Object element,
                                               org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo info,
                                               org.eclipse.core.runtime.IProgressMonitor monitor)
                                        throws org.eclipse.core.runtime.CoreException

      Attempts to acquire a working copy for the given source file. The working copy acquired by this method must be released eventually via a call to `releaseWorkingCopy`.

      If the given source file implements `ISourceFileImplExtension`, this implementation invokes ``becomeWorkingCopy_`(EMPTY_CONTEXT, monitor)` on it and returns `true`. Otherwise, `false` is returned.

      Parameters:
        `sourceFile` - the source file
        `element` - the element
        `info` - the element info
        `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 a working copy has been acquired; `false` if no working copy can be acquired for the given source file
      Throws:
        `org.eclipse.core.runtime.CoreException` - if the working copy could not be acquired successfully
        `org.eclipse.core.runtime.OperationCanceledException` - if this method is canceled

    - #### releaseWorkingCopy

          protected void releaseWorkingCopy​(ISourceFile workingCopy,
                                            java.lang.Object element,
                                            org.eclipse.ui.editors.text.TextFileDocumentProvider.FileInfo info)

      Releases the given working copy that was acquired via a call to `acquireWorkingCopy`.

      This implementation invokes `((ISourceFileImplExtension)workingCopy).`releaseWorkingCopy_()``.

      Parameters:
        `workingCopy` - the working copy to release
        `element` - the element
        `info` - the element info