Package org.eclipse.ui.progress

# Class DeferredTreeContentManager

java.lang.Object
org.eclipse.ui.progress.DeferredTreeContentManager

public class DeferredTreeContentManager extends Object
The DeferredContentManager is a class that helps an ITreeContentProvider get its deferred input. NOTE AbstractTreeViewer#isExpandable may need to be implemented in AbstractTreeViewer subclasses with deferred content that use filtering as a call to #getChildren may be required to determine the correct state of the expanding control. AbstractTreeViewers which use this class may wish to sacrifice accuracy of the expandable state indicator for the performance benefits of deferring content.

Since:
  3.0
See Also:
  - `IDeferredWorkbenchAdapter`

## Constructor Summary

Constructors
Constructor
Description
`DeferredTreeContentManager(AbstractTreeViewer viewer)`
Create a new instance of the receiver using the supplied content provider and viewer.
`DeferredTreeContentManager(AbstractTreeViewer viewer, IWorkbenchPartSite site)`
Create a new instance of the receiver using the supplied content provider and viewer.
`DeferredTreeContentManager(ITreeContentProvider provider, AbstractTreeViewer viewer)`
Deprecated.
in 3.4. provider is not used by this class
`DeferredTreeContentManager(ITreeContentProvider provider, AbstractTreeViewer viewer, IWorkbenchPartSite site)`
Deprecated.
in 3.4. provider is not used by this class

## Method Summary

Modifier and Type
Method
Description
`protected void`
`addChildren(Object parent, Object[] children, IProgressMonitor monitor)`
Create a UIJob to add the children to the parent in the tree viewer.
`void`
`addUpdateCompleteListener(IJobChangeListener listener)`
Add a listener to list of update complete listeners.
`void`
`cancel(Object parent)`
Cancel all jobs that are fetching content for the given parent or any of its children.
`protected IElementCollector`
`createElementCollector(Object parent, PendingUpdateAdapter placeholder)`
Create the element collector for the receiver.
`protected PendingUpdateAdapter`
`createPendingUpdateAdapter()`
Factory method for creating the pending update adapter representing the placeholder node.
`protected IDeferredWorkbenchAdapter`
`getAdapter(Object element)`
Return the IDeferredWorkbenchAdapter for element or the element if it is an instance of IDeferredWorkbenchAdapter.
`Object[]`
`getChildren(Object parent)`
Returns the child elements of the given element, or in the case of a deferred element, returns a placeholder.
`protected String`
`getFetchJobName(Object parent, IDeferredWorkbenchAdapter adapter)`
Returns a name to use for the job that fetches children of the given parent.
`boolean`
`isDeferredAdapter(Object element)`
Return whether or not the element is or adapts to an IDeferredWorkbenchAdapter.
`boolean`
`mayHaveChildren(Object element)`
Provides an optimized lookup for determining if an element has children.
`void`
`removeUpdateCompleteListener(IJobChangeListener listener)`
Removes the listener from the list of update listeners that are attached to the job that updates the viewer content (clears the pending entry, etc.)
`protected void`
`runClearPlaceholderJob(PendingUpdateAdapter placeholder)`
Run a job to clear the placeholder.
`protected void`
`startFetchingDeferredChildren(Object parent, IDeferredWorkbenchAdapter adapter, PendingUpdateAdapter placeholder)`
Starts a job and creates a collector for fetching the children of this deferred adapter.

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

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

## Constructor Details

### DeferredTreeContentManager

@Deprecated public DeferredTreeContentManager(ITreeContentProvider provider, AbstractTreeViewer viewer, IWorkbenchPartSite site)
Deprecated.
in 3.4. provider is not used by this class
Create a new instance of the receiver using the supplied content provider and viewer. Run any jobs using the site.

Parameters:
  `provider` - content provider
  `viewer` - content viewer
  `site` - part site

### DeferredTreeContentManager

@Deprecated public DeferredTreeContentManager(ITreeContentProvider provider, AbstractTreeViewer viewer)
Deprecated.
in 3.4. provider is not used by this class
Create a new instance of the receiver using the supplied content provider and viewer.

Parameters:
  `provider` - The content provider that will be updated
  `viewer` - The tree viewer that the results are added to

### DeferredTreeContentManager

public DeferredTreeContentManager(AbstractTreeViewer viewer, IWorkbenchPartSite site)
Create a new instance of the receiver using the supplied content provider and viewer. Run any jobs using the site.

Parameters:
  `viewer` - content viewer
  `site` - part site
Since:
  3.4

### DeferredTreeContentManager

public DeferredTreeContentManager(AbstractTreeViewer viewer)
Create a new instance of the receiver using the supplied content provider and viewer.

