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.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `ISourceFileImplSupport.NotifyingReconcileOperation` Reconciles a working copy and sends out a delta notification indicating the nature of the change of the working copy since the last time it was reconciled.
    `static class` | `ISourceFileImplSupport.ReconcileOperation` Reconciles a working copy.

    - ### Nested classes/interfaces inherited from interface org.eclipse.handly.model.impl.IElementImplExtension

      `IElementImplExtension.CloseHint`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Property<java.lang.Object>` | `SOURCE_AST` Specifies the source AST.
    `static Property<java.lang.String>` | `SOURCE_CONTENTS` Specifies the source string.
    `static Property<ISnapshot>` | `SOURCE_SNAPSHOT` Specifies the source snapshot.

    - ### Fields inherited from interface org.eclipse.handly.model.impl.support.IElementImplSupport

      `NEW_ELEMENTS, NO_BODY`

    - ### Fields inherited from interface org.eclipse.handly.model.impl.IElementImplExtension

      `CLOSE_HINT, FORCE_OPEN`

    - ### Fields inherited from interface org.eclipse.handly.model.impl.ISourceFileImplExtension

      `WORKING_COPY_BUFFER, WORKING_COPY_CALLBACK, WORKING_COPY_CONTEXT`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default 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.
    `default 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).
    `void` | `buildSourceStructure_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)` Creates and initializes bodies for this element and for each of its descendant elements according to options specified in the given context.
    `default void` | `buildStructure_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)` This implementation delegates to `buildSourceStructure_(IContext, IProgressMonitor)` with an appropriately augmented context.
    `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.
    `default boolean` | `defaultEquals_(java.lang.Object obj)` A default implementation of `IElement.equals(Object)` cannot be provided in an interface, but clients can implement `equals` by delegating to this default method.
    `default int` | `defaultHashCode_()` A default implementation of `IElement.hashCode()` cannot be provided in an interface, but clients can implement `hashCode` by delegating to this default method.
    `default boolean` | `fileExists_()` Returns whether the underlying file exists.
    `default IBuffer` | `getBuffer_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)` Returns a buffer opened for this source file.
    `default IBuffer` | `getFileBuffer_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)` Returns a buffer opened for the underlying file of this source file.
    `default java.lang.Object` | `getFileObject_()` Returns the underlying file object, if any.
    `default ISnapshotProvider` | `getFileSnapshotProvider_()` Returns a snapshot provider for the underlying file's stored contents.
    `default ISourceFileImplSupport.ReconcileOperation` | `getReconcileOperation_()` Returns a reconcile operation for this source file.
    `default IContext` | `getWorkingCopyContext_()` Returns the context associated with the working copy, or `null` if this source file is not a working copy.
    `default boolean` | `isWorkingCopy_()` Returns whether this source file is a working copy.
    `default boolean` | `needsReconciling_()` Returns whether this source file needs reconciling.
    `default IContext` | `newWorkingCopyContext_(IContext context)` Returns a context to be associated with a new working copy of this source file.
    `default void` | `openParent_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)` Opens the parent element if necessary.
    `default void` | `reconcile_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)` Reconciles this source file.
    `default boolean` | `releaseWorkingCopy_()` Relinquishes an independent ownership of the working copy by decrementing an internal counter.
    `default void` | `toStringName_(java.lang.StringBuilder builder, IContext context)`
    `default void` | `validateExistence_(IContext context)` Validates that this element may be "opened", i.e., begin existence in the model.
    `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.

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

      `checkInRange, getSourceElementAt_, getSourceElementAt_, getSourceElementInfo_`

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

      `canEqual_, exists_, findBody_, getChildrenFromBody_, getElementManager_, getModel_, isOpenable_, newDoesNotExistException_, open_, peekAtBody_, remove_, removing_, toString_, toStringAncestors_, toStringBody_, toStringChildren_`

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

      `close_, getBody_, getBody_, getChildren_`

    - ### Methods inherited from interface org.eclipse.handly.model.impl.support.IModelManager.Provider

      `getModelManager_`

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

      `getFile_, getFileStore_`

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

      `equals, hashCode`

- - ### Field Detail

    - #### SOURCE_AST

          static final Property<java.lang.Object> SOURCE_AST

      Specifies the source AST.
      See Also:
        `buildSourceStructure_(IContext, IProgressMonitor)`

    - #### SOURCE_CONTENTS

          static final Property<java.lang.String> SOURCE_CONTENTS

      Specifies the source string.
      See Also:
        `buildSourceStructure_(IContext, IProgressMonitor)`

    - #### SOURCE_SNAPSHOT

          static final Property<ISnapshot> SOURCE_SNAPSHOT

      Specifies the source snapshot.
      See Also:
        `buildSourceStructure_(IContext, IProgressMonitor)`

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

      - `ISourceFileImplExtension.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.
      - `ISourceFileImplExtension.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.
      - `ISourceFileImplExtension.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 `ISourceFileImplExtension.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 `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)`

    - #### 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:
        `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 `SourceElementBody`s 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:

      - `IElementImplExtension.CLOSE_HINT` - Closing hint.

      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_(java.lang.StringBuilder builder,
                                     IContext context)

      Specified by:
        `toStringName_` in interface `IElementImplSupport`

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