Article-Adapters/index.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Adapters</title>
<meta http-equiv="Content-Type"
	content="text/html; charset=windows-1252">
<link href="../article.css" type="text/css" rel="stylesheet">
</head>
<body>

<h1>Adapters</h1>
<div class="summary">
<h2>Summary</h2>
<p>The adapter pattern is used extensively in Eclipse. The use of
this pattern allows plug-ins to be loosely coupled, yet still be tightly
integrated in the extremely dynamic Eclipse runtime environment. In this
article, we show you how to use the adapter framework to make your own
objects adaptable, and adapt other objects.</p>

<div class="author">By Wayne Beaton, The Eclipse Foundation</div>
<div class="copyright">Copyright &copy; 2008 The Eclipse
Foundation.</div>
<div class="date">June 24, 2008</div>
</div>

<div class="content">
<h2>Introduction</h2>
<p>The adapter pattern is used extensively in Eclipse. The use of
this pattern allows plug-ins to be loosely coupled, yet still be tightly
integrated in the extremely dynamic Eclipse runtime environment. The
adapter framework is used extensively by a wide variety of plug-ins,
including those from the Eclipse platform, other Eclipse projects, and
by the broader community and eco-system. The adapter framework should be
considered as one of the essential parts of the Eclipse platform that
everyone writing Eclipse plug-ins must know about.</p>

<h2>Using the Properties View</h2>

<p><em>This article is not intended to provide thorough
coverage of the Properties view. Rather, the Properties view is used as a
means for demonstrating how adapters can be put to work.</em></p>

<p>The Properties view displays properties for whatever is selected
in the workbench. Selections can occur in many places: the Navigator and
Package Explorer views are two very obvious sources of selection. But
selections can come from other places, even views created by you and
your fellow developers. It's easy to see the Properties view in action.
Just open it and select something in the Package Explorer; the
Properties view will update to reflect the properties for the selected
thing. Here, we see the Properties view (bottom) showing properties for
file selected in the Package Explorer:</p>

<div class="figure"><img src="images/properties.png" /></div>

<p>One of the really interesting things about the Properties view is
that it can display properties for objects that it knows nothing about.
In fact, the Properties view doesn't really know anything in particular
about any of the objects it displays.</p>

<p>You can use the Properties view to show information about the
objects selected in a view that you've created. The first step is to
make sure that the workbench selection service knows about the object
selected in your view. If you're using a JFace <code>TableViewer</code>
or <code>TreeViewer</code>, then this step is easy (if you're doing
something else, <a
	href="http://www.eclipse.org/articles/Article-WorkbenchSelections/article.html">&quot;Eclipse
Workbench: Using the Selection Service&quot;</a> by Marc R. Hoffmann will
help you determine how to best contribute the selection). You need to do
is invoke the <code>setSelectionProvider</code> method in your view's <code>createPartControl</code>
method (the important part is marked in bold):</p>
<pre>...
public void createPartControl(Composite parent) {
	viewer = new TableViewer(parent, SWT.MULTI | SWT.H_SCROLL | SWT.V_SCROLL);
	viewer.setContentProvider(new ViewContentProvider());
	viewer.setLabelProvider(new ViewLabelProvider());

	<strong>getSite().setSelectionProvider(viewer);</strong>

	viewer.setInput(getViewSite());
}
...</pre>

<p>Once you have your view contributing to the workbench selection,
you need to make sure that the objects that your view is selecting
contribute properties. The easiest (but not necessary most correct) way
to do this is to have your class implement the <code>IPropertySource</code>
interface:</p>

<pre>...
public class Person  <strong>implements IPropertySource</strong> {
	private String name;
	private Object street;
	private Object city;

	public Person(String name) {
		this.name = name;
		this.street = "";
		this.city = "";
	}

	public Object getEditableValue() {
		return this;
	}

