org.eclipse.handly.model

## Class ElementDeltas

- java.lang.Object
- - org.eclipse.handly.model.ElementDeltas

-     public class ElementDeltas
      extends java.lang.Object

  Provides static methods for generic access to `IElementDelta`s. Given a delta, clients can access the element that has changed, and any children that have changed.

  Note that, despite having a dependency on `IResourceDelta` and `IMarkerDelta`, this class can safely be used even when `org.eclipse.core.resources` bundle is not available. This is based on the "outward impression" of late resolution of symbolic references a JVM must provide according to the JVMS.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static IElementDelta[]` | `EMPTY_ARRAY` A zero-length array of the runtime type `IElementDelta[]`.

  - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static IElementDelta` | `findDelta(IElementDelta delta, IElement element)` Finds and returns the delta for the given element in a delta subtree (subtree root included), or `null` if no such delta can be found.
    `static IElementDelta[]` | `getAddedChildren(IElementDelta delta)` Returns element deltas for the immediate children that have been added.
    `static IElementDelta[]` | `getAffectedChildren(IElementDelta delta)` Returns element deltas for all affected (added, removed, or changed) immediate children.
    `static IElementDelta[]` | `getChangedChildren(IElementDelta delta)` Returns element deltas for the immediate children that have been changed.
    `static IElement` | `getElement(IElementDelta delta)` Returns the element that the delta describes a change to.
    `static long` | `getFlags(IElementDelta delta)` Returns flags which describe in more detail how an element has changed.
    `static int` | `getKind(IElementDelta delta)` Returns the kind of the element delta.
    `static org.eclipse.core.resources.IMarkerDelta[]` | `getMarkerDeltas(IElementDelta delta)` Returns the changes to markers on the corresponding resource of the delta's element.
    `static IElement` | `getMovedFromElement(IElementDelta delta)` Returns an element describing the delta's element before it was moved to its current location, or `null` if the `F_MOVED_FROM` change flag is not set.
    `static IElement` | `getMovedToElement(IElementDelta delta)` Returns an element describing the delta's element in its new location, or `null` if the `F_MOVED_TO` change flag is not set.
    `static IElementDelta[]` | `getRemovedChildren(IElementDelta delta)` Returns element deltas for the immediate children that have been removed.
    `static org.eclipse.core.resources.IResourceDelta[]` | `getResourceDeltas(IElementDelta delta)` Returns the changes to children of the delta element's corresponding resource that cannot be described in terms of element deltas.
    `static boolean` | `isEmpty(IElementDelta delta)` Returns whether the element delta is empty, i.e., represents an unchanged element.
    `static boolean` | `isNullOrEmpty(IElementDelta delta)` Returns whether the element delta is `null` or empty.
    `static boolean` | `isStructuralChange(IElementDelta delta)` Returns whether the element delta designates a structural change, i.e., a change that affects or might affect the element tree as opposed to only the element itself.
    `static java.lang.String` | `toString(IElementDelta delta, IContext context)` Returns a string representation of the element delta in a form suitable for debugging purposes.

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

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

