Package org.eclipse.core.databinding.observable.sideeffect

Class CompositeSideEffect

java.lang.Object
org.eclipse.core.databinding.observable.sideeffect.CompositeSideEffect
All Implemented Interfaces:
ISideEffect
public final class CompositeSideEffect extends Object implements ISideEffect
Represents an ISideEffect that is composed of a bunch of component ISideEffects. It has the following properties:
  • Disposing the composite will dispose all of the children.
  • If the composite is paused, all of the children will be paused as well.
Note that resuming a composite does not guarantee that all children will resume. Children may also be paused externally, in which case the child must be resumed both by the composite and by the external source(s) before it will execute.

Children may belong to multiple composites. When this occurs, all of its parent composites must be resumed in order for the child to execute and the child will be disposed the first time any of its parents are disposed.

Children may be removed from a composite. When this occurs, the child may be resumed immediately if the composite was paused and disposing the composite will no longer have any effect on the removed child.

Disposing a child will automatically remove it from its parent composite(s).

The main use of this class is to manage a group of side-effects that share the same life-cycle. For example, all side-effects used to populate widgets within a workbench part would likely be paused and resumed when the part is made visible or invisible, and would all be disposed together when the part is closed.

Since:
1.6

  • Constructor Details

    • CompositeSideEffect

      public CompositeSideEffect()
      Default constructor of an CompositeSideEffect.

  • Method Details

    • dispose

      public void dispose()
      Description copied from interface: ISideEffect
      Disposes the side-effect, detaching all listeners and deallocating all memory used by the side-effect. The side-effect will not execute again after this method is invoked.

      This method may be invoked more than once.

      Specified by:
      dispose in interface ISideEffect

    • isDisposed

      public boolean isDisposed()
      Description copied from interface: ISideEffect
      Returns true if this side-effect has been disposed. A disposed side-effect will never execute again or retain any strong references to the observables it uses. A side-effect which has not been disposed has some possibility of executing again in the future and of retaining strong references to observables.
      Specified by:
      isDisposed in interface ISideEffect
      Returns:
      true if this side-effect has been disposed.

    • addDisposeListener

      public void addDisposeListener(Consumer<ISideEffect> disposalConsumer)
      Description copied from interface: ISideEffect
      Adds a listener that will be invoked when this ISideEffect instance is disposed. The listener will not be invoked if the receiver has already been disposed at the time when the listener is attached.
      Specified by:
      addDisposeListener in interface ISideEffect
      Parameters:
      disposalConsumer - a consumer which will be notified once this ISideEffect is disposed.

    • removeDisposeListener

      public void removeDisposeListener(Consumer<ISideEffect> disposalConsumer)
      Description copied from interface: ISideEffect
      Removes a dispose listener from this ISideEffect instance. Has no effect if no such listener was previously attached.
      Specified by:
      removeDisposeListener in interface ISideEffect
      Parameters:
      disposalConsumer - a consumer which is supposed to be removed from the dispose listener list.

    • pause

      public void pause()
      Description copied from interface: ISideEffect
      Increments the count of the number of times the ISideEffect has been paused. If the side-effect has been paused a greater number of times than it has been resumed, it enters the paused state.

      When a ISideEffect is paused, this prevents it from running again until it is resumed. Note that the side-effect will continue listening to its dependencies while it is paused. If a dependency changes while the ISideEffect is paused, the ISideEffect will run again after it is resumed.

      A side-effect may be paused and resumed any number of times. You should use pause instead of dispose if there is a chance you may want to resume the SideEffect later.

      Specified by:
      pause in interface ISideEffect

    • resume

      public void resume()
      Description copied from interface: ISideEffect
      Increments the count of the number of times the ISideEffect has been resumed. If the side-effect has been resumed an equal number of times than it has been paused, it leaves the paused state and enters the resumed state. It is an error to resume ISideEffect more often than it has been paused.

      When a ISideEffect is resumed, it starts reacting to changes in tracked getters invoked by its runnable. It will continue to react to changes until it is either paused or disposed. If the ISideEffect is dirty, it will be run at the earliest opportunity after this method returns.

      Specified by:
      resume in interface ISideEffect

    • resumeAndRunIfDirty

      public void resumeAndRunIfDirty()
      Description copied from interface: ISideEffect
      Increments the count of the number of times the ISideEffect has been resumed. If the side-effect has been resumed an equal or greater number of times than it has been paused, it leaves the paused state and enters the resumed state.

      When a ISideEffect is resumed, it starts reacting to changes in TrackedGetters invoked by its runnable. It will continue to react to changes until it is either paused or disposed. If the ISideEffect is dirty, it will be run synchronously.

      This is a convenience method which is fully equivalent to calling ISideEffect.resume() followed by ISideEffect.runIfDirty(), but slightly faster.

      Specified by:
      resumeAndRunIfDirty in interface ISideEffect

    • runIfDirty

      public void runIfDirty()
      Description copied from interface: ISideEffect
      Causes the side effect to run synchronously if and only if it is currently dirty (that is, if one of its dependencies has changed since the last time it ran). Does nothing if the ISideEffect is currently paused.
      Specified by:
      runIfDirty in interface ISideEffect

    • add

      public void add(ISideEffect sideEffect)
      Adds the given ISideEffect instance from the composite.
      Parameters:
      sideEffect - ISideEffect

    • remove

      public void remove(ISideEffect sideEffect)
      Removes the given ISideEffect instance from the composite. This has no effect if the given side-effect is not part of the composite.
      Parameters:
      sideEffect - ISideEffect