EMF/EMF 2.3/Edit API Source Incompatibility

During the move to generics APIs in EMF 2.3, overly restrictive types were mistakenly used in a number of related EMF.Edit APIs. As of March 22, 2007, those types have been changed. This constitutes a source-incompatibility for current users of the EMF 2.3 development stream, first appearing in the I200703221305 integration build. For those following only the milestone builds, it will appear first in M6.

These changes were made in bug 178708.

API Changes

The following changes were made to APIs.

EditingDomain (and its AdapterFactoryEditingDomain implementation)

Collection<CommandParameter> getNewChildDescriptors(Object object, Object sibling); →
Collection<?> getNewChildDescriptors(Object object, Object sibling);

IEditingDomainItemProvider (and its various implementations)

Collection<CommandParameter> getNewChildDescriptors(Object object, EditingDomain editingDomain, Object sibling); →
public Collection<?> getNewChildDescriptors(Object object, EditingDomain editingDomain, Object sibling);

ItemProviderAdapter (and its various subclasses)

void collectNewChildDescriptors(Collection<CommandParameter> newChildDescriptors, Object object) →
void collectNewChildDescriptors(Collection<Object> newChildDescriptors, Object object)

(...in addition to the change inherited from IEditingDomainItemProvider, above.)

Required Client Updates

Because these changes are source-incompatible, clients following the 2.3 development stream will need to make corresponding changes to their code in order to continue compiling. In general, regenerating the edit and editor projects should suffice, though for models with "Creation Commands" disabled, no changes should be needed.

Look for any remaining errors after regenerating the code. Corresponding changes may also be needed in hand-written or hand-modified code. This section describes the two kinds of changes.

Item Providers

Change the signature of any getNewChildDescriptors() or collectNewChildDescriptors() overrides to the new one above. The implementations likely will not have to change at all, as any Collection can be returned as a Collection<?> and any object can be added to a Collection<Object>.

For example, change this:

/**
 * generated NOT
 */
protected void collectNewChildDescriptors(Collection<CommandParameter> newChildDescriptors, Object object)
{
  super.collectNewChildDescriptors(newChildDescriptors, object);
  newChildDescriptors.add(...);
  ...
}

To this:

/**
 * generated NOT
 */
protected void collectNewChildDescriptors(Collection<?> newChildDescriptors, Object object)
{
  super.collectNewChildDescriptors(newChildDescriptors, object);
  newChildDescriptors.add(...);
  ...
}

Action Bar Contributors

Change code calling EditingDomain.getNewChildDescriptors() to handle the new Collection<?> return type. For example, if its result is assigned to a variable, as in selectionChanged():

/**
 * generated NOT
 */
public void selectionChanged(SelectionChangedEvent event)
{
  ...
  Collection<CommandParameter> newChildDescriptors = null;
  Collection<CommandParameter> newSiblingDescriptors = null;
  ...

  newChildDescriptors = domain.getNewChildDescriptors(object, null);
  newSiblingDescriptors = domain.getNewChildDescriptors(null, object);
  ...
}

The variable's type must be changed:

/**
 * generated NOT
 */
public void selectionChanged(SelectionChangedEvent event)
{
  ...
  Collection<?> newChildDescriptors = null;
  Collection<?> newSiblingDescriptors = null;
  ...

  newChildDescriptors = domain.getNewChildDescriptors(object, null);
  newSiblingDescriptors = domain.getNewChildDescriptors(null, object);
  ...
}

This shouldn't cause any problems, as the collection returned by this API should only be inspected, never added to.

Also, if the result is passed to a method, such as generateCreateChildActions():

/**
 * generated NOT
 */
protected Collection<IAction> generateCreateChildActions(Collection<? extends CommandParameter> descriptors, ISelection selection)
{
  Collection<IAction> actions = new ArrayList<IAction>();
  if (descriptors != null)
  {
    for (CommandParameter descriptor : descriptors)
    {
      ...
    }
  }
return actions;
}

The method's signature must be changed:

/**
 * generated NOT
 */
protected Collection<IAction> generateCreateChildActions(Collection<?> descriptors, ISelection selection)
{
  Collection<IAction> actions = new ArrayList<IAction>();
  if (descriptors != null)
  {
    for (Object descriptor : descriptors)
    {
      ...
    }
  }
return actions;
}

Although the change in type propagates into the for loop, this shouldn't cause any problem, as the method usually just passes the arbitrary descriptor objects on to the actions it creates. Should you wish to operate on a descriptor specifically as a CommandParameter, you should do an instanceof check and cast, just as in EMF 2.2 and earlier. The same change is required in generateCreateSiblingActions().