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 `ISideEffect`s. 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 Summary

Constructors
Constructor
Description
`CompositeSideEffect()`
Default constructor of an CompositeSideEffect.

## Method Summary

Modifier and Type
Method
Description
`void`
`add(ISideEffect sideEffect)`
Adds the given `ISideEffect` instance from the composite.
`void`
`addDisposeListener(Consumer<ISideEffect> disposalConsumer)`
Adds a listener that will be invoked when this `ISideEffect` instance is disposed.
`void`
`dispose()`
Disposes the side-effect, detaching all listeners and deallocating all memory used by the side-effect.
`boolean`
`isDisposed()`
Returns true if this side-effect has been disposed.
`void`
`pause()`
Increments the count of the number of times the `ISideEffect` has been paused.
`void`
`remove(ISideEffect sideEffect)`
Removes the given `ISideEffect` instance from the composite.
`void`
`removeDisposeListener(Consumer<ISideEffect> disposalConsumer)`
Removes a dispose listener from this `ISideEffect` instance.
`void`
`resume()`
Increments the count of the number of times the `ISideEffect` has been resumed.
`void`
`resumeAndRunIfDirty()`
Increments the count of the number of times the `ISideEffect` has been resumed.
`void`
`runIfDirty()`
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).

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

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

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