org.eclipse.handly.model.impl

## Interface IElementImplExtension

- All Superinterfaces:
    IElement, IElementImpl
  All Known Subinterfaces:
    IElementImplSupport, ISourceConstructImplSupport, ISourceElementImplSupport, ISourceFileImplSupport
  All Known Implementing Classes:
    BaseSourceFile, Element, FsSourceFile, SourceConstruct, SourceFile, WorkspaceSourceFile

      public interface IElementImplExtension
      extends IElementImpl

  Extension of `IElementImpl` that introduces the notion of element's cached body. `IElement`s may implement this interface.
  Restriction:
    This interface is not intended to be extended by clients.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `IElementImplExtension.CloseHint` Indicates reason for element closing.

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Property<IElementImplExtension.CloseHint>` | `CLOSE_HINT` Closing hint.
    `static Property<java.lang.Boolean>` | `FORCE_OPEN` Indicates whether to forcibly reopen this element if it is already open (i.e., already present in the body cache).

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `default void` | `close_()` Closes this element if, and only if, the current state of this element permits closing.
    `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.
    `java.lang.Object` | `findBody_()` Returns the cached body for this element, or `null` if none.
    `default java.lang.Object` | `getBody_()` Returns the cached body for this element.
    `default java.lang.Object` | `getBody_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)` Returns the cached body for this element.
    `default IElement[]` | `getChildren_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)` Returns the immediate children of this element.
    `IElement[]` | `getChildrenFromBody_(java.lang.Object body)` Given a body for this element, returns the immediate children.
    `java.lang.Object` | `open_(IContext context, org.eclipse.core.runtime.IProgressMonitor monitor)` Ensures that this element is open, i.e., it exists and is present in the body cache.
    `java.lang.Object` | `peekAtBody_()` Returns the cached body for this element without disturbing cache ordering, or `null` if none.

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

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

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

      `equals, hashCode`

- - ### Field Detail

    - #### FORCE_OPEN

          static final Property<java.lang.Boolean> FORCE_OPEN

      Indicates whether to forcibly reopen this element if it is already open (i.e., already present in the body cache). Default value: `false`.

      This property is for implementation purposes; it is not intended for use by general clients.

      See Also:
        `open_(IContext, IProgressMonitor)`

    - #### CLOSE_HINT

          static final Property<IElementImplExtension.CloseHint> CLOSE_HINT

      Closing hint.

      This property is for implementation purposes; it is not intended for use by general clients.

      See Also:
        `close_(IContext)`

  - ### Method Detail

    - #### getChildren_

          default IElement[] getChildren_(IContext context,
                                          org.eclipse.core.runtime.IProgressMonitor monitor)
                                   throws org.eclipse.core.runtime.CoreException

      Description copied from interface: `IElementImpl`
      Returns the immediate children of this element. Unless otherwise specified by the implementing element, the children are in no particular order.
      Specified by:
        `getChildren_` in interface `IElementImpl`
      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:
        the immediate children of this element (never `null`). Clients must not modify the returned array.
      Throws:
        `org.eclipse.core.runtime.CoreException` - if this element does not exist or if an exception occurs while accessing its corresponding resource

    - #### getChildrenFromBody_

          IElement[] getChildrenFromBody_(java.lang.Object body)

      Given a body for this element, returns the immediate children.
      Parameters:
        `body` - a body for this element (not `null`)
      Returns:
        the immediate children (never `null`). Clients must not modify the returned array.

    - #### findBody_

          java.lang.Object findBody_()

      Returns the cached body for this element, or `null` if none.
      Returns:
        the cached body for this element, or `null` if none

    - #### peekAtBody_

          java.lang.Object peekAtBody_()

      Returns the cached body for this element without disturbing cache ordering, or `null` if none.
      Returns:
        the cached body for this element, or `null` if none

    - #### getBody_

          default java.lang.Object getBody_()
                                     throws org.eclipse.core.runtime.CoreException

      Returns the cached body for this element. If this element is not already present in the body cache, attempts to `open` it. Shortcut to `getBody_(EMPTY_CONTEXT, null)`.
      Returns:
        the cached body for this element (never `null`)
      Throws:
        `org.eclipse.core.runtime.CoreException` - if this element does not exist or if an exception occurs while accessing its corresponding resource

    - #### getBody_

          default java.lang.Object getBody_(IContext context,
                                            org.eclipse.core.runtime.IProgressMonitor monitor)
                                     throws org.eclipse.core.runtime.CoreException

      Returns the cached body for this element. If this element is not already present in the body cache, attempts to `open` it propagating the given context.
      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:
        the cached body for this element (never `null`)
      Throws:
        `org.eclipse.core.runtime.CoreException` - if this element does not exist or if an exception occurs while accessing its corresponding resource
        `org.eclipse.core.runtime.OperationCanceledException` - if this method is canceled

    - #### open_

          java.lang.Object open_(IContext context,
                                 org.eclipse.core.runtime.IProgressMonitor monitor)
                          throws org.eclipse.core.runtime.CoreException

      Ensures that this element is open, i.e., it exists and is present in the body cache. Returns the cached body for this element.

      Implementations are encouraged to support the following standard options, which may be specified in the given context:

      - `FORCE_OPEN` - Indicates whether to forcibly reopen this element if it is already open (i.e., already present in the body cache).
      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:
        the cached body for this element (never `null`)
      Throws:
        `org.eclipse.core.runtime.CoreException` - if this element does not exist or if an exception occurs while accessing its corresponding resource
        `org.eclipse.core.runtime.OperationCanceledException` - if this method is canceled

    - #### close_

          default void close_()

      Closes this element if, and only if, the current state of this element permits closing.

      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.

      Shortcut to `close_(EMPTY_CONTEXT)`.

      See Also:
        `close_(IContext)`

    - #### close_

          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:

      - `CLOSE_HINT` - Closing hint.
      Parameters:
        `context` - the operation context (not `null`)

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