	public IPropertyDescriptor[] getPropertyDescriptors() {
		return new IPropertyDescriptor[] {
				<strong>new TextPropertyDescriptor("name", "Name")</strong>,
				new TextPropertyDescriptor("street", "Street"),
				new TextPropertyDescriptor("city", "City")
		};
	}

	public Object getPropertyValue(Object id) {
		if ("name".equals(id)) return name;
		else if ("street".equals(id)) return street;
		else if ("city".equals(id)) return city;
		return null;
	}

	public void setPropertyValue(Object id, Object value) {
		if ("name".equals(id)) name = (String)value;
		else if ("street".equals(id)) street = (String)value;
		else if ("city".equals(id)) city = (String)value;
	}

	public boolean isPropertySet(Object id) {
		return false;
	}

	public void resetPropertyValue(Object id) {
	}
}</pre>

<p>In this example, the object has three properties that are all <em>text</em>
values (one of the property descriptors that defines the behaviour of a
property for the Property view is marked in bold). The first parameter
is the name of the property, and the second one is the label for that
property in the view. There are other types of property descriptors that
you can use; you can even make your own if you have a special type of
property.</p>

<p>This example has been kept deliberately simple. These properties
cannot be reset, nor does the implementation have any notion of whether
or not properties have been set. A more sophisticated implementation
will provide the user with more sophisticated options.</p>

<p>As indicated earlier, this solution does not provide the most
correct implementation possible. With this implementation, the domain
object needs to know about the very view-centric (and Eclipse-centric)
notion of being a property source; in short, there is a tight-coupling
between the model and the property viewing framework. This where
adapters come in.</p>

<h2>Introducing Adapters</h2>

<p>Tight coupling is bad because it tends to make things less
flexible. Sure, we can look at the properties of our domain object, but
what happens when we want to participate in other interactions? Do we
just implement another interface? And another? Tight coupling makes
reuse harder as well. Tightly coupling our domain class with the <code>IPropertySource</code>
interface makes it so that our domain class can't exist without that
interface (and all the other types packaged along with it, plus those
bits referenced by all those types, ...). The an adapter framework
solves this problem by decoupling the domain class from the
view-specific code required to make the Properties view work.</p>

<p>The first step is to remove the <code>IPropertySource</code>
behaviour from the domain class:</p>

<pre>...
public class Person implements <strong>IAdaptable</strong> {
	private String name;
	private Object street;
	private Object city;

	public Person(String name) {
		this.name = name;
		this.street = "";
		this.city = "";
	}

	<strong>public Object getAdapter(Class adapter)</strong> {
		if (adapter == IPropertySource.class) return new PersonPropertySource(this);
		return null;
	}

	// Getter and setter methods follow...
	...
}</pre>

<p>We move the <code>IPropertySource</code> behaviour to the <code>PersonPropertySource</code>
class:</p>

<pre>...
public class PersonPropertySource implements IPropertySource {
	private final Person person;

	public PersonPropertySource(Person person) {
		this.person = person;
	}

	public Object getEditableValue() {
		return this;
	}

	public IPropertyDescriptor[] getPropertyDescriptors() {
		return new IPropertyDescriptor[] {
				new TextPropertyDescriptor("name", "Name"),
				new TextPropertyDescriptor("street", "Street"),
				new TextPropertyDescriptor("city", "City")
		};
	}

	public Object getPropertyValue(Object id) {
		if ("name".equals(id)) return person.getName();
		else if ("street".equals(id)) return person.getStreet();
		else if ("city".equals(id)) return person.getCity();
		return null;
	}

	public boolean isPropertySet(Object id) {
		return false;
	}

	public void resetPropertyValue(Object id) {
	}

	public void setPropertyValue(Object id, Object value) {
		if ("name".equals(id)) person.setName((String)value);
		else if ("street".equals(id)) person.setStreet((String)value);
		else if ("city".equals(id)) person.setCity((String)value);
	}

}</pre>