Parameters:
  `viewer` - The tree viewer that the results are added to
Since:
  3.4

## Method Details

### mayHaveChildren

public boolean mayHaveChildren(Object element)
Provides an optimized lookup for determining if an element has children. This is required because elements that are populated lazilly can't answer `getChildren` just to determine the potential for children. Throw an AssertionFailedException if element is null.

Parameters:
  `element` - The Object being tested. This should not be `null`.
Returns:
  boolean `true` if there are potentially children.
Throws:
  `RuntimeException` - if the element is null.

### getChildren

public Object[] getChildren(Object parent)
Returns the child elements of the given element, or in the case of a deferred element, returns a placeholder. If a deferred element is used, a job is created to fetch the children in the background.

Parameters:
  `parent` - The parent object.
Returns:
  Object[] or `null` if parent is not an instance of IDeferredWorkbenchAdapter.

### createPendingUpdateAdapter

protected PendingUpdateAdapter createPendingUpdateAdapter()
Factory method for creating the pending update adapter representing the placeholder node. Subclasses may override.

Returns:
  a pending update adapter
Since:
  3.2

### getAdapter

protected IDeferredWorkbenchAdapter getAdapter(Object element)
Return the IDeferredWorkbenchAdapter for element or the element if it is an instance of IDeferredWorkbenchAdapter. If it does not exist return null.

Parameters:
  `element` - element to adapt
Returns:
  IDeferredWorkbenchAdapter or `null`

### startFetchingDeferredChildren

protected void startFetchingDeferredChildren(Object parent, IDeferredWorkbenchAdapter adapter, PendingUpdateAdapter placeholder)
Starts a job and creates a collector for fetching the children of this deferred adapter. If children are waiting to be retrieved for this parent already, that job is cancelled and another is started.

Parameters:
  `parent` - The parent object being filled in,
  `adapter` - The adapter being used to fetch the children.
  `placeholder` - The adapter that will be used to indicate that results are pending.

### getFetchJobName

protected String getFetchJobName(Object parent, IDeferredWorkbenchAdapter adapter)
Returns a name to use for the job that fetches children of the given parent. Subclasses may override. Default job name is parent's label.

Parameters:
  `parent` - parent that children are to be fetched for
  `adapter` - parent's deferred adapter
Returns:
  job name

### addChildren

protected void addChildren(Object parent, Object[] children, IProgressMonitor monitor)
Create a UIJob to add the children to the parent in the tree viewer.

Parameters:
  `parent` - the parent object being filled in
  `children` - the elements being added
  `monitor` - a progress monitor

### isDeferredAdapter

public boolean isDeferredAdapter(Object element)
Return whether or not the element is or adapts to an IDeferredWorkbenchAdapter.

Parameters:
  `element` - the element to test
Returns:
  boolean `true` if the element is an IDeferredWorkbenchAdapter

### runClearPlaceholderJob

protected void runClearPlaceholderJob(PendingUpdateAdapter placeholder)
Run a job to clear the placeholder. This is used when the update for the tree is complete so that the user is aware that no more updates are pending.

Parameters:
  `placeholder` - placeholder to clear

### cancel

public void cancel(Object parent)
Cancel all jobs that are fetching content for the given parent or any of its children.

Parameters:
  `parent` - the root to cancel

### createElementCollector

protected IElementCollector createElementCollector(Object parent, PendingUpdateAdapter placeholder)
Create the element collector for the receiver.

Parameters:
  `parent` - The parent object being filled in,
  `placeholder` - The adapter that will be used to indicate that results are pending.
Returns:
  IElementCollector

### addUpdateCompleteListener

public void addUpdateCompleteListener(IJobChangeListener listener)
Add a listener to list of update complete listeners. These listeners are attached to the job that updates the viewer content (clears the pending entry, etc.) after all deferred content has been retrieved. This method has no effect if the listener has already been added to the list of listeners. Since 3.6, this listener is added to a list of listeners rather than replacing the previously added listener. For backward compatibility, adding a null listener will be interpreted as removal of a listener if only one listener has been registered.

Parameters:
  `listener` - the listener to add to the list of update listeners
Since:
  3.4

### removeUpdateCompleteListener

public void removeUpdateCompleteListener(IJobChangeListener listener)
Removes the listener from the list of update listeners that are attached to the job that updates the viewer content (clears the pending entry, etc.) after all deferred content has been retrieved. If the listener is already attached to a running job, it is not removed, but it will not be added to any subsequent jobs that are run. This method has no effect if the listener was not previously added to the listener list.

Parameters:
  `listener` - the listener to be removed
Since:
  3.6