- - ### Field Detail

    - #### EMPTY_ARRAY

          public static final IElementDelta[] EMPTY_ARRAY

      A zero-length array of the runtime type `IElementDelta[]`.

  - ### Method Detail

    - #### getElement

          public static IElement getElement(IElementDelta delta)

      Returns the element that the delta describes a change to.
      Parameters:
        `delta` - not `null`
      Returns:
        the element that the delta describes a change to (never `null`)

    - #### isEmpty

          public static boolean isEmpty(IElementDelta delta)

      Returns whether the element delta is empty, i.e., represents an unchanged element.
      Parameters:
        `delta` - not `null`
      Returns:
        `true` if the element delta is empty, and `false` otherwise

    - #### isNullOrEmpty

          public static boolean isNullOrEmpty(IElementDelta delta)

      Returns whether the element delta is `null` or empty. Convenience method.
      Parameters:
        `delta` - may be `null`
      Returns:
        `true` if the element delta is `null` or empty, and `false` otherwise

    - #### getKind

          public static int getKind(IElementDelta delta)

      Returns the kind of the element delta. Normally, one of `ADDED`, `REMOVED`, or `CHANGED`. Returns `NO_CHANGE` if, and only if, the delta is empty.
      Parameters:
        `delta` - not `null`
      Returns:
        the kind of the element delta

    - #### getFlags

          public static long getFlags(IElementDelta delta)

      Returns flags which describe in more detail how an element has changed. Such flags should be tested using the `&` operator. For example:

              if ((flags & F_CONTENT) != 0) // a content change

      Some change flags make sense for most models and are predefined in `IElementDeltaConstants`, while others are model-specific and are defined by the model implementor. The range for model-specific change flags starts from `1L << 32` and includes the upper 32 bits of the `long` value. The lower 32 bits are reserved for predefined generic change flags.

      Move operations are indicated by special change flags. If an element is moved from A to B (with no other changes to A or B), then A will have kind `REMOVED`, with flag `F_MOVED_TO`, and `getMovedToElement` on A will return the handle for B. B will have kind `ADDED`, with flag `F_MOVED_FROM`, and `getMovedFromElement` on B will return the handle for A. (Note that the handle for A in this case represents an element that no longer exists.)

      Parameters:
        `delta` - not `null`
      Returns:
        flags that describe how an element has changed

    - #### isStructuralChange

          public static boolean isStructuralChange(IElementDelta delta)

      Returns whether the element delta designates a structural change, i.e., a change that affects or might affect the element tree as opposed to only the element itself.
      Parameters:
        `delta` - may be `null`
      Returns:
        `true` if the element delta designates a structural change, and `false` otherwise

    - #### findDelta

          public static IElementDelta findDelta(IElementDelta delta,
                                                IElement element)

      Finds and returns the delta for the given element in a delta subtree (subtree root included), or `null` if no such delta can be found.

      This is a convenience method to avoid manual traversal of the delta tree in cases where the listener is only interested in changes to particular elements. Calling this method will generally be faster than manually traversing the delta to a particular descendant.

      Parameters:
        `delta` - the delta at which to start the search (not `null`)
        `element` - the element of the desired delta (may be `null`, in which case `null` will be returned)
      Returns:
        the delta for the given element, or `null` if no such delta can be found

    - #### getAffectedChildren

          public static IElementDelta[] getAffectedChildren(IElementDelta delta)

      Returns element deltas for all affected (added, removed, or changed) immediate children.
      Parameters:
        `delta` - not `null`
      Returns:
        element deltas for all affected immediate children (never `null`). Clients must not modify the returned array.

    - #### getAddedChildren

          public static IElementDelta[] getAddedChildren(IElementDelta delta)

      Returns element deltas for the immediate children that have been added.
      Parameters:
        `delta` - not `null`
      Returns:
        element deltas for the immediate children that have been added (never `null`). Clients must not modify the returned array.

    - #### getRemovedChildren

          public static IElementDelta[] getRemovedChildren(IElementDelta delta)

      Returns element deltas for the immediate children that have been removed.
      Parameters:
        `delta` - not `null`
      Returns:
        element deltas for the immediate children that have been removed (never `null`). Clients must not modify the returned array.

    - #### getChangedChildren

          public static IElementDelta[] getChangedChildren(IElementDelta delta)

      Returns element deltas for the immediate children that have been changed.
      Parameters:
        `delta` - not `null`
      Returns:
        element deltas for the immediate children that have been changed (never `null`). Clients must not modify the returned array.

    - #### getMovedFromElement

          public static IElement getMovedFromElement(IElementDelta delta)

      Returns an element describing the delta's element before it was moved to its current location, or `null` if the `F_MOVED_FROM` change flag is not set.
      Parameters:
        `delta` - not `null`
      Returns:
        an element describing the delta's element before it was moved to its current location, or `null` if the `F_MOVED_FROM` change flag is not set
      See Also:
        `getMovedToElement(IElementDelta)`, `getFlags(IElementDelta)`

    - #### getMovedToElement

          public static IElement getMovedToElement(IElementDelta delta)

      Returns an element describing the delta's element in its new location, or `null` if the `F_MOVED_TO` change flag is not set.
      Parameters:
        `delta` - not `null`
      Returns:
        an element describing the delta's element in its new location, or `null` if the `F_MOVED_TO` change flag is not set
      See Also:
        `getMovedFromElement(IElementDelta)`, `getFlags(IElementDelta)`

    - #### getMarkerDeltas

          public static org.eclipse.core.resources.IMarkerDelta[] getMarkerDeltas(IElementDelta delta)

      Returns the changes to markers on the corresponding resource of the delta's element.

      Returns `null` if no markers changed. Note that this is an exception to the general convention of returning an empty array rather than `null`. This makes the method safe to call even when `org.eclipse.core.resources` bundle is not available.

      Note that marker deltas, like element deltas, are generally only valid for the dynamic scope of change notification. Clients must not hang on to these objects.

      Parameters:
        `delta` - not `null`
      Returns:
        the marker deltas, or `null` if none. Clients must not modify the returned array.

    - #### getResourceDeltas

          public static org.eclipse.core.resources.IResourceDelta[] getResourceDeltas(IElementDelta delta)

      Returns the changes to children of the delta element's corresponding resource that cannot be described in terms of element deltas.

      Returns `null` if there were no such changes. Note that this is an exception to the general convention of returning an empty array rather than `null`. This makes the method safe to call even when `org.eclipse.core.resources` bundle is not available.

      Note that resource deltas, like element deltas, are generally only valid for the dynamic scope of change notification. Clients must not hang on to these objects.

      Parameters:
        `delta` - not `null`
      Returns:
        the resource deltas, or `null` if none. Clients must not modify the returned array.

    - #### toString

          public static java.lang.String toString(IElementDelta delta,
                                                  IContext context)

      Returns a string representation of the element delta in a form suitable for debugging purposes. Clients can influence the result with format options specified in the given context; unrecognized options are ignored and an empty context is permitted.

      Model implementations are encouraged to support common options defined in `ToStringOptions` and interpret the `FORMAT_STYLE` as follows:

      - `FULL` - A full representation that lists affected children.
      - `LONG` - May be an alias for FULL.
      - `MEDIUM` - May be an alias for SHORT.
      - `SHORT` - A minimal representation that does not list affected children.
      Parameters:
        `delta` - not `null`
        `context` - not `null`
      Returns:
        a string representation of the element delta (never `null`)

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