GEF/GEF4/Common

Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in the original wiki page.

Introduction

The GEF4 Common component provides key concepts and infrastructure to be potentially used by all other GEF4 components.

Activate

package: org.eclipse.gef4.common.activate

Adapt

package: org.eclipse.gef4.common.adapt

The adapt package provides a modernized interpretation of the adaptable objects pattern, as traditionally supported by the Eclipse Core Runtime. In contrast to the "original" pattern, it allows:

to register and retrieve adapters by means of a TypeToken key as an alternative to a Class key, which ensures that adapters with generic types can also be registered and retrieved in a type-safe manner, and
to (optionally) register and retrieve adapters via an additional role, which allows to register multiple adapters of the same type (using different roles) for an adaptable, and
to ensure that adapters will obtain a back-reference to their adaptables if this needed.

The first two parts are realized by registering and retrieving adapters via an AdapterKey, which combines a type key (Class or TypeToken) with an (optional) role, instead of a Class key. The transferred getAdapter(Class<? super T>) method now is just a convenience operation that will retrieve the adapter registered under the default role (or the only adapter registered under the given Class key, if there is only one adapter for that type key). Support for type-safe registration and access of adapters with generic types is realized by supporting a TypeToken key instead of Class key. An adapter can thus be registered and retrieved in various ways:

  // register and retrieve adapter 'a' with raw type 'A' under 'default' role (traditional adaptable objects pattern).
  adaptable.setAdapter(A.class, a); 
  A a = adaptable.getAdapter(A.class);
 
  // register and retrieve adapter 'a' with generic type 'A<T>' under 'default' role
  adaptable.setAdapter(new TypeToken<A<T>>(){}, a);
  A<T> a = adaptable.getAdapter(new TypeToken<A<T>>(){});
 
  // register an adapter with a raw type under role 'a1'
  adaptable.setAdapter(AdapterKey.get(A.class, "a1"));
  A a = adaptable.getAdapter(AdapterKey.get(A.class));
 
  // register an adapter with a generic type under role 'a1'
  adaptable.setAdapter(AdapterKey.get(new TypeToken<A<T>>(){}, "a1"));
  A a = adaptable.getAdapter(AdapterKey.get(new TypeToken<A<T>>(){}, "a1"));

The latter part is realized by formalizing the back reference from the adapter to the adapter through a respective interface. That is, if an adapter that is set/unset at an adaptable implements IAdaptable.Bound, the adaptable is responsible of setting/unsetting a back reference to itself on the adapter:

public <T> void setAdapter(AdapterKey<? super T> key, T adapter) {
  ...
  if (adapter instanceof IAdaptable.Bound) {
    ((IAdaptable.Bound<A>) adapter).setAdaptable(this);
  ...
}
 
public <T> T unsetAdapter(AdapterKey<? super T> key) {
  ...
  if (adapter instanceof IAdaptable.Bound) {
    ((IAdaptable.Bound<A>) adapter).setAdaptable(null);
  }
  ...
}