[platform-ui-dev] New working set API

[Kimberly Horne <kim@xxxxxxxxxxxxx>]

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 planet.eclipse.org)