We need a mechanism that allows us to

The pattern is called Extension Object^[1] and is also known as Extension Interface. To quote its intent: “Anticipate that an object's interface needs to be extended in the future. Extension Object lets you add interfaces to a class and lets clients query whether an object has a particular extension.”

When implementing Extension Object, you have to answer several questions:

The Eclipse extension support is class-based. That is, you can add behavior to existing classes, but not add state to its existing instances. The additional behavior is described by an interface.

The key interface of the Eclipse extension support is IAdaptable. Classes that support adaptability implement this interface. While browsing the Eclipse source, you will find that IAdaptable is a popular interface, as illustrated in the following snapshot of the Hierarchy view shown in Figure 31.3.

Figure 31.3. IAdaptable Type Hierarchy

What is behind the IAdaptable name? When doing some Eclipse code archeology we found the class was originally called IExtensible. This captured the idea that the mechanism existed to support extending a type with additional behavior. Over time the name got changed to IAdaptable to emphasize the fact that the mechanism enables adapting an existing class to another interface.

IAdaptable is an interface with a single method that allows clients to dynamically query whether an object supports a particular interface:

public interface IAdaptable {
  public Object getAdapter(Class adapter);
}

The getAdapter() method answers a particular interface. Callers of getAdapter() pass in the class object corresponding to the interface (see Figure 31.4).

Figure 31.4. Extension Object

The class object is typically retrieved with a class literal (for example, IPropertySource.class). GetAdapter() could have taken a String argument instead, but then the compiler couldn't check to see whether the interface exists at compile time. GetAdapter() returns an object castable to the given class (or null if the interface isn't supported). Here is an example of how the Properties view queries the currently selected object for its IPropertySource interface:

getPropertySource(Object object) {
  //...
  if (object instanceof IAdaptable) {
    IAdaptable a=  (IAdaptable) object;
    return (IPropertySource)a.getAdapter(IPropertySource.class);
  }
}

The IAdaptable interface is used in two different ways in Eclipse:

Let's first consider how a class can provide interfaces using IAdaptable.

Here is an implementation of a getAdapter() method in a class that supports the IPropertySource interface:

Object getAdapter(Class adapter)  {
  if (adapter.equals(IPropertySource.class)
    return new PropertySourceAdapter(this);
  return super.getAdapter(adapter);
}

In PropertySourceAdapter, you implement the IPropertySource:

public class PropertySourceAdapter implements IPropertySource {
  private Object  source;

  public PropertySourceAdapter(Object source) {
    this.source= source;
  }

  public IPropertyDescriptor[] getPropertyDescriptors() {
    // return the property descriptors.
  }
  //...
}

Implementing getAdapter() directly helps with the API evolution. If later on the class wants to provide an additional interface, say IShowInSource, then we only have to augment the getAdapter() method. No changes to the external interface of the class are required:

Object getAdapter(Class adapter)  {
  if (adapter.equals(IPropertySource.class)
    return new PropertySourceAdapter(this);
  if (adapter.equals(IShowInSource.class)
    return new ShowInSourceAdapter(this);
  return super.getAdapter(adapter);
}

Implementing getAdapter() with conditional logic is simple. But since Extension Object is supposed to support unanticipated extension, conditional logic isn't the final answer. The next step is externally augmenting the interfaces supported by an existing type.

Let's consider how to add property-sheet support to IFile without having to pollute IFile with UI-specific behavior. A layer-preserving solution is to introduce a property-sheet wrapper for an IFile. Let's go down this path for a while to see its problems.

public class FileWithProperties implements IPropertySource {
  private IFile  file;

  public IPropertyDescriptor[] getPropertyDescriptors() {...}
  public Object getPropertyValue(Object id) {...}
  public boolean isPropertySet(Object id) {...}
  public void resetPropertyValue(Object id) {...}
  public void setPropertyValue(Object id, Object value) {...}

  public IFile toFile() { return file; }
}

The class FileWithProperties wraps an existing IFile and implements the IPropertySource interface. As an improvement, we could also implement the IFile interface (which the API contract doesn't allow) and implement the wrapper using the Decorator pattern. This would make the use of the wrapper more transparent to clients. However, there is another problem. We now end up with two different objects representing the same IFile. This introduces subtle complexities when it comes to testing files for equality. Life would be much simpler without any wrapping. Clients can just deal with IFile but extend its behavior. This is exactly the purpose of adapter factories. Here are the steps for how to extend IFile:

In the implementation you have to declare which adapters the factory provides. This is done in the getAdapterList() method. The purpose of this declarative method is to enable a quick lookup for an adapter. With this information, Eclipse can quickly decide whether a type supports a particular adapter.

An AdapterFactory encapsulates the extensions you want to add for a particular type.

class FileAdapterFactory implements IAdapterFactory {
  public Class[] getAdapterList() {
    return new Class[] {
     IPropertySource.class
    };
  }
  //...
}

In our case, the factory contributes a single adapter for IPropertySource. The other method is getAdapter(). In contrast to the IAdaptable.getAdapter(), it has an additional argument for the object that originally received the request:

public Object getAdapter(Object o, Class adapter) {
  if (adapter == IPropertySource.class)
    return new FilePropertySource((IFile)o);
  return null;
}

Next we have to register the factory for our desired type (IFile) with the AdapterManager. This has to occur early enough so that calls to getAdapter() return the correct result. This is commonly done in a plug-in's startup() method or in a static initializer. Here is a a corresponding code snippet:

IAdapterManager manager = Platform.getAdapterManager();
IAdapterFactory factory = new FileAdapterFactory();
manager.registerAdapters(factory, IFile.class);

Figure 31.5 illustrates these relationships.

Figure 31.5. Register Adapter Factories with the Platform

Now we have added an adapter factory. However, unless it gets an opportunity to participate in the getAdapter() requests, we haven't made any progress. Therefore, the getAdapter() invoked on IFile objects has to enable adapter contributions from the adapter manager (the Invitation Rule). The IFile interface is implemented in File. Figure 31.6 illustrates its type hierarchy.

Figure 31.6. IFile Type Hierarchy

The class File descends from Resource, which descends from the class PlatformObject. PlatformObject implements IAdaptable and forwards getAdapter() invocations to the Platform's adapter manager (see Figure 31.7). If you cannot derive from PlatformObject, you invite others to contribute adapters by calling:

Platform.getAdapterManager().getAdapter(this, adapter);

Figure 31.7. IAdapterFactory Returns Extensions for a Given Class

Once we have done all this, clients can call getAdapter(IPropertySource.class) without having to worry whether the interface is provided by the class itself or whether it was added externally.

Figure 31.8 shows the implementors of IAdapterFactory in Eclipse.

Figure 31.8. IAdapterFactory Type Hierarchy

Here are some points about the extension mechanism:

Extension Object—implemented as IAdaptable, IAdapterManager, and IAdapterFactory—furthers Eclipse's goal of supporting unanticipated extension by allowing contributors to extend the classes an object can pretend to be. While more complicated than just using objects, the extra complexity is balanced by the additional flexibility.