Package org.eclipse.handly.model.impl.support

# Class ElementDelta

java.lang.Object
org.eclipse.handly.model.impl.support.ElementDelta

All Implemented Interfaces:
  `IElementDelta`, `IElementDeltaImpl`

public class ElementDelta extends Object implements IElementDeltaImpl
A complete implementation of `IElementDeltaImpl`. To create a delta tree, use `ElementDelta.Builder`.

Note that, despite having a dependency on `IResourceDelta` and `IMarkerDelta`, this class can 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.

Clients can use this class as it stands or subclass it as circumstances warrant. Clients that subclass this class should consider registering an appropriate `ElementDelta.Factory` in the model context. Subclasses that introduce new fields should consider extending the `copyFrom_` method.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `ElementDelta.Builder`
  Builds a tree of `ElementDelta` objects based on elementary changes.
  `static interface`
  `ElementDelta.Factory`
  Represents a factory for creating instances of `ElementDelta`.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ElementDelta(IElement element)`
  Constructs an initially empty delta for the given element.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `protected void`
  `addAffectedChild_(ElementDelta child)`
  Adds the given delta as an affected child of this delta if permitted by the current state of this delta.
  `protected void`
  `addResourceDelta_(org.eclipse.core.resources.IResourceDelta resourceDelta)`
  Adds the given resource delta to the collection of resource deltas of this delta if permitted by the current state of this delta.
  `protected void`
  `copyFrom_(ElementDelta delta, boolean init)`
  Copies data from the given delta to this delta; the given delta is not modified in any way.
  `final ElementDelta`
  `findDelta_(IElement element)`
  Finds and returns the delta for the given element in this delta subtree (subtree root included), or `null` if no such delta can be found.
  `final ElementDelta[]`
  `getAddedChildren_()`
  Returns element deltas for the immediate children that have been added.
  `final ElementDelta[]`
  `getAffectedChildren_()`
  Returns element deltas for all affected (added, removed, or changed) immediate children.
  `final ElementDelta[]`
  `getChangedChildren_()`
  Returns element deltas for the immediate children that have been changed.
  `final IElement`
  `getElement_()`
  Returns the element that this delta describes a change to.
  `final long`
  `getFlags_()`
  Returns flags which describe in more detail how an element has changed.
  `final int`
  `getKind_()`
  Returns the kind of this element delta.
  `final org.eclipse.core.resources.IMarkerDelta[]`
  `getMarkerDeltas_()`
  Returns the changes to markers on the corresponding resource of this delta's element.
  `final IElement`
  `getMovedFromElement_()`
  Returns an element describing this delta's element before it was moved to its current location, or `null` if the `F_MOVED_FROM` change flag is not set.
  `final IElement`
  `getMovedToElement_()`
  Returns an element describing this delta's element in its new location, or `null` if the `F_MOVED_TO` change flag is not set.
  `final ElementDelta[]`
  `getRemovedChildren_()`
  Returns element deltas for the immediate children that have been removed.
  `final org.eclipse.core.resources.IResourceDelta[]`
  `getResourceDeltas_()`
  Returns the changes to children of the element's corresponding resource that cannot be described in terms of element deltas.
  `protected void`
  `insertSubTree_(ElementDelta delta)`
  Based on the given delta, creates a delta tree that can be directly parented by this delta and `adds` the created tree as an affected child of this delta.
  `protected void`
  `mergeWith_(ElementDelta delta)`
  Merges this delta with the given delta; the given delta is not modified in any way.
  `protected boolean`
  `needsChildIndex_()`
  Returns whether an index needs to be used for child lookup.
  `protected ElementDelta`
  `newDelta_(IElement element)`
  Returns a new, initially empty delta for the given element.
  `protected void`
  `setAffectedChildren_(ElementDelta[] children)`
  Sets the affected children for this delta.
  `protected void`
  `setFlags_(long flags)`
  Sets the flags for this delta.
  `protected void`
  `setKind_(int kind)`
  Sets the kind of this delta.
  `protected void`
  `setMarkerDeltas_(org.eclipse.core.resources.IMarkerDelta[] markerDeltas)`
  Sets the marker deltas for this delta.
  `protected void`
  `setMovedFromElement_(IElement movedFromElement)`
  Sets an element describing this delta's element before it was moved to its current location.
  `protected void`
  `setMovedToElement_(IElement movedToElement)`
  Sets an element describing this delta's element in its new location.
  `protected void`
  `setResourceDeltas_(org.eclipse.core.resources.IResourceDelta[] resourceDeltas)`
  Sets the resource deltas for this delta.
  `String`
  `toString()`
  `String`
  `toString_(IContext context)`
  Returns a string representation of this element delta in a form suitable for debugging purposes.
  `protected void`
  `toStringChildren_(StringBuilder builder, IContext context)`
  `protected boolean`
  `toStringFlags_(StringBuilder builder, IContext context)`
  Appends a string representation for this delta's flags to the given string builder.
  `protected void`
  `toStringKind_(StringBuilder builder, IContext context)`
  `protected void`
  `toStringResourceDeltas_(StringBuilder builder, IContext context)`

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

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

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

  `isEmpty_`

- ## Constructor Details

  - ### ElementDelta

    public ElementDelta(IElement element)
    Constructs an initially empty delta for the given element.
    Parameters:
      `element` - not `null`
    See Also:
      - `ElementDelta.Builder`

- ## Method Details

  - ### getElement_

    public final IElement getElement_()
    Description copied from interface: `IElementDeltaImpl`
    Returns the element that this delta describes a change to.
    Specified by:
      `getElement_` in interface `IElementDeltaImpl`
    Returns:
      the element that this delta describes a change to (never `null`)

  - ### getKind_

    public final int getKind_()
    Description copied from interface: `IElementDeltaImpl`
    Returns the kind of this element delta. Normally, one of `ADDED`, `REMOVED`, or `CHANGED`. Returns `NO_CHANGE` if, and only if, the delta is empty.
    Specified by:
      `getKind_` in interface `IElementDeltaImpl`
    Returns:
      the kind of this element delta

  - ### getFlags_

    public final long getFlags_()
    Description copied from interface: `IElementDeltaImpl`
    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 `IElementDeltaImpl.getMovedToElement_()` on A will return the handle for B. B will have kind `ADDED`, with flag `F_MOVED_FROM`, and `IElementDeltaImpl.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.)

    Specified by:
      `getFlags_` in interface `IElementDeltaImpl`
    Returns:
      flags that describe how an element has changed

  - ### findDelta_

    public final ElementDelta findDelta_(IElement element)
    Description copied from interface: `IElementDeltaImpl`
    Finds and returns the delta for the given element in this 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.

    Specified by:
      `findDelta_` in interface `IElementDeltaImpl`
    Parameters:
      `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 final ElementDelta[] getAffectedChildren_()
    Returns element deltas for all affected (added, removed, or changed) immediate children.

    This implementation returns an array of exactly the same runtime type as the array given in the most recent call to `setAffectedChildren_`.

    Specified by:
      `getAffectedChildren_` in interface `IElementDeltaImpl`
    Returns:
      element deltas for all affected immediate children (never `null`). Clients must not modify the returned array.

  - ### getAddedChildren_

    public final ElementDelta[] getAddedChildren_()
    Returns element deltas for the immediate children that have been added.

    This implementation returns an array of exactly the same runtime type as the array given in the most recent call to `setAffectedChildren_`.

    Specified by:
      `getAddedChildren_` in interface `IElementDeltaImpl`
    Returns:
      element deltas for the immediate children that have been added (never `null`). Clients must not modify the returned array.

  - ### getRemovedChildren_

    public final ElementDelta[] getRemovedChildren_()
    Returns element deltas for the immediate children that have been removed.

    This implementation returns an array of exactly the same runtime type as the array given in the most recent call to `setAffectedChildren_`.

    Specified by:
      `getRemovedChildren_` in interface `IElementDeltaImpl`
    Returns:
      element deltas for the immediate children that have been removed (never `null`). Clients must not modify the returned array.

  - ### getChangedChildren_

    public final ElementDelta[] getChangedChildren_()
    Returns element deltas for the immediate children that have been changed.

    This implementation returns an array of exactly the same runtime type as the array given in the most recent call to `setAffectedChildren_`.

    Specified by:
      `getChangedChildren_` in interface `IElementDeltaImpl`
    Returns:
      element deltas for the immediate children that have been changed (never `null`). Clients must not modify the returned array.

  - ### getMovedFromElement_

    public final IElement getMovedFromElement_()
    Description copied from interface: `IElementDeltaImpl`
    Returns an element describing this delta's element before it was moved to its current location, or `null` if the `F_MOVED_FROM` change flag is not set.
    Specified by:
      `getMovedFromElement_` in interface `IElementDeltaImpl`
    Returns:
      an element describing this 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:
      - `IElementDeltaImpl.getMovedToElement_()`
      - `IElementDeltaImpl.getFlags_()`

  - ### getMovedToElement_

    public final IElement getMovedToElement_()
    Description copied from interface: `IElementDeltaImpl`
    Returns an element describing this delta's element in its new location, or `null` if the `F_MOVED_TO` change flag is not set.
    Specified by:
      `getMovedToElement_` in interface `IElementDeltaImpl`
    Returns:
      an element describing this delta's element in its new location, or `null` if the `F_MOVED_TO` change flag is not set
    See Also:
      - `IElementDeltaImpl.getMovedFromElement_()`
      - `IElementDeltaImpl.getFlags_()`

  - ### getMarkerDeltas_

    public final org.eclipse.core.resources.IMarkerDelta[] getMarkerDeltas_()
    Description copied from interface: `IElementDeltaImpl`
    Returns the changes to markers on the corresponding resource of this 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.

    Specified by:
      `getMarkerDeltas_` in interface `IElementDeltaImpl`
    Returns:
      the marker deltas, or `null` if none. Clients must not modify the returned array.

  - ### getResourceDeltas_

    public final org.eclipse.core.resources.IResourceDelta[] getResourceDeltas_()
    Description copied from interface: `IElementDeltaImpl`
    Returns the changes to children of the 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.

    Specified by:
      `getResourceDeltas_` in interface `IElementDeltaImpl`
    Returns:
      the resource deltas, or `null` if none. Clients must not modify the returned array.

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### toString_

    public String toString_(IContext context)
    Description copied from interface: `IElementDeltaImpl`
    Returns a string representation of this 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.

    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.
    Specified by:
      `toString_` in interface `IElementDeltaImpl`
    Parameters:
      `context` - not `null`
    Returns:
      a string representation of this element delta (never `null`)

  - ### toStringChildren_

    protected void toStringChildren_(StringBuilder builder, IContext context)

  - ### toStringResourceDeltas_

    protected void toStringResourceDeltas_(StringBuilder builder, IContext context)

  - ### toStringKind_

    protected void toStringKind_(StringBuilder builder, IContext context)

  - ### toStringFlags_

    protected boolean toStringFlags_(StringBuilder builder, IContext context)
    Appends a string representation for this delta's flags to the given string builder.
    Parameters:
      `builder` - a string builder to append the delta flags to
      `context` - not `null`
    Returns:
      `true` if a flag was appended to the builder, and `false` if the builder was not modified by this method
    See Also:
      - `getFlags_()`

  - ### newDelta_

    protected ElementDelta newDelta_(IElement element)
    Returns a new, initially empty delta for the given element.

    This implementation uses `ElementDelta.Factory` registered in the element's model context. If no delta factory is registered in the model context, a new instance of this class (i.e., `ElementDelta`) is returned.

    Parameters:
      `element` - not `null`
    Returns:
      a new, initially empty delta for the given element (never `null`)

  - ### needsChildIndex_

    protected boolean needsChildIndex_()
    Returns whether an index needs to be used for child lookup.
    Returns:
      `true` if the child index needs to be used, and `false` otherwise

  - ### setKind_

    protected void setKind_(int kind)
    Sets the kind of this delta.

    This is a low-level mutator method. In particular, it is the caller's responsibility to ensure validity of the given value.

    Parameters:
      `kind` - the delta kind
    See Also:
      - `getKind_()`

  - ### setFlags_

    protected void setFlags_(long flags)
    Sets the flags for this delta.

    This is a low-level mutator method. In particular, it is the caller's responsibility to ensure validity of the given value.

    Parameters:
      `flags` - the delta flags
    See Also:
      - `getFlags_()`

  - ### setMovedFromElement_

    protected void setMovedFromElement_(IElement movedFromElement)
    Sets an element describing this delta's element before it was moved to its current location.

    This is a low-level mutator method. In particular, it is the caller's responsibility to set appropriate kind and flags for this delta.

    Parameters:
      `movedFromElement` - an element describing this delta's element before it was moved to its current location
    See Also:
      - `getMovedFromElement_()`

  - ### setMovedToElement_

    protected void setMovedToElement_(IElement movedToElement)
    Sets an element describing this delta's element in its new location.

    This is a low-level mutator method. In particular, it is the caller's responsibility to set appropriate kind and flags for this delta.

    Parameters:
      `movedToElement` - an element describing this delta's element in its new location
    See Also:
      - `getMovedToElement_()`

  - ### setMarkerDeltas_

    protected void setMarkerDeltas_(org.eclipse.core.resources.IMarkerDelta[] markerDeltas)
    Sets the marker deltas for this delta. Clients must not modify the given array afterwards.

    This is a low-level mutator method. In particular, it is the caller's responsibility to set appropriate kind and flags for this delta.

    Parameters:
      `markerDeltas` - the marker deltas
    See Also:
      - `getMarkerDeltas_()`

  - ### setResourceDeltas_

    protected void setResourceDeltas_(org.eclipse.core.resources.IResourceDelta[] resourceDeltas)
    Sets the resource deltas for this delta. Clients must not modify the given array afterwards.

    This is a low-level mutator method. In particular, it is the caller's responsibility to set appropriate kind and flags for this delta.

    Parameters:
      `resourceDeltas` - the resource deltas
    See Also:
      - `getResourceDeltas_()`

  - ### addResourceDelta_

    protected void addResourceDelta_(org.eclipse.core.resources.IResourceDelta resourceDelta)
    Adds the given resource delta to the collection of resource deltas of this delta if permitted by the current state of this delta. Note that in contrast to `setResourceDeltas_`, this method can change this delta's kind and flags as appropriate.

    If the kind of this delta is `ADDED` or `REMOVED`, this implementation returns without adding the given resource delta; otherwise, it sets the kind of this delta to `CHANGED` and adds the `F_CONTENT` change flag.

    Parameters:
      `resourceDelta` - the resource delta to add (not `null`)
    See Also:
      - `getResourceDeltas_()`

  - ### insertSubTree_

    protected void insertSubTree_(ElementDelta delta)
    Based on the given delta, creates a delta tree that can be directly parented by this delta and `adds` the created tree as an affected child of this delta.

    Note that after calling `insertSubTree_(delta)` there is no guarantee that

            findDelta_(d.getElement_()) == d

    or even that

            findDelta_(d.getElement_()) != null

    for any delta `d` in the subtree `delta` (subtree root included). For example, if this delta tree already contains a delta for `d.getElement_()`, that delta will be `merged` with `d`, which may even result in a logically empty delta, i.e., no delta for the element.

    Parameters:
      `delta` - the delta to insert (not `null`)
    Throws:
      `IllegalArgumentException` - if the given delta cannot be rooted in this delta

  - ### addAffectedChild_

    protected void addAffectedChild_(ElementDelta child)
    Adds the given delta as an affected child of this delta if permitted by the current state of this delta. If this delta already contains a child delta for the same element as the given delta, `merges` the existing child delta with the given delta. Note that in contrast to `setAffectedChildren_`, this method can change this delta's kind and flags as appropriate.

    It is the caller's responsibility to ensure that the given delta can be directly parented by this delta.

    Note that after calling `addAffectedChild_(delta)` there is no guarantee that

            findDelta_(d.getElement_()) == d

    or even that

            findDelta_(d.getElement_()) != null

    for any delta `d` in the subtree `delta` (subtree root included).

    If the kind of this delta is `ADDED` or `REMOVED`, this implementation returns without adding the given delta; otherwise, it sets the kind of this delta to `CHANGED` and adds the `F_CHILDREN` change flag and, if this delta's element is an `ISourceElement`, the `F_FINE_GRAINED` change flag.

    Parameters:
      `child` - the delta to add as an affected child (not `null`)
    See Also:
      - `getAffectedChildren_()`
      - `insertSubTree_(ElementDelta)`

  - ### mergeWith_

    protected void mergeWith_(ElementDelta delta)
    Merges this delta with the given delta; the given delta is not modified in any way.

    It is the caller's responsibility to ensure that the given delta pertains to the same element as this delta.

    This implementation implements merge semantics in terms of calls to `copyFrom_`.

    Parameters:
      `delta` - the delta to merge with (not `null`)

  - ### copyFrom_

    protected void copyFrom_(ElementDelta delta, boolean init)
    Copies data from the given delta to this delta; the given delta is not modified in any way.

    It is the caller's responsibility to ensure that the given delta pertains to the same element as this delta.

    Subclasses that introduce new fields should consider extending this method.

    Parameters:
      `delta` - the delta to copy data from (not `null`)
      `init` - `true` if this delta needs to be completely (re-)initialized with data from the given delta; `false` if this delta needs to be augmented with data from the given delta

  - ### setAffectedChildren_

    protected void setAffectedChildren_(ElementDelta[] children)
    Sets the affected children for this delta. Clients must not modify the given array afterwards.

    This is a low-level mutator method. In particular, it is the caller's responsibility to set appropriate kind and flags for this delta.

    Parameters:
      `children` - the affected children (not `null`)
    See Also:
      - `getAffectedChildren_()`