<p>The Properties view goes through a few steps to sort out how it's
going to display properties. First, it determines whether or not the
selected object implements the <code>IPropertySource</code> interface.
If it does (as it does in our first example), it uses the selected
object directly (after casting it to <code>IPropertySource</code>). If
that check fails, the Property view then determines whether or not the
selected object implements the <code>IAdaptable</code> interface
(highlighted in the <code>Person</code> class). If the selected object
is adaptable, it is asked&mdash;via the <code>getAdapter</code>
method&mdash;for an adapter with the <code>IPropertySource</code> type.
The <code>getAdapter</code> method either returns an object of the
appropriate type or <code>null</code> if it cannot be adapted to the
requested type. If the method returns an adapter, it is used by the
Property view to gather properties (if it is <code>null</code> the
Property view shows nothing).</p>

<p>The astute reader will notice that this really doesn't do very
much to actually weaken the coupling between the domain class and <code>IPropertySource</code>
(the <code>IPropertySource</code> type is referenced directly by the <code>getAdapter</code>
method). In fact, the coupling is just as strong. Even worse, we've
actually introduced a tight coupling to another type (<code>IAdaptable</code>).</p>

<h2>Decoupling with Adapters</h2>

<p>The next step is to completely decouple the domain class from <code>IPropertySource</code>.
To do this, we change the <code>getAdapter</code> method:</p>

<pre>public class Person implements IAdaptable {
	private String name;
	private Object street;
	private Object city;

	public Person(String name) {
		this.name = name;
		this.street = "";
		this.city = "";
	}

	<strong>public Object getAdapter(Class adapter) {
		return Platform.getAdapterManager().getAdapter(this, adapter);
	}</strong>

	...
}</pre>

<p>Previously, the <code>getAdapter</code> method checked the type
of the desired adapter and created an appropriate instance (if possible)
itself. Now, the method makes a call to the <code>AdapterManager</code>,
which can take care of figuring out how to adapt the instance.</p>

<p>For this to work, the adapter manager needs to be told how to
adapt the type. This can be done declaratively through the <code>plugin.xml</code>
file using the <code>org.eclipse.core.runtime.adapters</code> extension
point:</p>

<pre>&lt;plugin&gt;
   &lt;extension
         point="org.eclipse.core.runtime.adapters"&gt;
      &lt;factory
            adaptableType="org.eclipse.articles.adapters.core.Person"
            class="org.eclipse.articles.adapters.properties.PersonPropertiesSourceAdapterFactory"&gt;
         &lt;adapter
               type="org.eclipse.ui.views.properties.IPropertySource"&gt;
         &lt;/adapter&gt;
      &lt;/factory&gt;
   &lt;/extension&gt;
&lt;/plugin&gt;</pre>

<p>This extension defines an adapter for instances of the <code>org.eclipse.articles.adapters.core.Person</code>
class. When asked to adapt to the <code>org.eclipse.ui.views.properties.IPropertySource</code>,
the <code>PersonPropertiesSourceAdapterFactory</code> is used. This
factory class is defined as such:</p>

<pre>public class PersonPropertiesSourceAdapterFactory implements IAdapterFactory {
	public Object getAdapter(Object adaptableObject, Class adapterType) {
		if (adapterType == IPropertySource.class)
			return new PersonPropertySource((Person)adaptableObject);
		return null;
	}

	public Class[] getAdapterList() {
		return new Class[] {IPropertySource.class};
	}
}</pre>

<p>The <code>getAdapter</code> method does the heavy lifting and
creates the adapter. The <code>getAdapterList</code> returns a list of
the types of adapters the factory can create.</p>

<p>Adapter factories can also be registered programmatically using
APIs on the <code>AdapterManager</code> class.</p>

<p>The Properties view, and other users of the adapter framework
actually go through three steps to find an adapter:</p>

<ol>
	<li>If the object implements the required interface, use the
	object</li>
	<li>If the object implements <code>IAdaptable</code>, call the <code>getAdapter</code>
	method and use the returned object; if something other than <code>null</code>
	is answered, use the returned value</li>
	<li>Get the <code>AdapterManager</code> to try and adapt the
	object</li>
