Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[platform-ui-dev] New working set API

Near the end of M4 I added API to working sets that allow them to express interest in certain types of objects. The intent was that you could ask the working set if a given object was suitable for containment in it. This would allow us to write UIs where the selection of objects could be added to working sets of a particular type only. Ie: you couldn't add breakpoints to the resource working set. I didn't advertise the API at the time because I wasn't convinced that it was right and after some thought and discussion with downstream clients decided it wasn't.

Rather than answering whether or not a given item was applicable to a working set it would be much more useful for the working set to return an object that WAS applicable to the working set. For instance, attempting to add a breakpoint to a resource working set would instead add the resource that the breakpoint corresponded to. The following API was added to address this issue.

First, a new attribute was added to the working set plugin.xml schema. This optional attribute, "elementAdapterClass", takes a class that implements IWorkingSetElementAdapter as a value. This interface has the following definition:

* Interface that describes a mechanism that may be provided by working set * implementors to help manage the addition of elements to working sets. * Instances of this class are capable of transforming possible working set
 * content into the most applicable form.
 * @since 3.3
public interface IWorkingSetElementAdapter {

* Converts the given elements for addition to /removal from the working
	 * set.
	 * @return the (possibly adapted) elements to add to /remove from the
	 *         working set
	IAdaptable[] adaptElements(IWorkingSet ws, IAdaptable[] elements);
	 * Disposes of this element adaptor.
	void dispose();

It is the responsibility of this interface to inspect IAdaptables and return IAdaptables derived from the originals that are suitable for inclusion in working sets of this type. The adaptables may be the same objects, new objects, or no objects at all if the original adaptables are not suitable.

This interface is accessed indirectly via a new method on IWorkingSet:
	 * Transforms the supplied elements into elements that are suitable for
* containment in this working set. This is useful for UI elements which * wish to filter contributions to working sets based on applicability. This
	 * is a hint, however, and is not considered when the
	 * {@link #setElements(IAdaptable[])} method is invoked.
	 * @param objects
	 *            the objects to transform
* @return an array of transformed elements that be empty if no elements
	 *         from the original array are suitable
	 * @since 3.3
	public IAdaptable[] adaptElements(IAdaptable[] objects);

Note the comment in this method - this is only a hint for IWorkingSet clients, not a definitive filter. IWorkingSet.setElements() will continue to take any array of IAdaptable objects you throw at it.

This new interface behaves similarly to the existing IWorkingSetUpdater interface in that its specification will not cause eager plug-in loading. If your plug-in defines an IWorkingSetElementAdapter class it will not be used until your plug- in is loaded. Until that time the IWorkingSet.adaptElements() method will return the passed array of IAdaptables when invoked. To help get around this limitation a default implementation of IWorkingSetElementAdapter has been provided in the UI plugin. This class, BasicWorkingSetElementAdapter, is an IExecutableExtension and may be customized by client plug-ins in their plugin.xml file. The format for this customization is as follows:

<workingSet elementAdapterClass="org.eclipse.ui.BasicWorkingSetElementAdapter:some.p ackage.ClassName1[;adapt=true|false],some.package.ClassName1 [;adapt=true|false],..."
... />

From the documentation for BasicWorkingSetElementAdapter.adaptElements():

"When invoked this method will iterate over all classes specified as IExecutableExtension arguements to this class in order and compare with the elements. If the element is directly assignable to the provided class then it is added to the result array as is. If the class has specified "adapt=true" as an argument and there is an available adapter in the platform IAdapterManager then it is returned. Finally, if "adapt=true" and the class is already loaded (determined by inspecting exported bundles via the platform PackageAdmin) a direct query for the adapter is made on the object and if it is not <code>null</code> then it is returned.

A consequence of the above is that it is possible for this method to return differing results based on the state of bundles loaded within the system."

For example, here is the declaration for the IDE Resource Working Set elementAdapterClass:

org.eclipse.ui.BasicWorkingSetElementAdapter:org.eclipse.core.resources. IResource;adapt=true

This means that the Resource Working Set will only accept elements that IResources and these may be obtained either by direct assignment or by checking for an adapter.

If there are any comments on this API please log defects and I'll respond to them ASAP. The API deadline is fast approaching so if you do have issues it's better to express them now rather than later. Thanks!

(crossposted to

Back to the top