</ol>

<p>The final step actually makes the current implementation of <code>getAdapter</code>
in the <code>Person</code> class redundant. We can simply remove it, and
remove the reference to the <code>IAdaptable</code> interface from the
class. That is, the <code>Person</code> class simplifies to:</p>

<pre>public class Person {
	private String name;
	private Object street;
	private Object city;

	public Person(String name) {
		this.name = name;
		this.street = "";
		this.city = "";
	}
	...
}</pre>

<p>Voila! the domain class is totally decoupled from the adapter
type. Instances of the person class, when selected in your favourite
view, will populate the Properties view.</p>

<a name="code"></a>
<h3>Get the code</h3>

<p>This example can be added to your Eclipse development environment
either by downloading and importing the Plug-in Projects contained in <a
	href="code/adapters.zip">adapters.zip</a>. Alternatively, you can pull
the projects directly out of Eclipse CVS by importing the <a
	href="code/adapters.psf">Team Project Set</a>. Note that you'll need to
have support for the <a href="http://www.eclipse.org/pde">Plug-in
Development Environment</a> (PDE) included with your Eclipse configuration.
You can ensure that you have this functionality available by downloading
either the <em>Eclipse Classic</em>, or the <em>Eclipse for
Plug-in/RCP Developers</em> package. These bundles were created using the
Ganymede release of Eclipse, which contains version 3.4 of the Eclipse
Platform.</p>

<p>The example includes three different bundles:</p>

<dl>
	<dt><code>org.eclipse.articles.adapters.core</code></dt>
	<dd>
	<p>The &quot;core&quot; bundle contains the <code>Person</code>
	class and nothing else. It has no dependencies on any other bundles.</p>
	</dd>
	<dt><code>org.eclipse.articles.adapters.properties</code></dt>
	<dd>
	<p>The &quot;properties&quot; bundle contains the <code>PersonPropertiesSourceAdapterFactory</code>
	and <code>PersonPropertiesSource</code> classes. It also has a
	plugin.xml file which defines the extension to <code>org.eclipse.core.runtime.adapters</code>
	that registers the adapter.</p>
	<p>This bundle further includes a bundle activator that implements
	<code>org.eclipse.ui.IStartup</code> to participate in early startup
	(via the <code>org.eclipse.ui.startup</code> extension point). The
	properties view uses the <code>IAdapterManager#getAdapter(Object,
	Class)</code> method which&mdash;as discussed later in this
	document&mdash;only finds adapters from bundles that are activated.</p>
	</dd>
	<dt><code>org.eclipse.articles.adapters.ui</code></dt>
	<dd>
	<p>The &quot;ui&quot; bundle defines a very simple view that
	displays a list of <code>Person</code> objects. When an object is
	selected in this view, the Properties view (if it is open) will show
	the properties of the selection.</p>
	</dd>
</dl>

<p>There are several important aspects to this example. First, the
&quot;core&quot; bundle is written without any explicit or implicit
dependencies on anything that is part of the Eclipse framework. This
bundle can therefore be reused easily in other applications without
modification. It's also important that the view defined in the
&quot;ui&quot; component has no dependencies on the Properties view.
These two views integrate completely on the workbench, yet know
absolutely nothing about each other. It is the &quot;properties&quot;
bundle that provides the glue between the two.</p>

<h2>Adapting</h2>

<p>The adapter framework is great for getting your objects to
tightly integrate with existing parts of the Eclipse infrastructure,
while remaining loosely coupled with the actual implementation. Loose
coupling with tight integration is pretty powerful stuff.</p>

<p>The <em>"Image Preview" view</em>, is example plug-in that
displays the image (if one is available) for a file selected in the
workbench. The best part is that the view is completely decoupled from
the Resources API. That is, it doesn't know anything about files,
directories, workspaces, or anything else in particular. The view is
shown in action below:</p>

<div class="figure"><img src="images/image-viewer.png" /></div>

<p>The code for the <a href="http://www.eclipse.org/examples/imageviewer">Image Preview example</a>
can accessed via the <a href="http://www.eclipse.org/examples">Eclipse Examples project</a>.</p>

<p>By implementing the Image Preview view using adapters, it can be
easily made to display an image for different kinds of selected objects
by providing a new adapter. A natural extension of this is that we can
use the Image Preview view in a <a href="http://www.eclipse.org/rcp">Rich
Client Platform</a> (RCP) application to display an image for arbitrary
domain objects (assuming that it makes sense for the objects to provide
images, of course).</p>

<p>The Image Preview view listens to the workbench selection
service. When a selection occurs in a view (such as the Package
Explorer, or Navigator), the selection service notifies registered
listeners. When the Image Preview view is notified of the selection
change, it attempts to adapt the selected object to the <code>ImageProvider</code>
interface (which is defined in the same bundle as the view). The <code>ImageProvider</code>
is then used to obtain an image.</p>

<p>Recall the three steps to find an adapter:</p>
<ol>
	<li>If the selected object implements the <code>ImageProvider</code>
	interface, use the object</li>
	<li>If the object implements <code>IAdaptable</code>, call the <code>getAdapter</code>
	method asking for an <code>ImageProvider</code>; if something other
	than <code>null</code> is answered, use the returned value</li>
	<li>Get the <code>AdapterManager</code> to try and adapt the
	object</li>
</ol>

<p>The <code>getImageProvider</code> method in the Image Preview
view looks like this:</p>

<pre>private ImageProvider getImageProvider(Object object) {
	// First, if the object is an ImageProvider, use it.
	if (ImageProvider.class.isInstance(object)) return (ImageProvider)object;

	// Second, if the object is adaptable, ask it to get an adapter.
	ImageProvider provider = null;
	if (object instanceof IAdaptable)
		provider = (ImageProvider)((IAdaptable)object).getAdapter(ImageProvider.class);

	// If we haven't found an adapter yet, try asking the AdapterManager.
	if (provider == null)
		provider = (ImageProvider)Platform.getAdapterManager().<strong>loadAdapter</strong>(object, ImageProvider.class.getName());

	return provider;
}</pre>

<p>The first step, is to see if the selected object implements the
required interface. If it does, we cast and return it. If we make it to
the second step, we ask the object if it is adaptable (i.e. does it
implement the <code>IAdaptable</code> interface?). If it does, we use
that method to attempt to find an adapter. If that method fails (returns
<code>null</code>), the <code>AdapterManager</code> is used. Ultimately,
this method may fail to find an appropriate adapter and return <code>null</code>.</p>

<p>The selected object doesn't need to know anything about the Image
Preview view. Conversely, the Image Preview view knows nothing about
files or any other particular type of object. The adapter implementor
knows about both (it really only needs to know about the <code>ImageProvider</code>
interface).</p>

<p>Note that there are two different ways to ask the <code>AdapterManager</code>
to adapt an object: <code>getAdapter</code> or <code>loadAdapter</code>
(which is highlighted in the snippet). Both methods will find
programmatically- and declaratively-registered adapters, however the <code>getAdapter</code>
method will only find declaratively-registered adapters <em>if the
bundle that contributes them has already been activated</em>. The <code>loadAdapter</code>
will load and activate the bundle (if required) as part of the process.</p>

<h2>Conclusion</h2>

<p>The adapter framework is a important part of every Eclipse plug-in developer's
arsenal. By using the adapter framework, you can easily create bundles that have no
explicit coupling to the Eclipse platform. The adapter framework can be used to
significantly reduce the coupling in an application, encouraging higher-quality code
and making it generally easier to understand and reuse parts of the application. 
Tight integration with loose coupling is a powerful concept.</p>
</div>
</body>
</html>